MCP Server para API do Mercado Livre

Servidor MCP (Model Context Protocol) completo para integração com a API do Mercado Livre, com suporte a stdio, REST e WebSocket.

🚀 Funcionalidades

Gerenciamento de Produtos

• Buscar produtos
• Obter detalhes de produtos
• Criar novos produtos
• Atualizar produtos existentes
• Gerenciar estoque
• Atualizar preços
• Pausar/ativar produtos

Gerenciamento de Pedidos

• Listar pedidos do vendedor
• Obter detalhes de pedidos
• Filtrar por status
• Buscar pedidos por data

Perguntas e Respostas

• Listar perguntas recebidas
• Responder perguntas
• Filtrar por status (respondidas/não respondidas)
• Bloquear usuários

Envios

• Obter detalhes de envios
• Gerar etiquetas (PDF/ZPL2)
• Rastrear envios
• Consultar opções de envio

Métricas

• Visitas de produtos
• Perguntas recebidas
• Visualizações de telefone
• Análise por período

📦 Instalação

npm install
npm run build

⚙️ Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto:

# Modo de operação: stdio, rest ou websocket
MCP_MODE=stdio

# Porta (para modos rest e websocket)
MCP_PORT=3000

# Credenciais do Mercado Livre
ML_CLIENT_ID=seu_client_id
ML_CLIENT_SECRET=seu_client_secret
ML_REDIRECT_URI=http://localhost:3000/callback

# Tokens (opcional, serão obtidos via OAuth)
ML_ACCESS_TOKEN=seu_access_token
ML_REFRESH_TOKEN=seu_refresh_token

Obter Credenciais

1. Acesse https://developers.mercadolivre.com.br/
2. Crie uma nova aplicação
3. Copie o Client ID e Client Secret
4. Configure a Redirect URI

🎯 Uso

Modo STDIO (MCP Padrão)

npm start

Ou adicione ao seu mcp.json:

{
  "mcpServers": {
    "mercadolivre": {
      "command": "node",
      "args": ["/caminho/para/ML/mcp-server/dist/index.js"],
      "env": {
        "ML_CLIENT_ID": "seu_client_id",
        "ML_CLIENT_SECRET": "seu_client_secret",
        "ML_ACCESS_TOKEN": "seu_access_token",
        "ML_REFRESH_TOKEN": "seu_refresh_token"
      }
    }
  }
}

Modo REST

MCP_MODE=rest npm start

Endpoints disponíveis:

GET  /health
GET  /products/search?query=termo&limit=50
GET  /products/:itemId
GET  /users/:userId/products
POST /products
PUT  /products/:itemId
PUT  /products/:itemId/stock
PUT  /products/:itemId/price
POST /products/:itemId/pause
POST /products/:itemId/activate
GET  /sellers/:sellerId/orders
GET  /orders/:orderId
GET  /questions/received
POST /questions/:questionId/answer
GET  /shipments/:shipmentId
POST /shipments/labels
GET  /users/:userId/visits

Modo WebSocket

MCP_MODE=websocket npm start

Exemplo de cliente:

const ws = new WebSocket('ws://localhost:3001');

ws.on('open', () => {
  ws.send(JSON.stringify({
    id: '1',
    method: 'search_products',
    params: { query: 'notebook', limit: 10 }
  }));
});

ws.on('message', (data) => {
  const response = JSON.parse(data);
  console.log(response);
});

🔧 Ferramentas Disponíveis (MCP)

Produtos

search_products

Buscar produtos no Mercado Livre

{
  "query": "notebook",
  "limit": 50
}

get_product

Obter detalhes de um produto

{
  "itemId": "MLB123456789"
}

update_stock

Atualizar estoque

{
  "itemId": "MLB123456789",
  "quantity": 10
}

update_price

Atualizar preço

{
  "itemId": "MLB123456789",
  "price": 1999.90
}

Pedidos

get_seller_orders

Listar pedidos do vendedor

{
  "sellerId": "123456789",
  "status": "paid",
  "limit": 50
}

Perguntas

get_received_questions

Listar perguntas recebidas

{
  "status": "UNANSWERED",
  "limit": 50
}

answer_question

Responder uma pergunta

{
  "questionId": "123456789",
  "text": "Olá! Sim, temos em estoque."
}

Envios

get_shipment

Obter detalhes de envio

{
  "shipmentId": "123456789"
}

print_shipment_label

Gerar etiqueta

{
  "shipmentIds": ["123456789", "987654321"],
  "format": "pdf"
}

Métricas

get_user_visits

Obter visitas de produtos

{
  "userId": "123456789",
  "dateFrom": "2024-01-01T00:00:00.000Z",
  "dateTo": "2024-01-31T23:59:59.999Z"
}

🔐 Autenticação

O servidor gerencia automaticamente:

• Refresh de tokens expirados
• Renovação automática de access tokens
• Armazenamento seguro de credenciais

Fluxo OAuth

1. Obtenha a URL de autorização:

const authUrl = client.getAuthUrl('random_state');
// Redirecione o usuário para authUrl

2. Após autorização, troque o código por tokens:

await client.exchangeCodeForToken(code);

📝 Exemplos de Uso com Linguagem Natural

Com o MCP Server, você pode usar linguagem natural para gerenciar sua conta:

• "Busque produtos de notebook com preço até 3000 reais"
• "Atualize o estoque do produto MLB123 para 50 unidades"
• "Liste todos os pedidos pagos dos últimos 7 dias"
• "Responda a pergunta 456 dizendo que o produto está disponível"
• "Gere etiquetas de envio para os pedidos 789 e 101"
• "Mostre as métricas de visitas do mês passado"

🛠️ Desenvolvimento

# Modo desenvolvimento com hot reload
npm run dev

# Build
npm run build

# Testes
npm test

📚 Documentação da API

Consulte a documentação oficial do Mercado Livre:

• https://developers.mercadolivre.com.br/pt_br/api-docs

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o projeto
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request

📄 Licença

MIT

🔗 Links Úteis

• Documentação MCP
• API Mercado Livre
• OAuth 2.0