Skip to main content
Glama

Mercado Libre MCP Server — para Claude Code, Cursor y agentes de IA

npm version npm downloads License: MIT

@nahuelalbornoz/mercadolibre-mcp — servidor MCP (Model Context Protocol) para vendedores de Mercado Libre. 11 tools de operación (con write-back), proxy al MCP oficial de ML, token-store Supabase multi-tenant, y knowledge tools ("TRAID ML Hub", v1.2.0+) que exponen features, gotchas y patrones reusables programáticamente. Compatible con Claude Code, Cursor, Continue y cualquier cliente MCP.

npx @nahuelalbornoz/mercadolibre-mcp

Por qué esta vs las alternativas

  • vs el MCP oficial de ML: este paquete lo envuelve (Capa 0, tools official_*, siempre actualizado server-side) y le agrega las operaciones de seller que el oficial no expone (precio/stock/preguntas/ads con write-back, métricas, reputación, competencia).

  • vs @nahuelalbornoz/mercadolibre-mcp-read: ese es el subset read-only (7 tools, sin riesgo de tocar la tienda). Usá este paquete completo cuando necesites escribir (precios, stock, respuestas, ads); usá el -read si solo hacés análisis/reporting.

  • Auth flexible: 3 modos (Supabase multi-tenant, token directo, auto-refresh standalone) — elegís según si tenés un backend (n8n/cron) renovando el token o no.


Related MCP server: Amazon Seller MCP

Arquitectura — 5 capas

CAPA 4 · _meta_*    introspection (TBD v1.2.0 GA)
CAPA 3 · flow_*     composite workflows opt-in (TBD v1.2.0-rc)
CAPA 2 · traid_*    knowledge tools ★ NUEVO en v1.2.0
CAPA 1 · ml_*       endpoints ML hand-coded (11 v1.0 + 9 nuevas en beta)
CAPA 0 · official_* proxy MCP oficial ML (v1.1.0)

Capa

Cuándo cambia

Quién la usa

0 — official

Cuando ML actualiza server-side (transparente)

Devs buscando docs ML on-demand

1 — ml

Cuando descubrimos gotcha o endpoint nuevo

Cualquier tool de Capa 3 o devs

2 — traid

Cuando agregamos feature al knowledge/

Todo agente Claude arrancando feature ML en cualquier repo TRAID

3 — flow

Cuando pulimos un workflow de negocio

Proyectos cliente que activan el flow via config

4 — meta

Casi nunca

Devs debuggeando conexión MCP


Capa 1 — Tools ML (11 v1.0 + extensiones)

Las 11 tools existentes v1.0 (preservadas con backwards-compat 100%):

Tool

Descripción

Tipo

list_products

Lista productos/publicaciones de un vendedor

Lectura

get_orders

Obtiene órdenes/ventas con detalle

Lectura

update_price

Actualiza precio de una publicación

Escritura

update_stock

Actualiza stock de una publicación

Escritura

list_questions

Lista preguntas recibidas

Lectura

answer_question

Responde una pregunta

Escritura

get_item_metrics

Métricas: visitas, conversión, salud

Lectura

manage_ads

Gestiona Product Ads (activar/pausar/status)

Escritura

get_reputation

Reputación del vendedor

Lectura

search_competitors

Busca productos de la competencia

Lectura

get_categories

Categorías y atributos para publicar

Lectura

price_to_win

Precio para ganar el buy-box / competencia de catálogo

Lectura

price_history

Historial de cambios de precio de una publicación

Lectura

stockout_risk

Riesgo de quiebre de stock (días de cobertura + velocidad)

Lectura

Las 3 últimas (price_to_win, price_history, stockout_risk) se sumaron en la fusión meli-seller-mcp (2026-07-18) — ver más abajo.

En v1.2.0-beta llegan 9 tools más con prefijo ml_* para endpoints validados que faltaban: ml_items_price_to_win, ml_users_items_visits_bulk, ml_products_catalog, ml_products_catalog_items, ml_items_shipping_options, ml_marketplace_benchmarks (con pre-flight Global Selling check), ml_orders_billing, ml_claims_search, ml_stock_fulfillment. Ver spec-capa1-ml-raw.md.


Capa 2 — Knowledge tools (★ nuevo)

Tools que consultan una base de conocimiento propia. Desde 1.2.0-alpha.3 el paquete NO incluye ninguna base de conocimiento interna: sin configuración, estas tools responden vacío. Quien quiera usarlas debe apuntar a su propia base con TRAID_KNOWLEDGE_MODE=filesystem y TRAID_KNOWLEDGE_PATH.

traid_feature_lookup(query, limit?, category?)

Busca features reusables en la base de conocimiento configurada.

traid_client_context(slug?)

Devuelve el contexto del cliente actual de la base configurada. Auto-detect via TRAID_CLIENT_SLUG env.

TBD en próximas alphas:

  • traid_pattern_for(use_case) — patrón reusable para un caso de uso

  • traid_gotcha_search(query) — busca gotchas API ML conocidos

  • traid_endpoint_catalog(pattern?) — endpoints validados/rotos/workarounds

  • traid_sql_snippet(domain) — schemas SQL canónicos

  • traid_stack_advice(component) — recomendación stack TRAID 2026

  • traid_anti_pattern_check(description) — check vs 10 anti-patterns

Documentación oficial de Mercado Libre: https://developers.mercadolibre.com.ar/


Capa 0 — Proxy MCP oficial ML

Al boot, conecta al servidor oficial https://mcp.mercadolibre.com/mcp y re-registra sus tools con prefijo official_*. Cuando ML agrega endpoints, los ves automáticamente sin re-buildear.

Tools típicas: official_search_documentation, official_get_documentation_page, official_product_description, official_product_reviews, official_seller_reputation.

Desactivable con ML_SKIP_UPSTREAM_PROXY=1 o TRAID_DISABLE_LAYERS=official.


Setup

Tres modos de autenticación (orden de prioridad — se elige el primero configurado):

Opción A: Supabase (multi-tenant, recomendado v1.1.0+)

{
  "mcpServers": {
    "traid-ml-hub": {
      "command": "npx",
      "args": ["-y", "@nahuelalbornoz/mercadolibre-mcp"],
      "env": {
        "SUPABASE_URL": "https://YOUR_PROJECT.supabase.co",
        "SUPABASE_SERVICE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}",
        "ML_ACCOUNT_LABEL": "miami",
        "ML_TOKEN_TABLE": "oauth_tokens",
        "ML_SITE_ID": "MLA",

        "TRAID_CLIENT_SLUG": "mi-cliente",
        "TRAID_KNOWLEDGE_MODE": "bundled"
      }
    }
  }
}

Schema mínimo esperado de la tabla de tokens:

create table oauth_tokens (
  account_label text primary key,
  access_token  text not null,
  refresh_token text,
  expires_at    timestamptz,
  updated_at    timestamptz default now()
);

Opción B: Token directo

{
  "env": {
    "ML_ACCESS_TOKEN": "APP_USR-...",
    "ML_SITE_ID": "MLA",
    "TRAID_CLIENT_SLUG": "mi-cliente"
  }
}

Opción C: Auto-refresh standalone

{
  "env": {
    "ML_CLIENT_ID": "tu_client_id",
    "ML_CLIENT_SECRET": "tu_client_secret",
    "ML_REFRESH_TOKEN": "tu_refresh_token",
    "ML_SITE_ID": "MLA"
  }
}

Env vars v1.2.0+

Env

Default

Propósito

TRAID_CLIENT_SLUG

(vacío)

Slug del cliente actual en tu base de conocimiento (ej: mi-cliente). Habilita traid_client_context sin args.

TRAID_KNOWLEDGE_MODE

bundled

bundled (default; desde alpha.3 el paquete no trae base, así que las tools traid_* responden vacío) · filesystem (lee de tu propia base via TRAID_KNOWLEDGE_PATH) · pinecone (v1.3).

TRAID_KNOWLEDGE_PATH

(vacío)

Path a tu base de conocimiento (solo modo filesystem).

TRAID_FLOWS_ENABLED

(vacío)

CSV con nombres de flow_* a registrar. Default vacío = solo Capas 0+1+2+4.

TRAID_DISABLE_LAYERS

(vacío)

CSV de capas a deshabilitar (official,ml,traid,flow).

GCP_PROJECT_ID

(vacío)

Activa flows que usan Vertex Gemini. Sin esto, los flows W3.* arrancan disabled.

Env vars existentes v1.1.0 (preservadas): ML_ACCESS_TOKEN, ML_CLIENT_ID, ML_CLIENT_SECRET, ML_REFRESH_TOKEN, ML_SITE_ID, ML_ACCOUNT_LABEL, ML_TOKEN_TABLE, SUPABASE_URL, SUPABASE_SERVICE_KEY, ML_SKIP_UPSTREAM_PROXY.


Sites soportados

Site ID

País

MLA

Argentina

MLU

Uruguay

MLB

Brasil

MLC

Chile

MLM

México

MCO

Colombia

CBT

Global Selling (cross-border)


Uso desde Claude

"Listame los productos activos"
"Mostrá las órdenes de hoy"
"Actualizá el precio de MLA123456 a $5000"
"Qué preguntas sin responder tengo?"
"Buscá competencia para repuestos de freno Toyota"

# Nuevo en v1.2.0 (Capa 2):
"Buscame features de TRAID relacionadas a OAuth multi-tenant"
"Qué contexto tengo del cliente actual?"

Desarrollo

cd PROYECTOS/mercadolibre-mcp
npm install
npm run build               # Compilar TypeScript
npm run build:knowledge     # Regenerar data/knowledge.json desde CONOCIMIENTO-NAHUEL
npm run dev                 # Dev con tsx + reload

Requiere que el repo CONOCIMIENTO-NAHUEL esté en ../CONOCIMIENTO-NAHUEL para build:knowledge.

Tests del knowledge snapshot

node -e "const {searchFeatures} = require('./dist/knowledge/loader.js'); console.log(searchFeatures('repricing', {limit: 3}))"

Seguridad

  • Auto-refresh serializado (single-flight + lease CAS): el refresh del token (modo standalone) está serializado in-process — dos refrescos concurrentes ya no revocan la cuenta (el refresh_token de ML es de un solo uso). Con Supabase configurado, además se serializa entre procesos/réplicas con un lease compare-and-set (CAS) sobre oauth_tokens (columnas refresh_in_progress/locked_until). Requiere aplicar migrations/0001_oauth_tokens_lease.sql (idempotente, RLS inline service_role-only). Sin la migración, el single-flight in-process sigue protegiendo la carrera. Ver la sección "Fusión meli-seller-mcp".

  • Nunca se loguea el valor de un token, ni truncado. Solo "presente/ausente/rotado".

  • Candados de tools: el registro pasa por un gate (src/tool-guard.ts) que corta el arranque si se intentara registrar una tool de compra u operación destructiva (buy_*, purchase, checkout, delete, cancel, refund, pay*, en inglés y español). Las 4 tools de escritura permitidas (update_price, update_stock, answer_question, manage_ads) están en una allowlist explícita.

  • Reportar vulnerabilidades: issues del repo o contacto@traid.agency.


Fusión meli-seller-mcp — 2026-07-18

Este paquete absorbió lo mejor del repo hermano meli-seller-mcp (un MCP read-only más nuevo, con la auth blindada y analytics porteadas de globalstats-haussman), que queda archivado. Qué se trajo:

Absorbido:

  • Lease CAS del token (seguridad): el refresh del modo standalone ahora puede serializarse cross-proceso con un lease en la DB, no sólo in-process. Cableado en src/auth.ts sobre helpers de src/token-store.ts (tryAcquireRefreshLease/releaseRefreshLease/persistRefreshedToken/readTokenRow/waitForFreshDbToken). Se activa cuando hay Supabase configurado; ML_AUTH_MODE=standalone fuerza el auto-refresh aunque haya Supabase (para usar el lease). Migración nueva: migrations/0001_oauth_tokens_lease.sql.

  • 3 analytics read-only nuevas (Capa 1, src/tools/), reimplementadas en TypeScript puro con el patrón server.tool()→content del paquete:

    • price_to_win — precio para ganar el buy-box / competencia de catálogo (GET /items/{id}/price_to_win?version=v2).

    • price_history — historial de cambios de precio (GET /pricing-automation/items/{id}/price/history).

    • stockout_risk — riesgo de quiebre de stock: días de cobertura y velocidad de venta, calculado en vivo (órdenes + stock). Suma un helper mlGetAll (paginado offset/limit) a src/client.ts.

  • Candados de tools destructivas/de compra (ver Seguridad).

Qué falta / fuera de alcance:

  • forecast_demand (pronóstico de demanda Prophet/Python) NO se portó: introduce una dependencia de host (Python + prophet + pandas) que no queremos como dependencia dura en todos los deploys. Queda como trabajo futuro detrás de un flag.

  • El broker de tokens central: a futuro, el refresh delegará en el token broker de traid-saas (/internal/v1/token) cuando esté vivo; el lease CAS local queda como defensa propia (funciona sin el broker y lo complementa).

Licencia

MIT

Available Tools

16 tools
answer_questionB

Responde una pregunta en Mercado Libre. La respuesta es pública y visible por todos los compradores.

Inputs: text (required), question_id (required).

get_categoriesA

Obtiene categorías de Mercado Libre y sus atributos. Útil para saber qué categoría usar al publicar y qué atributos son requeridos.

Inputs: query, category_id.

get_item_metricsB

Obtiene métricas de una publicación: visitas, salud de publicación y datos de catálogo.

Inputs: item_id (required), date_to, date_from.

get_ordersA

Obtiene las órdenes/ventas de un vendedor. Incluye comprador, items, envío y pagos.

Inputs: seller_id (required), limit, offset, status, +2 more.

get_reputationA

Obtiene la reputación de un vendedor: nivel, ventas completadas, reclamos, cancelaciones y tiempo de despacho.

Inputs: seller_id (required).

list_productsB

Lista los productos/publicaciones de un vendedor en Mercado Libre. Retorna título, precio, stock, estado, link y thumbnail.

Inputs: seller_id (required), limit, offset, status.

list_questionsB

Lista las preguntas recibidas en publicaciones de Mercado Libre. Puede filtrar por item o estado (sin responder, respondidas).

Inputs: seller_id (required), limit, offset, status, +1 more.

manage_adsC

Gestiona Product Ads de Mercado Libre: activar, pausar o consultar estado de publicidad de un item.

Inputs: action (required), item_id (required), seller_id (required), daily_budget.

price_historyA

Historial de cambios de precio de una publicación de Mercado Libre (solo lectura). Devuelve los eventos de cambio de precio del item en una ventana de días, paginados. Requiere item_id; days/page/size son opcionales.

Inputs: item_id (required), days, page, size.

price_to_winA

Precio para ganar el buy-box / competencia de catálogo de una publicación en Mercado Libre (solo lectura). Devuelve precio actual, precio sugerido para ganar, estado de competencia, participación de visitas y boosts que afectan el ranking.

Inputs: item_id (required).

search_competitorsB

Busca productos de la competencia en Mercado Libre. Retorna top resultados con precio, vendedor, ventas y envío gratis.

Inputs: query (required), sort, limit, price_max, +2 more.

stockout_riskB

Riesgo de quiebre de stock por publicación: días de cobertura y velocidad de venta (unidades/día) sobre una ventana histórica. Read-only, calculado en vivo desde la API de Mercado Libre (órdenes + stock). Sin escrituras.

Inputs: limit, status, seller_id, window_days, +3 more.

traid_client_contextA

Devuelve metadata operativa del cliente TRAID actual (seller_ids, schema Supabase, n8n folder, repos, bloqueantes pendientes). Si no se pasa slug, usa TRAID_CLIENT_SLUG env var (auto-detect). Usar al arrancar sesión Claude en un proyecto cliente para cargar contexto sin parsear archivos.

Inputs: slug.

traid_feature_lookupA

Busca features reusables en la base de conocimiento configurada (TRAID_KNOWLEDGE_MODE=filesystem y TRAID_KNOWLEDGE_PATH; el paquete no trae ninguna base incluida). Devuelve top N matches con descripción, cómo reusar y trade-offs. Ej: query="repricing".

Inputs: query (required), limit, category.

update_priceB

Actualiza el precio de una publicación en Mercado Libre. Retorna precio anterior y nuevo para confirmación.

Inputs: price (required), item_id (required).

update_stockA

Actualiza el stock/cantidad disponible de una publicación en Mercado Libre. Retorna stock anterior y nuevo.

Inputs: item_id (required), quantity (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools target clearly distinct resources (orders, metrics, ads, reputation, questions) or actions (update_price, update_stock, answer_question). The price cluster (price_to_win vs price_history vs update_price) and stockout_risk vs get_item_metrics require reading descriptions to distinguish, but each still has a distinct purpose.

    Naming Consistency3/5

    The majority follow a verb_noun snake_case pattern (get_orders, update_price, list_questions, answer_question). However, price_to_win, price_history, and stockout_risk are noun-phrase names without verbs, and the traid_* tools introduce a separate prefix, giving a mixed convention.

    Tool Count4/5

    16 tools is at the upper end but each maps to a concrete seller workflow (sales, metrics, ads, reputation, pricing, stock, questions). The set is coherent and mostly earns its count, though the two traid_* tools feel somewhat unrelated to the core Mercado Libre domain.

    Completeness3/5

    The seller analytics/management surface is strong (orders, listings, pricing, stock, questions, competitors), but there is no tool to publish/create a listing despite get_categories describing attributes needed 'al publicar', and no order fulfillment or shipping operations. These are notable gaps for a full seller lifecycle.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables managing Amazon seller listings, orders, pricing, inventory, and reports through the SP-API via MCP tools.
      15
      18 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to connect marketplace seller accounts, explore and call shop-level APIs, and manage orders, products, returns, inventory, pricing, and tracking with scoped read-only or read-write access.
      2
      MIT