MCP Mercado Livre

Servidor MCP (Model Context Protocol) em TypeScript para a API do Mercado Livre, focado em vendedores. Permite que LLMs (Claude Desktop, Kimi Code, Cursor etc.) pesquisem o marketplace, publiquem e gerenciem anúncios, respondam perguntas, acompanhem pedidos, envios, reclamações, reputação, catálogo, promoções e muito mais — tudo por linguagem natural.

Projeto open source (MIT) — contribuições são bem-vindas! Veja Contribuindo.

Destaques

• 42 ferramentas cobrindo o ciclo completo do vendedor (busca, publicação, gestão, pós-venda, reputação, catálogo, promoções, Ads, Full, Shops)

• OAuth 2.0 com refresh automático — tokens de 6h renovados 5 min antes de expirar, com persistência da rotação do refresh token

• Suporte a Docker Compose — rode o servidor e a autenticação em containers, com tokens em volume persistente

• Erros graciosos — falhas da API (validação, escopo, permissão) retornam a mensagem do Mercado Livre de forma clara, sem derrubar o servidor

• Zero dependências além do essencial — apenas @modelcontextprotocol/sdk e zod; HTTP via fetch nativo do Node 18+

Related MCP server: BopMarket MCP Server

Início rápido

🔰 Nunca usou MCP ou a API do Mercado Livre? Siga o guia de instalação detalhado para iniciantes — passo a passo com prints do que esperar em cada etapa.

Pré-requisitos

• Node.js >= 18 (ou Docker + Docker Compose)

• Um aplicativo criado em developers.mercadolivre.com.br com a Redirect URI http://localhost:3333/callback

Configuração

1. Instale as dependências:

   npm install

2. Crie o arquivo de ambiente:

   cp .env.example .env

3. Preencha .env com ML_CLIENT_ID e ML_CLIENT_SECRET do seu aplicativo.

4. Compile:

   npm run build

5. Autentique (abre o navegador, captura o código e salva os tokens em tokens.json):

   npm run auth

6. Configure seu cliente MCP (veja Configuração nos clientes MCP) e comece a conversar.

Os tokens são renovados automaticamente (vida útil de 6h, com refresh 5 min antes de expirar). O refresh token é rotacionado pelo Mercado Livre e sempre persistido junto.

Ferramentas disponíveis (42)

Legenda: 📖 leitura · ✏️ escrita (operação real na conta)

Busca & Leitura

Publicação

Gestão de anúncios

Perguntas

Envios

Mensagens

Reclamações & Devoluções

Reputação & Métricas

Catálogo

Preço & Mercado

Categorias

Promoções

Mercado Ads

Fulfillment (Full)

Mercado Shops & Depósitos

Nota: as ferramentas de Mercado Ads, Fulfillment (Full) e Mercado Shops exigem que a conta/aplicativo tenha esses recursos habilitados (escopo de advertising, conta Full, loja criada). Caso contrário, o erro retornado pelo Mercado Livre é exibido claramente pela ferramenta.

Fluxos recomendados

Criar um anúncio

1. predict_category com o título do produto → obtém o category_id ideal.

2. get_category_attributes com a categoria escolhida → descobre os atributos obrigatórios.

3. (opcional) get_listing_types e get_listing_prices → escolhe o tipo de anúncio e estima as taxas.

4. (opcional) upload_picture e/ou upload_video → envia as mídias locais antes, caso não estejam em URLs públicas, e guarda os IDs retornados.

5. create_item com todos os atributos obrigatórios preenchidos (e video_id se houver vídeo) → publica o anúncio.

Se o Mercado Livre rejeitar a criação com erro de validação, o corpo completo do erro é retornado — basta corrigir os campos indicados e tentar novamente.

Operação diária do vendedor

1. get_questions com status=UNANSWERED → responde com answer_question (conversão depende disso).

2. get_orders → novos pedidos; get_shipment + get_shipment_label para despachar.

3. get_claims com status=opened → entende com get_claim_detail e responde com send_claim_message (prazos contam para a reputação).

4. get_item_visits + get_my_items → detecta anúncios com visitas e sem vendas; ajusta preço com get_price_suggestion e update_item.

5. get_seller_reputation → acompanha o termômetro e as métricas de claims/atrasos/cancelamentos.

Uso com Docker Compose

# build da imagem
docker compose build

# autenticação (publica a porta 3333 e imprime a URL para abrir no navegador)
docker compose --profile auth run --rm --service-ports auth

# executar o servidor MCP manualmente (stdio)
docker compose run --rm mcp-mercadolivre

Os tokens ficam no volume nomeado meli-data (/app/data/tokens.json dentro do container), compartilhado entre os serviços auth e mcp-mercadolivre.

Configuração nos clientes MCP

Execução local (Node)

Claude Desktop (claude_desktop_config.json), Kimi Code ou Cursor — trecho mcpServers:

{
  "mcpServers": {
    "mercadolivre": {
      "command": "node",
      "args": ["/caminho/absoluto/para/mcp_mercadolivre/dist/index.js"],
      "env": {
        "ML_CLIENT_ID": "seu_app_id",
        "ML_CLIENT_SECRET": "seu_client_secret",
        "ML_SITE_ID": "MLB"
      }
    }
  }
}

O caminho exato do arquivo de configuração de cada cliente (macOS/Windows/Linux) está no guia de instalação.

Execução via Docker

{
  "mcpServers": {
    "mercadolivre": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/caminho/absoluto/para/mcp_mercadolivre/.env",
        "-e", "ML_TOKENS_FILE=/app/data/tokens.json",
        "-v", "mcp_mercadolivre_meli-data:/app/data",
        "mcp-mercadolivre"
      ]
    }
  }
}

Importante: rode a autenticação (docker compose --profile auth run --rm --service-ports auth) antes de usar o servidor via Docker, para que os tokens existam no volume.

Segurança

O servidor inclui um pacote de proteções para operar sua conta com segurança, especialmente enquanto você experimenta.

Modo somente leitura (ML_READ_ONLY)

Defina ML_READ_ONLY=true no .env e nenhuma ferramenta de escrita é registrada — o tools/list expõe apenas 32 ferramentas de leitura (incluindo manage_question_blacklist, que nesse modo aceita somente a ação list; block/unblock retornam erro explicando o modo). Recomendado: use ML_READ_ONLY=true nos primeiros experimentos e só desligue quando estiver confortável.

Perfis de ferramentas (ML_TOOL_PROFILE)

Limita quais ferramentas o servidor expõe:

Confirmação de ação irreversível

update_item_status com action="close" exige o parâmetro confirm: true — sem ele, a chamada é recusada com uma mensagem pedindo a confirmação explícita (fechar um anúncio com vendas é irreversível).

Guarda de conteúdo em mensagens

send_message e send_claim_message varrem o texto antes de chamar a API e bloqueiam mensagens contendo e-mails, telefones (formatos BR) ou links/domínios — conteúdo proibido pela moderação do Mercado Livre, que pode sancionar a conta. A mensagem de bloqueio explica o motivo para o texto ser reformulado.

Log de auditoria

Toda invocação de ferramenta de escrita é registrada em audit.log (raiz do projeto, append-only, gitignored) com timestamp, ferramenta, parâmetros (truncados em 500 caracteres) e resultado (ok/error). Ferramentas de leitura não são logadas.

Permissões do arquivo de tokens

Na inicialização e após salvar tokens, o servidor verifica tokens.json: se as permissões forem mais abertas que 0600 (legível por grupo/outros), um aviso é impresso e o modo é corrigido automaticamente para 0600.

Solução de problemas

• O cadastro do app rejeita a Redirect URI http://localhost:3333/callback: o Mercado Livre exige HTTPS para apps em produção, mas aceita http://localhost durante a autenticação. Se o formulário de cadastro recusar, cadastre temporariamente uma URL HTTPS qualquer (ex. https://localhost/callback) e, na hora de autenticar, mantenha ML_REDIRECT_URI=http://localhost:3333/callback no .env — ou use uma URL HTTPS válida e ajuste ML_REDIRECT_URI e o auth-cli de acordo.

• Redirect URI mismatch na autenticação: o ML_REDIRECT_URI do .env precisa ser idêntico ao cadastrado no aplicativo (incluindo porta e path). Qualquer diferença faz o Meli recusar o callback.

• No tokens stored: rode npm run auth (ou o serviço auth do compose) novamente.

• Erros 401 persistentes / refresh token expirado: o refresh token tem validade máxima (~6 meses) e é rotacionado a cada refresh — se a conta ficou muito tempo sem uso ou o arquivo de tokens foi perdido, refaça a autenticação.

• Erros de escopo/permissão nas ferramentas de Ads, Full ou Shops (403/404): essas APIs exigem recursos extras — escopo de advertising concedido ao app, conta Full habilitada, ou uma Mercado Shop criada. O servidor retorna a mensagem do Meli como está; habilite o recurso na conta/app e tente novamente.

• Erros de validação no create_item: o corpo completo do erro do Meli é retornado — normalmente indica atributos obrigatórios faltando (rode get_category_attributes na categoria) ou valores fora do permitido. Corrija os campos indicados e reenvie.

• Etiqueta de envio não encontrada: a etiqueta só existe quando o envio está ready_to_ship, e tipos logísticos como flex/self_service não têm etiqueta para impressão.

Estrutura do projeto

mcp_mercadolivre/
├── src/
│   ├── index.ts        # Servidor MCP: registro das 42 ferramentas
│   ├── meli-client.ts  # Cliente HTTP da API Meli (Bearer, retry 401, multipart, binário)
│   ├── auth.ts         # OAuth 2.0: URL de autorização, troca/refresh de tokens
│   ├── auth-cli.ts     # CLI de autenticação (servidor local :3333 + browser)
│   ├── token-store.ts  # Persistência dos tokens em tokens.json (0600)
│   ├── safety.ts       # Perfis, read-only, guarda de conteúdo, audit log
│   └── config.ts       # Variáveis de ambiente + parser de .env sem dependências
├── docs/
│   ├── instalacao.md   # Guia de instalação passo a passo para iniciantes
│   ├── arquitetura.md  # Arquitetura, fluxo OAuth e decisões de design
│   ├── tools.md        # Referência completa das 42 ferramentas
│   └── api-map.md      # Mapa de endpoints da API Meli utilizados e cobertura
├── dist/               # Build (tsc)
├── Dockerfile
├── docker-compose.yml
├── LICENSE             # Licença MIT
├── CONTRIBUTING.md     # Guia de contribuição
├── .env.example
└── package.json

Documentação

• docs/instalacao.md — guia de instalação passo a passo (para quem nunca usou MCP)

• docs/arquitetura.md — arquitetura interna, fluxo OAuth e estratégia de erros

• docs/tools.md — referência detalhada de cada ferramenta (parâmetros, endpoints, notas)

• docs/api-map.md — endpoints da API do Mercado Livre utilizados e áreas não cobertas

Contribuindo

Contribuições são muito bem-vindas — issues, sugestões de novas ferramentas e pull requests. Leia o CONTRIBUTING.md para os padrões do código e o checklist de como adicionar uma nova ferramenta.

Licença

Distribuído sob a licença MIT. Veja o arquivo LICENSE para o texto completo.

Autor & Contato

• Nome: Gustavo Santos

• GitHub: https://github.com/gustavossouza

• Email: gustavohsantos2009@hotmail.com

• LinkedIn: https://www.linkedin.com/in/gustavohssouza/

• WhatsApp: +55 41 99101-6997