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 a small sourced rules table and are always labelled estimates.
- 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
| Tool | What it does |
|---|---|
get_shipping_rates |
Live 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_cost |
Item + 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 (AO, SA, AE, GB, CA, AU, NG, PK, IN, BR, DE, FR, NL). Optional Easyship Tax & Duty API when EASYSHIP_API_KEY and an HS code are given. |
get_services_and_fees |
Services, plans (Basic free, Premium $9.99, Business $14.99) and published fees with source URLs + last-checked date. |
get_started |
How to get the free US address (sign-up: https://login.globalshopaholics.com/register) and next steps. |
request_assisted_purchase |
Sends 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. |
request_shipment_quote |
Same lead flow for manual quotes, labels, customs paperwork, freight; tag mcp-shipping-request. |
track_shipment |
Carrier 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.
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: 7 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, optional Easyship
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), duty rules (sourced), GS calculator country list
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