sellabot-mcp

An MCP server that exposes marketplace seller operations as tools Claude can call. Shopee first, designed to expand to Lazada and TikTok Shop via the same adapter contract.

Claude is the interface; sellabot-mcp is the automation layer. See CLAUDE.md for the full design.

What it can do

32 tools across products, pricing, inventory, customer service, orders & fulfillment, returns/cancellations/disputes, promotions, and shop info. The scope rule: anything a seller can do through the marketplace API that doesn't require physically moving goods.

Crucial actions (refunds, cancellations, disputes, booking shipments) are human-gated — the server previews the exact effect and waits for the seller's explicit approval before executing (see CLAUDE.md §3).

Setup

npm install
cp .env.example .env      # fill in SHOPEE_PARTNER_ID/KEY and a TOKEN_ENCRYPTION_KEY
npm run authorize         # one-time: opens the Shopee OAuth flow, stores tokens
npm run build

npm run authorize prints an authorization URL; approve it in the browser, and the local callback captures the code, exchanges it for tokens (stored encrypted), and prints the SHOPEE_SHOP_ID to add to .env.

Run

npm start                 # serves over stdio
npm run dev               # watch mode (tsx)

Set READ_ONLY=true to expose only the get_* tools — safe for testing against a live shop.

Connect to Claude

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "sellabot": {
      "command": "node",
      "args": ["C:\\Users\\Rexton\\sellabot_mcp\\dist\\index.js"],
      "env": { "SHOPEE_PARTNER_ID": "…", "SHOPEE_PARTNER_KEY": "…", "SHOPEE_REGION": "MY", "SHOPEE_ENV": "production", "SHOPEE_SHOP_ID": "…", "TOKEN_ENCRYPTION_KEY": "…" }
    }
  }
}

Claude Code:

claude mcp add sellabot -- node C:\Users\Rexton\sellabot_mcp\dist\index.js

Develop

npm run typecheck    # type-check src + scripts
npm test             # signing golden-vector tests

Project layout

src/
  index.ts           entry (stdio)
  server.ts          wiring + MCP elicitation bridge
  config.ts          env validation (Zod)
  core/              models, errors, http, token-store, consent, audit, platform, registry
  platforms/shopee/  sign, auth, client, mappers, adapter (the only Shopee-aware code)
  tools/             platform-agnostic tool definitions
scripts/authorize.ts one-time OAuth flow

Adding a platform = implement Platform in src/platforms/<name>/ and register it. No tool changes.