MCP Server — Mercado Livre (Vendedor)

Servidor MCP (Model Context Protocol) que integra com a API do Mercado Livre, disponibilizando ferramentas para gestão de vendas, envios e etiquetas diretamente pelo Claude.

Pré-requisitos

• Node.js v18+
• App do Mercado Livre criado no Portal de Desenvolvedores
  • Com as permissões: offline_access, read, orders-shipments

Instalação

git clone https://github.com/seu-usuario/rg-mcp-mercadolivre.git
cd rg-mcp-mercadolivre
npm install
npm run build

Obter credenciais

1. Criar App no Mercado Livre

Acesse o Portal de Desenvolvedores e crie um aplicativo. Anote o Client ID e Client Secret.

2. Autorizar o App

Abra no navegador (substitua CLIENT_ID e REDIRECT_URI pelos seus valores):

https://auth.mercadolivre.com.br/authorization?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI

Após autorizar, você será redirecionado para uma URL com um parâmetro ?code=TG-XXXXXXX. Copie esse código.

3. Trocar o código por tokens

curl -X POST "https://api.mercadolibre.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "code=TG-XXXXXXX" \
  -d "redirect_uri=REDIRECT_URI"

A resposta conterá o refresh_token necessário para a configuração.

Configuração no Claude Code

Crie um arquivo .mcp.json na raiz do projeto:

{
  "mcpServers": {
    "mcp-mercadolivre": {
      "command": "node",
      "args": ["/caminho/completo/para/rg-mcp-mercadolivre/build/index.js"],
      "env": {
        "ML_CLIENT_ID": "seu_client_id",
        "ML_CLIENT_SECRET": "seu_client_secret",
        "ML_REFRESH_TOKEN": "seu_refresh_token"
      }
    }
  }
}

Importante: O arquivo .mcp.json contém credenciais sensíveis e já está no .gitignore. Nunca o commite no repositório.

Após criar o arquivo, reinicie o Claude Code para que o MCP server seja carregado. O Claude vai pedir aprovação na primeira vez.

Persistência de tokens

O servidor persiste automaticamente o refresh_token mais recente em .ml_token.json. Como o Mercado Livre invalida o refresh token a cada uso (single-use), essa persistência garante que o servidor continue funcionando entre reinícios sem precisar reautorizar.

Ferramentas disponíveis

listar_vendas

Lista as vendas do vendedor com filtros.

Parâmetro	Tipo	Descrição
status	string	Status do pedido: paid, cancelled, confirmed, etc.
tags	string	Tags: paid, not_delivered, delivered
q	string	Busca por ID do pedido, item, título ou nickname
date_from	string	Data início (ISO 8601)
date_to	string	Data fim (ISO 8601)
sort	string	date_asc ou date_desc
limit	number	Quantidade por página (max 50)
offset	number	Offset para paginação

vendas_para_enviar

Lista vendas pagas que estão prontas para despacho (ready_to_ship).

Parâmetro	Tipo	Descrição
apenas_hoje	boolean	Se true, filtra apenas envios com prazo para hoje
limit	number	Quantidade máxima de pedidos

gerar_etiquetas

Gera etiquetas de envio em PDF ou ZPL para impressão.

Parâmetro	Tipo	Descrição
shipment_ids	string	(obrigatório) IDs dos shipments separados por vírgula (max 50)
formato	string	pdf ou zpl2

detalhes_venda

Retorna os detalhes completos de um pedido.

Parâmetro	Tipo	Descrição
order_id	number	(obrigatório) ID do pedido

detalhes_envio

Retorna detalhes de um envio: endereço, rastreio, status, logística.

Parâmetro	Tipo	Descrição
shipment_id	number	(obrigatório) ID do envio

historico_envio

Retorna o histórico completo de status de um envio.

Parâmetro	Tipo	Descrição
shipment_id	number	(obrigatório) ID do envio

salvar_pdf

Converte uma string base64 em arquivo PDF e salva no caminho especificado. Útil para salvar etiquetas geradas pela tool gerar_etiquetas.

Parâmetro	Tipo	Descrição
base64	string	(obrigatório) Conteúdo do PDF codificado em base64
caminho	string	(obrigatório) Caminho absoluto onde salvar o arquivo (deve terminar com .pdf)

Exemplos de prompts

Consultar vendas

Liste minhas últimas 10 vendas

Quais vendas eu fiz hoje?

Busque vendas do produto "Tecido Tricoline"

Mostre minhas vendas canceladas do último mês

Envios pendentes

Quais vendas preciso enviar hoje?

Liste todas as vendas prontas para despacho

Tenho algum envio pendente?

Etiquetas

Gere as etiquetas dos envios pendentes em PDF

Gere a etiqueta ZPL do shipment 46688889102

Gere etiquetas para os shipments 46688889102, 46688889103, 46688889104

Detalhes e rastreio

Mostre os detalhes do pedido 2000015624114436

Qual o status do envio 46688889102?

Mostre o histórico de rastreio do envio 46688889102

Salvar etiquetas em PDF

Gere as etiquetas dos envios pendentes e salve o PDF na minha área de trabalho

Gere a etiqueta do shipment 46688889102 e salve em /Users/usuario/Desktop/etiqueta.pdf

Combinações

Liste as vendas que preciso enviar hoje, gere todas as etiquetas e salve o PDF no Desktop

Mostre minhas vendas de hoje com os detalhes de cada envio

Desenvolvimento

# Rodar em modo dev (com hot reload)
npm run dev

# Build
npm run build

# Rodar o servidor
npm start

Licença

MIT