xuniwattoo

Global Shopaholics MCP server

Community xuniwattoo
Updated

Global Shopaholics MCP server: buy from any US store and ship worldwide (rates, landed cost, assisted purchase, tracking)

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.

Install in CursorInstall in VS CodeInstall in VS Code InsidersClaude 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: 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

MCP Server · Populars

MCP Server · New

    IBM

    IBM Aspera CLI

    IBM Aspera CLI (ascli): the automation interface for IBM Aspera, from command line to AI agents. Transfers, packages, files and administration of Aspera on Cloud, Faspex, HSTS, Node, Shares, Console, Orchestrator. MCP server.

    Community IBM
    Nimbleway

    WebRouter

    WebRouter is an open source standard that connects your agent to the web

    Community Nimbleway
    frontman-ai

    frontman

    The AI agent that lives in your framework/browser

    Community frontman-ai
    Laksh-star

    Screenward

    Movie and TV discovery, watch planning, and streaming availability—for browsers and MCP clients.

    Community Laksh-star
    codescene-oss

    CodeHealth MCP Server

    The CodeScene MCP Server exposes CodeScene’s Code Health analysis as local AI-friendly tools.

    Community codescene-oss