Mercadolivre MCP Server

用于自由市场API的MCP服务器

完整的模型上下文协议 （MCP） 服务器，可与自由市场 API 集成，支持 stdio、REST 和 WebSocket。

🚀 功能

产品管理

• 搜索产品
• 获取产品详情
• 创建新产品
• 更新现有产品
• 库存管理
• 更新价格
• 暂停/激活产品

订单管理

• 列出卖方订单
• 获取订单详情
• 按状态筛选
• 按日期搜索订单

问题和答案

• 列出已收到的问题
• 回答问题
• 按状态过滤（已回复/未回复）
• 阻止用户

发货

• 获取发货详情
• Gerar标签（PDF/ZPL2）
• 跟踪发送
• 查看发送选项

Metricas

• 产品参观
• 收到的问题
• 电话视图
• 按期分析

📦 安装

npm install
npm run build

⚙️ 配置

环境变量

创建文件 .env 工程根 ：

# 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

获取凭据

1. 访问https://developers.mercadolivre.com.br/
2. 创建新应用程序
3. 复制O Client ID e Client Secret
4. 配置a Redirect URI

🎯 使用

STDIO 模式 （标准 MCP）

npm start

或添加到您的 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"
      }
    }
  }
}

休息模式

MCP_MODE=rest npm start

可用的端点 ：

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

客户示例：

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);
});

🔧 可用工具（MCP）

产品

search_products

在自由市场上搜索产品

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

get_product

获取产品详情

{
  "itemId": "MLB123456789"
}

update_stock

更新库存

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

update_price

更新价格

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

订单

get_seller_orders

列出卖方订单

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

问题

get_received_questions

列出已收到的问题

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

answer_question

回答一个问题

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

发货

get_shipment

获取发货详情

{
  "shipmentId": "123456789"
}

print_shipment_label

Gerar标签

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

Metricas

get_user_visits

获取产品访问

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

🔐 认证

服务器自动管理 ：

• 刷新过期代币
• 自动更新访问令牌
• 安全存储凭据

Fluxo OAuth

1. 获取授权 URL ：

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

1. 授权后，将代码兑换为令牌：

await client.exchangeCodeForToken(code);

📝 自然语言使用示例

使用 MCP Server，您可以使用自然语言管理您的帐户：

• “寻找价格高达3000雷亚尔的笔记本电脑产品”
• “将MLB123产品库存更新至50个单位”
• “列出过去7天的所有付费订单”
• “回答问题 456 说产品可用”
• “管理 789 和 101 订单的运输标签”
• “显示上个月的访问量指标”

🛠️ 开发

# Modo desenvolvimento com hot reload
npm run dev

# Build
npm run build

# Testes
npm test

📚 API 文档

请参阅自由市场官方文件：

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

🤝 贡献

欢迎捐款！请：

1. 分叉工程
2. 为您的功能创建分支
3. 提交您的更改
4. 推动一个分支
5. Abra um Pull请求

📄 许可证

麻省理工学院

🔗 链接乌斯

• MCP 文档
• API Mercado Livre公司
• OAuth 2.0