Shopee Seller MCP

Read-only Shopee Open Platform data (Ads, orders, products, finance) for AI agents, across several shops, over MCP.

An unofficial Model Context Protocol server for the Shopee Open Platform. Connect ChatGPT, Claude, Claude Code, Codex, Cursor, VS Code, Gemini CLI, n8n or your own agents to one or more Shopee shops and ask questions such as "compare Ads spend and direct GMV for store-a and store-b last month". Not affiliated with or endorsed by Shopee.

Features

• Read-only by design. Multi-shop and remote modes expose read endpoints only; write tools cannot be enabled there.

• Multi-shop. Each shop has its own credentials and an alias (store-a, store-b). Every call names its shop explicitly; there is no default shop and no fallback.

• Ads tools. get_ads_balances and get_ads_summary (CPC expense, direct/broad orders and GMV) with explicit handling of missing or partial data.

• Typed catalog tools. Individual Shopee v2 read endpoints (products, orders, payments, returns, logistics, Ads, AMS and more) as typed MCP tools.

• Remote HTTP mode. Stateless Streamable HTTP at /mcp with OAuth 2.1 (ChatGPT and Claude.ai connectors) and static bearer tokens (CLIs, IDEs, n8n, scripts).

• Browser shop onboarding. Add or remove shops at /admin/shops without SSH. Changes apply without a restart.

• One-command client setup. shopee-mcp-http connect <client> prints or merges the right config for each MCP client.

• Self-hosted. Run it on your own VPS (systemd and nginx) or any Docker host with a persistent volume.

Related MCP server: MCP Shopline

How it works

flowchart LR
    subgraph Clients
        A["ChatGPT / Claude.ai<br/>(OAuth 2.1)"]
        B["Claude Code / Codex / Cursor<br/>VS Code / Gemini CLI / n8n<br/>(bearer token)"]
    end
    subgraph Server["shopee-mcp-http (your host)"]
        M["/mcp<br/>stateless MCP"]
        O["/authorize, /token<br/>OAuth server"]
        S["/admin/shops<br/>shop onboarding"]
        R[("shop registry<br/>owner-only env files")]
        D[("auth.db<br/>hashed tokens")]
    end
    P["Shopee Open Platform API"]
    A -->|OAuth| O --> D
    A -->|Bearer| M
    B -->|Bearer| M
    M --> R --> P
    S -->|seller authorization| P
    S --> R

1. You register a Shopee Open Platform app and deploy this server with its partner credentials.

2. At /admin/shops you add shops. The seller approves your app on Shopee and is redirected back to /callback; the server exchanges the code and stores the shop's tokens in an owner-only file.

3. MCP clients connect to /mcp with OAuth or a bearer token and call tools with an explicit shop alias. Shopee access tokens are refreshed automatically.

Quick start

All remote options need a public https URL. It is the OAuth issuer and the base of the Shopee redirect URL (<public-url>/callback).

Free hosting tiers without persistent storage are not supported yet: Shopee refresh tokens rotate and must survive restarts.

(b) Docker

docker build -t shopee-seller-mcp .
docker run -d --name shopee-mcp -p 8080:8080 -v shopee-mcp-data:/data \
  -e SHOPEE_MCP_PUBLIC_URL=https://mcp.example.com \
  -e SHOPEE_MCP_ADMIN_PASSPHRASE='a-long-random-passphrase' \
  -e SHOPEE_PARTNER_ID=123456 -e SHOPEE_PARTNER_KEY='your-partner-key' \
  shopee-seller-mcp

Put a TLS reverse proxy for https://mcp.example.com in front of port 8080. Every variable is listed in .env.example.

Shopee Open Platform setup

1. Create a developer account in the Shopee Open Platform console and complete verification.

2. Create an app of type Seller In-House System (for shops you operate). Note the sandbox (test) and live Partner ID and Partner Key.

3. Set the app's redirect URL domain to your public URL, for example https://mcp.example.com. Sellers are sent back to https://mcp.example.com/callback.

4. Request the API permissions you need (for example Ads, Product, Order, Payment).

5. Test with a sandbox shop, then submit the app to Go Live and use the live credentials for real shops.

Partner credentials are read only from the server environment: SHOPEE_PARTNER_ID/SHOPEE_PARTNER_KEY (live), and optionally SHOPEE_SANDBOX_PARTNER_ID/SHOPEE_SANDBOX_PARTNER_KEY. When the sandbox pair is not set, sandbox onboarding uses the main pair. Credentials are never entered in the browser.

Adding shops

Open https://<your-host>/admin/shops and sign in with the operator passphrase.

• Add shop: choose an alias (for example store-a), the environment (sandbox or production) and the authorization period, then click Continue to Shopee. Sign in as the seller and approve the app. You return to /callback and the shop is available to MCP clients immediately.

• Main account (several shops at once): on the Shopee login page, sign in with the main account that manages your shops and tick the shops to authorize. Shopee returns a main_account_id instead of a shop_id. You then see the authorized shop IDs (with shop names when Shopee returns them), pick which ones to add and give each an alias. The alias you typed in Add shop is used as the default prefix. Each selected shop gets its own credential file and is refreshed independently.

• Invite link (remote seller): under Invite links, pick the environment (live by default), a lifetime (1 hour to 7 days) and an optional label, then click Create invite link. The link (https://<your-host>/invite/<token>) is shown once; send it to the person who holds the seller's main account or shop account. They open it, click Continue to Shopee and approve there. They never see the passphrase or the admin page. Their shops are added automatically with aliases from the shop name (or shop-<shop_id>); shops that are already connected are skipped. A link works once (after at least one shop is saved) and can be revoked while it is active. A Shopee sub account cannot approve access.

• Rename: change any shop's alias (for example an automatic alias from an invite). The credential file stays the same.

• Remove shop: removes the alias and deletes its stored tokens.

• The list shows alias, environment, authorization expiry and, for shops added through an invite, the invite label. To renew, remove the shop and add it again before the authorization expires.

The shopee-auth CLI flow and a hand-written shops file still work; see docs/DEPLOY.md.

Connecting clients

The MCP endpoint is https://<your-host>/mcp.

Bearer tokens come from shopee-mcp-http token create --auth-file <auth.db> --label <name> and are printed once.

export SHOPEE_MCP_TOKEN=smcp_...
shopee-mcp-http connect cursor --url https://mcp.example.com/mcp           # print snippet and target path
shopee-mcp-http connect cursor --url https://mcp.example.com/mcp --write   # merge into ~/.cursor/mcp.json (with backup)

Generated configs reference $SHOPEE_MCP_TOKEN instead of storing the token, unless you pass --inline-token. Without Python, use scripts/install-agent.sh for Claude Code, Codex and Cursor. More in docs/INTEGRATIONS.md.

Tools

Example: get_ads_summary with {"shops": ["store-a", "store-b"], "start_date": "01-10-2026", "end_date": "31-10-2026"}.

Data semantics

• Direct and broad attribution stay separate. They are never added together, and CPC numbers are never combined with GMV Max or other campaign types.

• Long ranges are chunked. Two or more days use the daily endpoint in chunks of at most 30 days; a single day uses the hourly endpoint. One call may span up to 366 days and 60 Shopee requests. Shopee keeps about six months of Ads history, so older dates come back as missing.

• Gaps are explicit. Failed or missing dates are listed and never treated as zero. totals is set only when the whole period is covered; otherwise partial_totals covers covered_dates.

• No cross-shop sums. Each shop is reported separately.

• No currency. Shopee's Ads APIs do not return a currency; values are in each shop's local currency.

• Field names are Open API names. Reconcile with Seller Centre before using numbers in reports.

Security model

• Read-only in multi-shop and HTTP modes (--allow-write is rejected).

• Every /mcp request needs a bearer token: a static token or an OAuth access token bound to this server's resource URL. Only SHA-256 hashes are stored, in an owner-only SQLite file.

• OAuth 2.1 with PKCE S256, dynamic client registration limited to ChatGPT, Claude and loopback redirect URIs, rotating refresh tokens, and an operator-passphrase consent page.

• /admin/shops uses the same passphrase, single-use CSRF tokens and throttling as the consent page. Shop authorization state values are single-use and bound to the admin session that started them.

• Shop tokens live in owner-only (0600) files in a 0700 directory. Codes, tokens, passphrases and query strings are never logged.

• The server binds 127.0.0.1 unless --host is given. A non-loopback bind requires an https public URL, and client-IP headers are then trusted only from --trusted-proxy networks.

Details: docs/SECURITY.md.

Limitations and disclaimer

• Unofficial project; not affiliated with, endorsed by or supported by Shopee. Shopee names and trademarks belong to their owners.

• Available endpoints depend on your app's permissions, region and account type. Not every catalog endpoint has been verified in every region.

• Ads summaries have not been reconciled with Seller Centre in every market. Check definitions before reporting.

• Shop tokens are access-controlled on disk but not encrypted. Secure the host, the disk and its backups.

• Run one instance per data directory: admin sessions and pending shop authorizations are kept in memory.

• Review Shopee's terms and data policies before production use.

License

Released under the MIT License.