Mercado Livre MCP Server

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