Servidor MCP de MercadoLibre

Un servidor Model Context Protocol (MCP) que conecta a Claude directamente con tu cuenta de vendedor de MercadoLibre. Gestioná publicaciones, pedidos y envíos — todo mediante lenguaje natural.

Apunta a MLA (Argentina) por defecto. Cambiá ML_SITE para otros mercados.

---

Qué podés hacer con esto

• "Listame mis publicaciones activas"
• "Creá una nueva publicación para un iPhone 14 usado, ARS 500000, categoría MLA1055"
• "Mostrame mis últimos 10 pedidos pagados"
• "Conseguime la etiqueta de envío del despacho 12345678"
• "¿Qué categoría debería usar para auriculares con cancelación de ruido?"

---

Requisitos

• Python 3.11 o superior
• Una cuenta de vendedor de MercadoLibre
• Una aplicación de desarrollador de MercadoLibre (client_id + client_secret)
• Una cuenta de Claude.ai Pro, Team o Enterprise (para conexiones MCP remotas)

---

Paso 1 — Crear una aplicación de MercadoLibre

1. Andá a developers.mercadolibre.com.ar e iniciá sesión
2. Hacé clic en Crear aplicación
3. Completá los datos de la app. En URI de redirección ingresá tu URL de callback:
   • Local: http://localhost:8000/auth/callback
   • Railway: https://your-app.up.railway.app/auth/callback
4. Guardá la app y copiá tu App ID (esto es ML_CLIENT_ID) y Secret key (ML_CLIENT_SECRET)

---

Paso 2 — Configurar el servidor localmente

Cloná este repo

git clone https://github.com/your-username/mercadolibre-mcp.git
cd mercadolibre-mcp

Instalá las dependencias

pip install -r requirements.txt

Configurá tus variables de entorno

cp env.example .env

Abrí .env y completá tus valores:

ML_CLIENT_ID=your-app-id
ML_CLIENT_SECRET=your-secret-key
ML_REDIRECT_URI=http://localhost:8000/auth/callback
BEARER_TOKEN=pick-a-long-random-string-here

Iniciá el servidor

python server.py

Completá el flujo de OAuth

ML requiere autorización del usuario antes de que el servidor pueda acceder a los datos de tu cuenta.

1. Abrí http://localhost:8000/auth/url — devuelve un JSON con auth_url
2. Abrí esa URL en tu navegador y autorizá la app
3. ML te redirige a /auth/callback — el servidor intercambia el código por tokens
4. El servidor registra ML_ACCESS_TOKEN y ML_REFRESH_TOKEN en la consola

Pegá esos dos valores en tu archivo .env para que sobrevivan a los reinicios del servidor:

ML_ACCESS_TOKEN=APP_USR-...
ML_REFRESH_TOKEN=TG-...

Los tokens de acceso de ML expiran cada 6 horas. El servidor los renueva automáticamente usando el refresh token, pero el refresh token se rota en cada renovación — revisá tus logs y actualizá ML_REFRESH_TOKEN después de cada reinicio hasta que tengas una configuración más duradera.

---

Paso 3 — Desplegar en la nube

Desplegar en Railway

1. Forkeá este repo de GitHub a tu propia cuenta
2. Andá a railway.app e iniciá sesión con GitHub
3. Hacé clic en New Project → Deploy from GitHub repo
4. Seleccioná tu repo forkeado
5. Cuando termine el build, andá a tu servicio → Settings → Networking → Generate Domain
6. Copiá tu URL pública — se ve algo así como https://ml-mcp-production.up.railway.app

Agregá tus variables de entorno en Railway

Variable	Requerida	Valor
ML_CLIENT_ID	✅	Tu App ID de ML
ML_CLIENT_SECRET	✅	Tu Secret key de ML
ML_REDIRECT_URI	✅	https://your-app.up.railway.app/auth/callback
ML_ACCESS_TOKEN	✅*	Obtenido después del flujo de OAuth
ML_REFRESH_TOKEN	✅*	Obtenido después del flujo de OAuth
BEARER_TOKEN	✅	Cadena aleatoria larga — el mismo valor que vas a ingresar en Claude
ML_SITE	No	MLA (por defecto)
PORT	No	8000
ALLOW_TOKEN_QUERY_PARAM	No	1 — solo si Claude.ai no puede enviar headers de Authorization

*Requerido para que el servidor pueda hacer llamadas a la API. Completá el flujo de OAuth en tu instancia local primero, y después pegá los tokens acá.

---

Paso 4 — Conectar con Claude

1. Andá a claude.ai → hacé clic en tu ícono de perfil → Settings
2. Navegá a Integrations
3. Hacé clic en Add integration
4. Completá:
   • Name: MercadoLibre
   • URL: https://your-app.up.railway.app/mcp
5. En el campo de authentication token: pegá el valor de tu BEARER_TOKEN

---

Herramientas disponibles

Herramienta	Descripción
ml_get_my_user	Obtiene el perfil del vendedor autenticado
ml_list_items	Lista tus publicaciones (con filtro de estado y paginación)
ml_get_item	Obtiene una publicación por su ID
ml_create_item	Crea una nueva publicación de producto
ml_update_item	Actualiza una publicación existente
ml_change_item_status	Pausa, reactiva o cierra una publicación
ml_list_orders	Lista tus pedidos (con filtro de estado)
ml_get_order	Obtiene un pedido por su ID
ml_get_shipment	Obtiene los detalles de envío de un despacho
ml_get_shipment_label	Obtiene una etiqueta de envío imprimible (ZPL2 o PDF)
ml_predict_category	Predice la mejor categoría para una descripción de producto
ml_get_category_attributes	Obtiene los atributos requeridos/opcionales de una categoría

---

Referencia de variables de entorno

Variable	Requerida	Valor por defecto	Descripción
ML_CLIENT_ID	✅	—	App ID de la aplicación de ML
ML_CLIENT_SECRET	✅	—	Secret key de la aplicación de ML
ML_REDIRECT_URI	✅	—	URL de callback de OAuth registrada en tu app de ML
ML_ACCESS_TOKEN	✅*	—	Token de acceso de ML (del flujo de OAuth)
ML_REFRESH_TOKEN	✅*	—	Refresh token de ML (del flujo de OAuth)
BEARER_TOKEN	✅	—	Protege tu endpoint MCP — configurá el mismo valor en Claude
ML_SITE	No	MLA	ID del sitio: MLA=Argentina, MLB=Brasil, MLM=México, MLC=Chile
TOKEN_REFRESH_BUFFER	No	1800	Segundos antes del vencimiento del token para disparar una renovación
PORT	No	8000	Puerto en el que escucha el servidor
MCP_TRANSPORT	No	streamable-http	Protocolo de transporte
ALLOW_TOKEN_QUERY_PARAM	No	—	Poner en 1 solo si tu cliente MCP no puede enviar headers de Authorization
MAX_REQUEST_BODY	No	1048576	Tamaño máximo del cuerpo de la request entrante, en bytes (1 MB)
RATE_LIMIT_RPM	No	60	Máximo de requests por minuto por IP
RATE_LIMIT_MAX_IPS	No	10000	Máximo de IPs rastreadas por el limitador de tasa
TRUSTED_PROXY_COUNT	No	1	Cantidad de proxies inversos delante del servidor

*Requerido para el acceso a la API. Se obtiene completando el flujo de OAuth.

---

Resolución de problemas

Error "No ML_REFRESH_TOKEN available" Todavía no se completó el flujo de OAuth. Visitá /auth/url, autorizá la app y pegá los tokens de los logs del servidor en tus variables de entorno.

401 Unauthorized de MercadoLibre Tu token de acceso es inválido o expiró, y el refresh token falta o es inválido. Volvé a ejecutar el flujo de OAuth para obtener tokens nuevos.

"Token exchange failed" en /auth/callback Asegurate de que ML_REDIRECT_URI coincida exactamente con lo registrado en tu app de ML (incluyendo el esquema y el path). Incluso una diferencia de barra final va a causar un desajuste.

Claude no puede conectarse al servidor Asegurate de que tu despliegue en Railway esté activo y de que se haya generado un dominio. Visitá https://your-app.up.railway.app/health — debería devolver {"status": "ok"}.

El refresh token deja de funcionar después de un reinicio ML rota el refresh token en cada llamada de renovación. El servidor registra el nuevo ML_REFRESH_TOKEN cada vez que renueva. Actualizá ese valor en tus variables de entorno de Railway para mantenerlo vigente.

---

Licencia

MIT