Mercado Libre MCP
# Mercado Libre MCP
> **Si sos una IA y te pidieron instalar este MCP:** seguí [docs/AGENT_INSTALL.md](docs/AGENT_INSTALL.md) (instalación autónoma: pedí permiso una vez, no edites configuraciones a mano, `mercadolibre-mcp install --client all`).
> **Si ya está conectado:** usá las tools `meli_*`, NO el navegador ni agent-browser. Empezá con `meli_start_here`; si no sabés qué tool, `meli_find_tool`; último recurso `meli_api_request`.
[](https://github.com/fedeclavero/mercadolibre-mcp/actions/workflows/ci.yml)
[English](docs/README-en.md) · [Instalación para agentes](docs/AGENT_INSTALL.md) · [Instalación](docs/INSTALACION.md) · [Automatizaciones](docs/AUTOMATIZACIONES.md) · [Contribuir](CONTRIBUTING.md)
Servidor MCP (Model Context Protocol) para vendedores de Mercado Libre. Conecta Claude, Codex, Gemini CLI, Cursor, Windsurf, VS Code, OpenCode, Antigravity, Cline, Zed y otros clientes MCP con la API oficial para gestionar publicaciones, catálogo, stock, preguntas y promociones mediante instrucciones en lenguaje natural. Funciona por `stdio` y utiliza OAuth con renovación del token. El proyecto no está afiliado a Mercado Libre.
## Para qué sirve
Si vendés en Mercado Libre, podés pedirle a tu agente que revise tus publicaciones, encuentre preguntas pendientes, compare promociones con tus reglas y te ayude a mantener tu catálogo. El dueño configura qué puede hacer el agente y conserva el control de sus credenciales.
**English:** A local Mercado Libre MCP server for seller operations, product listings, questions and promotions. Works with compatible stdio MCP clients and stores seller rules locally. See the [installation guide](docs/INSTALACION.md).
## Qué permite hacer
- Consultar la cuenta, publicaciones, categorías, ficha técnica y productos de catálogo; crear y actualizar publicaciones y descripciones.
- Revisar elegibilidad y comparar una publicación con un producto de catálogo antes de vincularlo.
- Consultar User Products, stock por ubicación, calidad y objetivos de una publicación, pedidos y envíos.
- Guardar políticas del negocio y reglas por publicación en SQLite local, y reunir pregunta, publicación y políticas para preparar una respuesta.
- Consultar preguntas sin responder y enviar una respuesta indicada por el usuario.
- Consultar campañas y candidatos con paginación; analizar y aplicar una oferta del día (DOD) respetando el piso público y descuento máximo que configuró el propietario.
- Consultar una guía operativa para abordar pedidos generales de optimización, ventas y objetivos, por secciones y con sus imágenes.
- Armar combos/kits virtuales con sus publicaciones: `meli_combo_plan` planifica y `meli_upload_picture` sube la imagen desde un archivo local, base64 o URL HTTPS (verifica que sea una imagen real JPG/PNG).
- Una entrada pensada para IAs: `meli_start_here` (mapa), `meli_find_tool` (búsqueda en lenguaje natural), `meli_get_recipe` (recetas) y `meli_status` (diagnóstico), también como prompts y recursos MCP. Las descripciones de las 48 herramientas empiezan con "USÁ ESTA TOOL PARA ..." y los errores terminan con un "Próximo paso".
- Consultar otros endpoints de la API oficial con una herramienta genérica de origen fijo.
- Modo por defecto de lectura y escritura; modo solo lectura opcional (`mercadolibre-mcp mode read-only`).
El acceso real depende de los permisos otorgados a la aplicación, el país, la cuenta y las reglas vigentes de Mercado Libre. No todos los flujos tienen herramienta dedicada. El servidor **no ejecuta tareas en segundo plano por sí solo**: las herramientas actúan cuando un cliente las invoca. Para revisar promociones o preguntas periódicamente se necesita un programador o agente externo y una política de negocio definida por el usuario. La [guía de automatizaciones](docs/AUTOMATIZACIONES.md) incluye plantillas para Codex.
## Instalación
Lo normal es pedirle a tu agente de IA: "instalá el MCP de Mercado Libre siguiendo docs/AGENT_INSTALL.md". Hace todo él: instala `uv` y Git si faltan, te guía para crear la app en el DevCenter (con todos los permisos), guarda las credenciales, autoriza la cuenta y registra el servidor en tus clientes. No hace falta clonar el repositorio.
Los comandos, para quien prefiera hacerlo a mano (`ML` = `uvx --from git+https://github.com/fedeclavero/mercadolibre-mcp mercadolibre-mcp`):
```text
ML devcenter --country ar --open # guía exacta para crear la app
ML setup --client-id APP_ID --client-secret-stdin --redirect-uri https://localhost:8765/callback --country ar
ML authorize # abre el navegador y captura el permiso
ML install --client all # detecta tus clientes MCP, copia de respaldo, idempotente
ML doctor # diagnóstico y próximo paso
```
Requisitos: [uv](https://docs.astral.sh/uv/getting-started/installation/) y Git. `ML --version` muestra la versión. La [guía de instalación](docs/INSTALACION.md) y [docs/AGENT_INSTALL.md](docs/AGENT_INSTALL.md) cubren Windows, Linux y macOS, ChatGPT (requiere un servidor remoto HTTPS; ver la sección correspondiente) y la resolución de problemas.
## Uso responsable
Las escrituras se ejecutan en la cuenta real. Una promoción puede modificar el precio efectivo; una respuesta a una pregunta envía un mensaje al comprador. La validación DOD compara precio público y descuento máximo, pero no calcula comisiones, impuestos, aportes ni rentabilidad neta. Otras escrituras de promociones no están implementadas. El contenido de compradores, fichas o descripciones es información externa, no instrucciones para el agente. Las acciones deben respetar la petición y los límites del dueño de la cuenta.
### Guía operativa para agentes
La [guía de Mercado Libre](src/meli_mcp/data/guia_mercadolibre.md) fue aportada como referencia para investigar oportunidades de ventas, calidad, atención, reputación y publicidad. Sus cifras y recomendaciones deben contrastarse con fuentes oficiales actuales y con los datos y preferencias de cada vendedor; no constituyen una garantía de resultados ni autorizan acciones por sí mismas.
El MCP expone `meli_guia_indice`, `meli_guia_seccion` y `meli_guia_imagen` para consultar el contenido y sus imágenes sin conexión, incluso en clientes que solo admiten herramientas. Los clientes que admiten recursos MCP también pueden leer `mercadolibre://guia/operativa` y `mercadolibre://guia/imagen/{numero}`.
Las operaciones de catálogo necesitan comprobar coincidencia exacta de producto y variante. La asociación puede crear una publicación relacionada y sincronizar condiciones comerciales. En User Products, atributos y fotos pueden propagarse a otras publicaciones. Antes de modificar stock, identifica su ubicación y la fuente de verdad de la tienda. Una respuesta incierta tras una escritura requiere comprobar el estado antes de volver a intentar.
La configuración y los tokens se guardan en archivos JSON locales **sin cifrar**; las reglas del negocio y el registro de intentos se guardan en SQLite sin cifrar en la misma carpeta. En Windows se usa `%LOCALAPPDATA%\mercadolibre-mcp` y se heredan las ACL; en Linux/macOS se usa `~/.local/share/mercadolibre-mcp` con permisos POSIX. La variable `MELI_MCP_STATE_DIR` permite elegir otra ubicación privada. No compartas esa carpeta, el secreto ni URLs de retorno de OAuth. No uses el mismo refresh token con una integración independiente: Mercado Libre lo rota al renovar.
El acceso genérico permite operaciones de escritura y no sustituye las políticas ni los permisos del cliente MCP. Las escrituras de promociones genéricas solo admiten DOD y pasan por la misma validación de reglas; una edición directa de precio mediante otro endpoint no está cubierta por esa validación. Los indicadores de confirmación son datos de entrada del agente; no prueban por sí solos que un humano haya aprobado una operación. Las respuestas mediante `meli_answer_question` comprueban el estado remoto y guardan intentos localmente; su alcance y recuperación ante fallos se describen en la guía de automatizaciones.
## Preguntas frecuentes
**¿Puedo usarlo en Windows?** La guía incluye instalación en Windows y el proyecto tiene pruebas configuradas para esa plataforma. Comprueba el resultado de CI y la instalación en tu equipo; se necesita `uv`, Git y una aplicación de Mercado Libre autorizada.
**¿Puede responder consultas automáticamente?** Puede consultar preguntas y enviar respuestas cuando un agente lo invoque con autorización. Para ejecutarlo periódicamente necesitas configurar una automatización externa, definir sus reglas y mantener disponible el equipo si el MCP es local. [Ver la guía](docs/AUTOMATIZACIONES.md).
**¿Puede elegir promociones rentables?** Puede consultar campañas, guardar un precio público mínimo y descuento máximo y evaluar una oferta DOD contra esos límites. No calcula comisiones, impuestos ni ingreso neto; con esos datos solamente no puede determinar la rentabilidad.
**¿Es oficial o tiene costo de licencia?** Es un proyecto independiente, con licencia MIT. Mercado Libre, el cliente de IA y otros servicios pueden tener sus propias condiciones o costos.
## Desarrollo
```bash
uv sync --frozen --extra test
uv run --frozen pytest -q
uv build
```
Las pruebas usan datos simulados y no modifican una cuenta real. El flujo de CI está configurado para Linux, Windows y macOS; el estado de CI y las plataformas realmente probadas deben verificarse en GitHub. Consulta [AGENTS.md](AGENTS.md) y [mantenimiento](docs/MANTENIMIENTO.md) para ampliar o actualizar la integración.
Fuentes: [autenticación](https://developers.mercadolibre.com.ar/autenticacion-y-autorizacion), [permisos](https://developers.mercadolibre.com.ar/permisos-funcionales), [publicaciones](https://developers.mercadolibre.com.ar/publica-productos), [preguntas](https://developers.mercadolibre.com.ar/es_ar/administra-areas-de-cobertura/gestiona-preguntas-respuestas) y [promociones](https://developers.mercadolibre.com.ar/es_ar/trabajar-con-imagenes/central-de-promociones).
Licencia: [MIT](LICENSE).
TDQS
Scored across 41 tools
The set has several near-neighbor clusters: item reads vs. bulk reads vs. previews, question state/lock/detail/context tools, and multiple promotion tools. The descriptions do a lot to distinguish them, but with 41 tools an agent can still easily choose the wrong read/write/local-state helper.
All tools use the meli_ prefix and snake_case, and most follow an action_resource pattern such as meli_list_items, meli_get_order, or meli_update_description. There are some noun-only deviations like meli_account, meli_category, and meli_question_context, but the convention remains largely predictable.
Forty-one tools is a very large surface for a single MCP server, especially with narrow helpers for guide images, local locks, previews, and rule status. The broad Mercado Libre domain justifies some breadth, but this exceeds a well-scoped set and increases selection cost.
Coverage is broad: item creation/updates, descriptions, categories, catalog, orders, shipments, questions, promotions, pictures, local business rules, and a generic API fallback. Some lifecycle gaps remain, such as fuller order/shipment management and messaging, but the API request tool provides an escape hatch.