mcp-shopee-seller 0.4.0

MCP server para vendedores Shopee (Open Platform API v2) — pedidos, produtos, finanças, promoções, chat e ads via agentes de IA. Roda 100% local.

mcp-shopee-seller

Servidor MCP para a Shopee Open Platform API v2. Permite que agentes de IA (Claude Code, Codex, Cursor, Antigravity etc.) administrem sua loja Shopee: pedidos, produtos/estoque, logística, finanças, promoções, chat e ads.

Roda 100% no seu computador — os dados da loja trafegam direto entre o seu PC e a Shopee; tokens ficam salvos localmente no seu perfil de usuário.

Tools (42)

Módulo	Tools
Conexão de loja	connect_shop, connect_status, connect_shop_manual, disconnect_shop, list_authorized_shops
Pedidos	list_orders, get_order_details
Produtos & estoque	list_products, get_product_details, update_stock, update_price
Catálogo (criar/editar anúncios)	upload_product_image, search_categories, get_category_requirements, create_product, update_product, set_product_status
Relatórios analíticos	get_sales_performance_report, get_unsold_products_report
Logística	get_shipping_parameter, ship_order, get_tracking_info, get_logistics_channels
Finanças	get_payout_detail, list_wallet_transactions
Promoções (vouchers)	list_vouchers, get_voucher, create_voucher, end_voucher
Chat (atendimento)	list_conversations, get_messages, send_message
Shopee Ads	get_ads_balance, get_ads_shop_info, get_ads_daily_performance, get_recommended_keywords, create_ads_campaign, pause_ads, resume_ads, delete_ads
Genérico / diagnóstico	shopee_api_call, shopee_status

Instalação

Pré-requisito único: uv (curl -LsSf https://astral.sh/uv/install.sh | sh).

Claude Code:

claude mcp add shopee --env MCP_BROKER_URL=... --env MCP_LICENSE_KEY=... -- uvx mcp-shopee-seller

Claude Desktop / Cursor / Antigravity (JSON de MCP servers):

{
  "mcpServers": {
    "shopee": {
      "command": "uvx",
      "args": ["mcp-shopee-seller"],
      "env": { "MCP_BROKER_URL": "...", "MCP_LICENSE_KEY": "..." }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.shopee]
command = "uvx"
args = ["mcp-shopee-seller"]
env = { MCP_BROKER_URL = "...", MCP_LICENSE_KEY = "..." }

Modos de operação

Modo	Variáveis	Para quem
broker (padrão)	MCP_BROKER_URL + MCP_LICENSE_KEY	Usuário final. A assinatura HMAC vem do serviço de licença; somente metadados (path, timestamp, shop_id) são enviados a ele — pedidos, produtos e valores nunca passam pelo broker.
local (avançado)	SHOPEE_PARTNER_ID + SHOPEE_PARTNER_KEY	Quem tem App próprio em open.shopee.com. Tudo 100% local, zero serviços de terceiros.

Variáveis opcionais: SHOPEE_ENV (live padrão | sandbox), SHOPEE_HOST (host regional), SHOPEE_SHOP_ID (loja padrão), SHOPEE_AUTH_PORT (porta do callback, padrão 38473), SHOPEE_TOKEN_FILE, SHOPEE_REDIRECT_URL.

Conectando sua loja (login)

Basta pedir ao agente: "conecte minha loja Shopee".

1. A tool connect_shop abre o navegador na página de autorização da Shopee.
2. Você entra como vendedor e autoriza (a senha nunca passa pelo MCP).
3. O agente chama connect_status e a loja fica pronta.

Os tokens ficam em ~/Library/Application Support/marketplace-mcp/shopee/ (macOS), %APPDATA%\marketplace-mcp\shopee\ (Windows) ou ~/.config/marketplace-mcp/shopee/ (Linux), com renovação automática do access token (4h). Multi-loja: repita connect_shop para cada conta; use shop_id nas tools para escolher a loja.

Sem navegador (SSH/headless): autorize em outra máquina e cole a URL de redirect na tool connect_shop_manual (ou use o CLI shopee-authorize).

Desenvolvimento

Este pacote faz parte do monorepo (workspace uv) junto com marketplace-mcp-core. Na raiz do repositório:

uv sync                                   # cria o venv do workspace
uv run mcp-shopee-seller                  # roda o servidor (stdio)
uv run shopee-authorize --list            # CLI de autorização

Modo local no dev: crie um .env com SHOPEE_PARTNER_ID, SHOPEE_PARTNER_KEY e SHOPEE_ENV=sandbox, e registre http://127.0.0.1:38473/callback como Redirect URL no painel do seu App.