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?"

Related MCP server: Amazon SP-API MCP Server

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

*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

Referencia de variables de entorno

*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