Global Shopaholics MCP

Global Shopaholics için, ABD merkezli bir paket yönlendirme hizmeti sunan uzak MCP sunucusu. Yapay zekâ ajanlarının uluslararası gönderim ücretlerini öğrenmesini, toplam maliyeti (gümrük vergileri ve vergiler dâhil) tahmin etmesini, ABD mağazalarından destekli satın alma talebinde bulunmasını ve gönderileri takip etmesini sağlar.

Barındırılan MCP Sunucusu

npx add-mcp 'https://mcp.globalshopaholics.com/mcp'

Claude Code, Codex, Cursor ve daha fazlasına kurulur

Dokümantasyon

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