You can browse Shopee Brasil affiliate offers, generate tracked affiliate links, pull commission reports, and keep a local observation history — all through an MCP server that runs in synthetic fixture mode by default or live mode with your own Shopee Open API credentials.
Check status: affiliate_status shows mode, local account reference, available tools and whether history is enabled (it does not authenticate you).
Find products: search_offers by keyword, shop, category, AMS/key-seller and sort order, with images, discounts, categories and commission components; get_offer re-queries a specific item/shop.
Explore shops and campaigns: search_shop_offers (shop type, commission, remaining budget) and search_campaign_offers (Shopee campaigns, category/collection, period).
Work with official catalogs: list_product_feeds (FULL/DELTA) and get_product_feed for paged datafeed rows, with JSON numbers kept as strings for precision.
Generate affiliate links: generate_affiliate_link (up to 5 ordered subIDs, expected account reference) and generate_affiliate_links_batch (up to 20 links, validated up front, stops on first error).
Handle product URLs: parse_product_url extracts item/shop IDs and builds a canonical URL offline; resolve_product_url follows short links after validating each redirect.
Analyze commissions: get_conversion_report (unvalidated conversions), get_validated_report (by validation ID from the billing panel; not proof of payment), and summarize_report grouped by raw subID, campaign, UTC day, product or shop.
Export data: export_data returns CSV or JSON for up to 500 caller-supplied rows, neutralizing spreadsheet formulas in CSV and never writing files.
Track price history: observe_offer records a new observation in the optional local SQLite history, and get_offer_history reads observations back, separated by account, mode, item and shop.
Connect how you like: stdio (with run.py --mode live) or experimental Streamable HTTP with an OAuth screen, encrypted credential/session storage and per-connection accounts.
Caveats: fixture mode is synthetic with no external calls; live mode needs your own credentials and verified profile; commission values are estimates, complete=false means partial results, and HTTP transport is experimental and should stay behind HTTPS on a private VPS.
Integrates with the Shopee Brasil Affiliate Open API, providing tools for affiliate product search, offer details, shop and campaign offers, product feeds, affiliate link generation, conversion and validated reports, URL parsing, and local offer-history observation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Shopee Affiliate MCP search Shopee Brasil for bluetooth earbuds with high commission"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor MCP em Python para a Open API de Afiliados Shopee Brasil. Expõe 17 ferramentas por stdio ou Streamable HTTP com OAuth e usa consultas GraphQL assinadas com App ID e Secret da conta configurada.
O modo padrão é fixture: produtos sintéticos e nenhuma chamada externa. O modo live exige credenciais e o perfil administrativo oficial. Os contratos foram conferidos no portal brasileiro em 2026-10-01. As novas operações foram testadas com respostas simuladas; a aceitação real depende das permissões da conta.
Projeto independente, sem vínculo, endosso ou suporte oficial da Shopee. Licença MIT. Cada instalação precisa das próprias credenciais e do acesso à Open API de afiliados; o repositório não fornece uma conta nem um serviço compartilhado. A licença do código não concede direitos sobre dados, marcas ou serviços da Shopee.
O modo live pode devolver links com atribuição, identificadores de pedidos, subIDs e valores de comissão. Esses resultados e os exports devem ser tratados como dados privados da conta. Revise conversas, logs e arquivos antes de compartilhá-los. O histórico opcional fica no SQLite local. Publicar o código não publica esses dados, mas o cliente MCP pode guardar as respostas. Veja orientações de segurança.
Esta versão é inicial: as novas ferramentas passaram em testes simulados e ainda precisam de validação com a API real. HTTP permanece experimental e local; não exponha esse transporte na internet.
Related MCP server: shopee-mcp
Ferramenta | Função |
| Modo, referência local da conta, ferramentas e histórico habilitado; não autentica sozinho |
| Produtos por palavra-chave, loja, categoria, AMS/key seller e ordenação; imagens, desconto, categorias e componentes de comissão |
| Consulta atual do produto por item/shop IDs |
| Ofertas de lojas, tipo de loja, comissão e faixa de orçamento restante |
| Campanhas Shopee, categoria/coleção, comissão e período |
| Catálogos oficiais FULL/DELTA |
| Página de catálogo por datafeed ID e offset; colunas JSON preservadas |
| Link oficial com até cinco subIDs ordenados e conta esperada |
| Até 20 links; valida tudo antes de enviar e para no primeiro erro |
| Extrai IDs de URLs de produto e gera URL canônica; sem acesso à rede |
| Resolve link curto, validando cada destino antes de acessá-lo |
| Conversões e comissões reportadas ainda não validadas |
| Relatório validado por validation ID obtido no faturamento |
| Resumo por subID bruto, campanha, dia UTC, produto ou loja |
| CSV/JSON dos registros fornecidos; CSV neutraliza fórmulas |
| Coleta e grava uma observação de produto no histórico opcional |
| Histórico local separado por conta, modo, item e loja |
Para uso pessoal em Codex, Hermes e Claude Code, siga PRIVATE.md. O formulário exige uma chave privada antes de autorizar as credenciais Shopee.
Para subir no Coolify, siga o guia de configuração.
O transporte oauth-http oferece uma única tela com App ID e App Secret. Não exige cadastro ou senha adicional. Valida o acesso à Shopee antes de autorizar o cliente. As credenciais e sessões ficam criptografadas em SQLite num volume persistente e sobrevivem a reinícios; o servidor entrega tokens próprios ao cliente MCP.
Hospede atrás de HTTPS na VPS e configure MCP_PUBLIC_URL e SHOPEE_VERIFIED_PROFILE. Cada conexão usa sua própria conta. Conexões com as mesmas credenciais compartilham o cliente e os controles locais. Histórico SQLite fica desabilitado neste transporte.
Veja o guia de conexão remota, o Compose e o exemplo Hermes com OAuth. Esta integração é experimental e passou em testes simulados; a conexão real pelo ChatGPT/Hermes e a VPS ainda precisam de aceitação.
Python 3.11+:
python3 -m venv .venv
.venv/bin/python -m pip install -c requirements.lock -e .requirements.lock fixa o conjunto de dependências testado. Nenhum segredo deve estar no código, no Git ou nos argumentos de ferramentas.
.venv/bin/python local_test.py --fixture --extended
.venv/bin/python local_test.py --extendedO segundo comando pede App ID e App Secret com entrada oculta no Terminal e mantém os valores somente em memória. Verifica initialize/list/status, pesquisa/detalhe de produto, ofertas de lojas, campanhas e lista de feeds. Não gera links nem consulta relatórios financeiros automaticamente. Veja teste local.
Para iniciar um servidor stdio, o cliente MCP deve executar:
.venv/bin/python run.py --mode liveO processo espera mensagens MCP e não mostra um menu. Ele recebe:
Variável | Uso |
| App ID da Open API de afiliados |
| Secret da mesma aplicação |
| Rótulo local, ASCII alfanumérico/underscore/hífen, até 64 caracteres |
| Caminho absoluto de |
| Opcional: caminho absoluto do SQLite de observações |
O servidor não carrega .env automaticamente. O arquivo .env.example contém somente nomes e caminhos de exemplo. Injete segredos pelo ambiente protegido do processo. Confirme no painel que a aplicação está associada à conta correta; o rótulo local não comprova titularidade.
Modelos: cliente MCP, Hermes. Substitua os caminhos pelo diretório de instalação e disponibilize as credenciais ao processo.
Use timestamps Unix em segundos para purchase_time_start e purchase_time_end. get_validated_report recebe validation_id do painel. max_pages controla a paginação automática (1 por padrão, até 10); limit aceita até 500 registros. complete=false significa que o retorno cobre apenas parte do relatório. next_cursor deve ser usado em até 30 segundos e uma única vez. Consultas de relatórios não recebem retry automático; consultas iniciais sem cursor exigem intervalo maior que 30 segundos por tipo de relatório/processo.
Exemplo de argumentos para summarize_report:
{
"purchase_time_start": 1790812800,
"purchase_time_end": 1790899199,
"group_by": "utm_content",
"limit": 100,
"max_pages": 5
}SubID é preservado como utm_content bruto, sem presumir o separador entre slots. Resumos por produto/loja usam comissão dos itens, sem distribuir arbitrariamente a comissão líquida da conversão. Valores ausentes têm contadores explícitos. Comissão validada não comprova depósito recebido. clickTime representa o clique associado a uma conversão; não fornece todos os cliques da campanha.
IDs são strings e valores monetários são strings decimais. O feed preserva números JSON como strings para não perder precisão. Nos relatórios, ajustes monetários negativos são preservados. BRL é inferido do mercado brasileiro.
Configure SHOPEE_HISTORY_DB para habilitar as ferramentas de histórico. Somente observe_offer grava uma nova observação. Esse histórico começa quando você inicia a coleta; não recupera preços antigos anteriores a ela.
export_data recebe uma lista rows com até 500 objetos e format: "csv" ou "json". Retorna o conteúdo ao cliente sem aceitar caminhos de arquivo. O cliente pode salvar esse conteúdo como um artefato. Dados exportados têm origem caller_supplied_data.
Veja instalação na VPS. Para Hermes na mesma VPS, stdio dispensa porta pública. O Dockerfile roda como usuário sem privilégios e inicia em fixture por padrão. A CI valida o build Docker e initialize/list/status MCP dentro do container em fixture. A configuração HTTPS e o fluxo live ainda precisam de teste no destino.
O transporte private-http permanece experimental, restrito ao loopback e protegido por um token separado. Para conexão remota, use oauth-http atrás de HTTPS conforme o guia.
PYTHONPATH=src:tests .venv/bin/python -m unittest discover -s tests -vCI no GitHub testa Python 3.11 e 3.12. A verificação local passou em 77 testes, incluindo MCP stdio real, assinaturas, precisão, relatórios paginados, batch com resultado incerto, redirecionamentos e isolamento do histórico. O teste HTTP em memória ainda registra avisos de encerramento do SDK; detalhes em VERIFICATION.md.
Limites atuais: sem estoque/frete/cupons/avaliações textuais, publicação em redes sociais, compras, administração de vendedor ou métricas de todos os cliques. O escopo é a API de afiliados disponível à conta.
Implementação própria baseada na documentação oficial brasileira: produtos, lojas, campanhas, feeds, conversões, relatórios validados. Veja contratos e políticas locais.
Mostra modo e referência LOCAL da conta. Não autentica nem comprova titularidade na Shopee.
Inputs: no named parameters. Returns: data, mode, synthetic, account_reference
Retorna CSV ou JSON dos registros fornecidos, sem escrever arquivos; neutraliza fórmulas em CSV.
Inputs: rows (required), format (required). Returns: data, mode, synthetic, account_reference
Gera link SOMENTE via operação oficial verificada, para a referência de conta esperada e subIDs explícitos. Nunca publica. Fixtures recusam geração.
Inputs: sub_ids (required), origin_url (required), expected_account_reference (required). Returns: data, mode, synthetic, account_reference
Gera até 20 links oficiais sequencialmente; valida todo o lote antes do envio e interrompe em erro.
Inputs: links (required), expected_account_reference (required). Returns: data, mode, synthetic, account_reference
Consulta conversões e comissões ainda não validadas; paginação automática limitada e cursor de uso único/30s.
Inputs: purchase_time_end (required), purchase_time_start (required), limit, cursor, +5 more. Returns: data, mode, synthetic, account_reference
Reconsulta oferta por item_id e shop_id. Retorna nova observação; não garante estoque, frete ou comissão aprovada.
Inputs: item_id (required), shop_id (required). Returns: data, mode, synthetic, account_reference
Consulta observações coletadas neste servidor, separadas por conta e modo.
Inputs: item_id (required), shop_id (required), limit. Returns: data, mode, synthetic, account_reference
Obtém uma página do feed oficial; preserva IDs e decimais como strings.
Inputs: datafeed_id (required), limit, offset. Returns: data, mode, synthetic, account_reference
Consulta comissões validadas por validationId do painel de faturamento; não comprova pagamento.
Inputs: validation_id (required), limit, cursor, max_pages. Returns: data, mode, synthetic, account_reference
Lista catálogos oficiais FULL ou DELTA disponíveis para a conta.
Inputs: feed_mode. Returns: data, mode, synthetic, account_reference
Registra uma nova observação do produto em SQLite local habilitado pelo administrador.
Inputs: item_id (required), shop_id (required). Returns: data, mode, synthetic, account_reference
Extrai IDs de URL Shopee.
Inputs: url (required). Returns: data, mode, synthetic, account_reference
Resolve link curto Shopee, validando cada redirecionamento antes de consultar IDs.
Inputs: url (required). Returns: data, mode, synthetic, account_reference
Pesquisa campanhas e ofertas Shopee com categoria/coleção e período.
Inputs: page, limit, keyword, sort_type. Returns: data, mode, synthetic, account_reference
Pesquisa uma página; preço/comissão são observações estimadas. Modo fixture contém somente dados sintéticos.
Inputs: keyword (required), page, limit, cursor, +5 more. Returns: data, mode, synthetic, account_reference
Pesquisa ofertas de lojas, comissão, classificação e orçamento disponível.
Inputs: page, limit, keyword, shop_id, +3 more. Returns: data, mode, synthetic, account_reference
Agrupa conversões por subID bruto, campanha ou dia UTC; informa quando o total cobre apenas parte do relatório.
Inputs: purchase_time_end (required), purchase_time_start (required), limit, cursor, +6 more. Returns: data, mode, synthetic, account_reference
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 17 tools
Tools mostly target distinct resources: search_offers/search_shop_offers/search_campaign_offers differ by scope, and get_offer/observe_offer/get_offer_history differ by action. The two generate_affiliate_link variants and the report trio could be momentarily confused, but descriptions clarify their boundaries.
Almost all tools follow a verb_noun snake_case pattern (search_offers, get_offer, generate_affiliate_link, get_conversion_report). The lone deviation is the noun-only affiliate_status, which is a minor inconsistency.
17 tools is slightly heavy but each maps to a real affiliate workflow step (search, offer lookup, link generation, feeds, reports, URL parsing, observation history). Nothing appears redundant enough to trim.
The surface covers the affiliate lifecycle well: discovery (offers/shops/campaigns), link generation, feed access, reporting, and local observation history. Missing update/delete style operations and explicit account auth, but those are out of scope per descriptions.
Affiliate links, product search and offer posts for Shopee, Mercado Livre, Amazon and AliExpress.
Affiliate sales analytics across Shopee, AliExpress, Amazon, Mercado Livre and other marketplaces.
ScrapeCreators MCP — wraps the ScrapeCreators social-media + ad-library scraping API…
17 data tools in one MCP server, run on Apify: Google Shopping, Flights, Hotels, News, Images, Videos, Ads Transparency, Jobs and Trends; YouTube transcripts; AI visibility checks; Google Maps leads; App Store and Google Play reviews. Pay per result. Sign in with Apify (OAuth) or an API token.
