Repository avatar
Other Tools
v1.2.0
active

gs-mcp

io.github.xuniwattoo/gs-mcp

Buy from any US store for you: ship worldwide or in the US, find it cheaper, pay in crypto.

Documentation

Global Shopaholics MCP server

A public, remote Model Context Protocol server that lets any AI agent (Claude, ChatGPT, Cursor, Grok, …) help a person anywhere buy from any US store and ship it through Global Shopaholics (GS).

It only wraps what GS already has: the website's live rate engine, published fees/plans, the sign-up flow, the Assisted Purchase request process and carrier tracking. Duty/VAT figures come from GS's sourced per-country, per-product-category rules (87 countries; see docs/duties.md) and are always labelled estimates with a range.

  • Transport: Streamable HTTP (stateless, JSON responses) at /mcp, plus a stdio entry.
  • Runtime: web-standard Request/Response → runs on Cloudflare Workers (primary), Vercel, or any Node ≥ 20 host (Cloudways).
  • No auth for read tools. Lead tools are rate-limited per IP (hourly), per email (daily) and by a global daily cap; rate-lookup tools have a per-IP hourly cap. On Cloudflare Workers these limits live in a SQLite Durable Object; Node/Vercel fall back to a per-process in-memory limiter.

Tools

ToolWhat it does
get_shipping_ratesLive DHL / FedEx / UPS / USPS prices, transit times, max weight/size, insurance text and dimensional-weight flag from GS's rate engine (/wp-json/rate-calculator/v2/getrates), normalized and sorted.
estimate_landed_costItem + optional US sales tax + GS Assisted Purchase fee (0% when paid by bank transfer or crypto, otherwise 5% with a $5 minimum; expedited & executive per GS FAQ) + live shipping + estimated duty, VAT/GST and fees per item and product category (phones, laptops, clothing, shoes, cosmetics, perfume…) for 87 countries, with de minimis, CIF/FOB basis, courier regimes and who collects. Other countries: WITS tariff lookup (free) or the Easyship Tax & Duty API when EASYSHIP_API_KEY is set, cached permanently by country + HS6. Returns a typical estimate plus low–high range.
get_services_and_feesServices, plans (Basic free, Premium $9.99, Business $14.99) and published fees with source URLs + last-checked date.
get_startedHow to get the free US address (sign-up: https://login.globalshopaholics.com/register) and next steps.
request_assisted_purchaseSends a "buy it for me" request to GS (GoHighLevel and/or webhook), tag mcp-assisted-purchase; returns a reference id. Falls back to GS's Assisted Purchase page + prefilled email if no sink is configured.
find_lower_priceFind it cheaper at US stores. Google Shopping (US) via Serper: top offers sorted by price (store, price, link, rating, savings vs the current price), no affiliate links, sketchy sellers and outliers dropped. Indicative prices only. Cached 24 h, 10 searches/hour per client. Needs SERPER_API_KEY. Hands off to request_us_purchase / request_assisted_purchase.
request_us_purchaseUS domestic buy-for-me. GS buys from any US store and ships to a US address (incl. Hawaii, Alaska, Puerto Rico, APO/FPO, stores that won't ship to the customer). Inputs: product URLs, quantity, variant, max price, find_lower_price, ship-to state + ZIP, name, email. Same GHL lead flow; tags mcp-us-domestic (+ price-beat). Fee 0% for crypto/bank transfer, otherwise 5% with $5 minimum; crypto via create_crypto_payment once GS confirms the total. Prices are never guaranteed.
request_shipment_quoteSame lead flow for manual quotes, labels, customs paperwork, freight; tag mcp-shipping-request.
create_crypto_paymentCrypto checkout is live. Creates a BTCPay invoice (USD) for an amount GS has already quoted and returns checkout link, invoice id and expiry. 0% GS fee when paying by crypto. Capped at $10,000, rate limited, logged to the GHL contact (mcp-crypto-payment). Needs BTCPAY_URL, BTCPAY_STORE_ID, BTCPAY_API_KEY (key limited to create/view invoices).
get_crypto_payment_statusRead-only status of an invoice by id.
track_shipmentCarrier tracking URL (DHL/FedEx/UPS/USPS, auto-detected). GS has no public tracking page; customers also see status in their dashboard.

Resource: gs://about (markdown overview). Prompt: buy-and-ship.

Run locally

npm install
cp .env.example .env          # optional, every value has a default
npm run dev                   # Node server on http://localhost:8787/mcp
npm test                      # unit + in-process MCP tests (all network mocked)
npm run smoke                 # spawns the server, real HTTP MCP client, LIVE GS rates, lead sinks mocked
npm run cf:dev                # same code inside the Cloudflare Workers runtime (wrangler dev)
npm run stdio                 # stdio transport

npm run build && npm start runs the compiled Node server (dist/entry/node.js).

Connect an AI agent

Public MCP URL (Streamable HTTP, free, no sign-up, no auth): https://mcp.globalshopaholics.com/mcp. Fallback: https://gs-mcp.gshopaholics.workers.dev/mcp.

Install in Cursor Install in VS Code Install in VS Code Insiders Claude Desktop extension

Claude Code – plugin (adds the server plus a ship-from-us skill that tells Claude when to use it):

/plugin marketplace add xuniwattoo/gs-mcp
/plugin install global-shopaholics@global-shopaholics

On Claude Code 2.1.275+ one step works: /plugin install global-shopaholics --marketplace xuniwattoo/gs-mcp

Or just the server: claude mcp add --transport http global-shopaholics https://mcp.globalshopaholics.com/mcp

Claude.ai / Claude Desktop – Settings → Connectors → Add custom connector → name Global Shopaholics, URL https://mcp.globalshopaholics.com/mcp. Or download global-shopaholics.mcpb and double-click it (Claude Desktop → Settings → Extensions). Manual config for older builds:

{ "mcpServers": { "global-shopaholics": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.globalshopaholics.com/mcp"] } } }

ChatGPT – Settings → Apps & Connectors → Advanced settings → turn on Developer mode → Create → MCP server URL https://mcp.globalshopaholics.com/mcp, authentication No authentication.

Codex (CLI, IDE, ChatGPT desktop) – codex mcp add global-shopaholics --url https://mcp.globalshopaholics.com/mcp, or in ~/.codex/config.toml:

[mcp_servers.global-shopaholics]
url = "https://mcp.globalshopaholics.com/mcp"

A Codex/ChatGPT plugin package (server + skill) is in plugins/openai/global-shopaholics.

Cursor – click the button above, or ~/.cursor/mcp.json:

{ "mcpServers": { "global-shopaholics": { "url": "https://mcp.globalshopaholics.com/mcp" } } }

Direct deeplink: cursor://anysphere.cursor-deeplink/mcp/install?name=global-shopaholics&config=eyJ1cmwiOiJodHRwczovL21jcC5nbG9iYWxzaG9wYWhvbGljcy5jb20vbWNwIn0=

VS Code (Copilot agent mode) – click the button above, or code --add-mcp '{"name":"global-shopaholics","type":"http","url":"https://mcp.globalshopaholics.com/mcp"}', or .vscode/mcp.json:

{ "servers": { "global-shopaholics": { "type": "http", "url": "https://mcp.globalshopaholics.com/mcp" } } }

Windsurf – ~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "global-shopaholics": { "serverUrl": "https://mcp.globalshopaholics.com/mcp" } } }

Gemini CLI – gemini mcp add --transport http global-shopaholics https://mcp.globalshopaholics.com/mcp, or ~/.gemini/settings.json:

{ "mcpServers": { "global-shopaholics": { "httpUrl": "https://mcp.globalshopaholics.com/mcp" } } }

Cline / Roo / other clients – add a remote server of type Streamable HTTP with URL https://mcp.globalshopaholics.com/mcp.

curl

curl -s -X POST https://mcp.globalshopaholics.com/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_shipping_rates","arguments":{"country":"AO","weight":5,"unit":"kg"}}}'

Discovery

  • Server card: https://mcp.globalshopaholics.com/mcp/server-card (also /.well-known/mcp/server-card.json)
  • AI catalog: https://mcp.globalshopaholics.com/.well-known/ai-catalog.json
  • https://mcp.globalshopaholics.com/llms.txt
  • Official MCP Registry name: io.github.xuniwattoo/gs-mcp (server.json)
  • Copies for globalshopaholics.com: site-files/

Configuration

See .env.example (Node/Vercel) or wrangler.toml [vars] + wrangler secret put (Workers). Full list in docs/deploy.md.

Layout

src/config.ts            env → typed config (works with Workers env or process.env)
src/server.ts            McpServer: 11 tools, resource, prompt (zod schemas)
src/http.ts              stateless web-standard Streamable HTTP handler, CORS, /health
src/entry/worker.ts      Cloudflare Workers entry
src/entry/node.ts        plain Node HTTP entry (Cloudways/VPS)
src/entry/stdio.ts       stdio entry
api/mcp.ts, vercel.json  Vercel entry
src/lib/rates.ts         GS rate engine client + normalizer + 10-min cache
src/lib/landed.ts        landed-cost estimator, GS fee logic
src/lib/duty-engine.ts   per-item duty/tax engine (profiles + WITS MFN rates)
src/lib/duty-fallback.ts fallback lookup (Easyship → WITS) + permanent DO cache
src/lib/leads.ts         GoHighLevel v2 / webhook lead sinks + fallback
src/lib/ratelimit.ts     limiter contract + in-memory fallback
src/lib/limiter-do.ts    SQLite Durable Object limiter (Workers)
src/lib/validate.ts      lead-input sanitization and checks
src/lib/tracking.ts      carrier detection + URLs
src/data/*.ts            GS facts (sourced), GS calculator country list
src/data/duty/           duty profiles, categories, WITS tariff snapshot, GS order priority
test/                    vitest tests + fixture (real GS response, Angola 5 kg)
scripts/smoke.ts         end-to-end smoke test
docs/                    website page copy, deploy guide
src/discovery.ts         server card, AI catalog, llms.txt (served by the Worker)
site-files/              discovery files to publish on globalshopaholics.com
.claude-plugin/          Claude Code marketplace (plugins/claude/global-shopaholics)
plugins/openai/          Codex / ChatGPT plugin package
mcpb/                    Claude Desktop extension (stdio relay to the remote server); `npm run mcpb:build`
server.json              MCP registry manifest

No installation packages available.