Tiendanube MCP Server

tiendanube-mcp

Servidor MCP para desarrollar apps e integraciones en Tiendanube y Nuvemshop.

Instalación

claude mcp add tiendanube -- npx -y @commenteme/tiendanube-mcp

Requiere Node >= 18. El cliente ejecuta el servidor con npx, así que no hace falta instalarlo. Para Claude Desktop, Cursor, Windsurf, VS Code y otros clientes, mira Otros clientes.

Uso rápido

Reinicia el cliente y pide lo que necesitas en lenguaje natural. El asistente elige la herramienta:

• "Que scope necesita POST /orders/{id}/fulfillment-orders/{id}/tracking-events?"
• "Arma el receptor de webhooks para order/paid y app/uninstalled con la verificación de firma"
• "Genera el flujo de instalación OAuth del app 1234"
• "Que eventos de webhook hay para fulfillment orders?"
• "Cómo funcionan los slots del checkout en NubeSDK?"

Que incluye

Para quien escribe apps de partners e integraciones propias: Admin API, OAuth, webhooks, NubeSDK, apps del Admin y temas.

• Documentación oficial en vivo: search-docs y read-doc leen las páginas Markdown que nuvemshop.dev publica para agentes, en inglés, portugués o español. Cada respuesta trae la URL de la página.
• Índices de la Admin API 2025-03, sin red: 228 endpoints con el scope que piden y su página de referencia, los 18 grupos de scopes OAuth y los 57 eventos de webhook, con los tres de privacidad obligatorios aparte.
• Scaffolding: el receptor de webhooks (firma x-linkedstore-hmac-sha256 sobre el body crudo, 200 inmediato y una prueba) y el flujo OAuth (redirección con state y canje del code con body JSON). Las herramientas devuelven los archivos (ruta y contenido) para que el cliente los escriba.
• Sin credenciales: no pide token de tienda, no escribe en disco y solo se conecta a nuvemshop.dev y tiendanube.dev.

Funciona con Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code, Windsurf y cualquier cliente MCP con transporte stdio.

Por que existe

Tiendanube tiene un Admin MCP oficial para operar una tienda conversando: crear productos, ajustar stock y precios, ver pedidos, manejar cupones y promociones. Si lo que necesitas es operar una tienda, ocupa ese. Para quien construye sobre la plataforma no había servidor: este responde que endpoint, que scope y que evento usar, y entrega el código de las partes que todo app repite. Va junto con las skills de tiendanube-skills.

Documentación

Otros clientes

En claude_desktop_config.json (Claude Desktop), ~/.cursor/mcp.json o .cursor/mcp.json (Cursor) y ~/.codeium/windsurf/mcp_config.json (Windsurf):

{
  "mcpServers": {
    "tiendanube": {
      "command": "npx",
      "args": ["-y", "@commenteme/tiendanube-mcp"]
    }
  }
}

En VS Code, .vscode/mcp.json:

{
  "servers": {
    "tiendanube": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@commenteme/tiendanube-mcp"]
    }
  }
}

Codex, con el CLI (queda en ~/.codex/config.toml):

codex mcp add tiendanube -- npx -y @commenteme/tiendanube-mcp

O a mano, en ~/.codex/config.toml o en .codex/config.toml del proyecto:

[mcp_servers.tiendanube]
command = "npx"
args = ["-y", "@commenteme/tiendanube-mcp"]

Gemini CLI, con el CLI (-s user lo deja en ~/.gemini/settings.json; sin -s, en .gemini/settings.json del proyecto):

gemini mcp add -s user tiendanube npx -y @commenteme/tiendanube-mcp

GitHub Copilot CLI, en ~/.copilot/mcp-config.json o en .mcp.json del proyecto, con el mismo JSON de mcpServers de arriba. En VS Code, Copilot usa el .vscode/mcp.json.

Cualquier cliente con transporte stdio sirve: el comando es npx y los argumentos, -y @commenteme/tiendanube-mcp. En Claude Code, --scope project deja la configuración en .mcp.json para compartirla con el equipo.

Herramientas

De dónde vienen los datos

La documentación de nuvemshop.dev no tiene licencia abierta, así que el paquete no la trae: search-docs y read-doc la leen en vivo y la guardan solo en memoria mientras corre el proceso. Los archivos de data/ son índices de hechos armados por scripts/ingerir.ts desde esas páginas: métodos, rutas, nombres de recursos, de scopes y de eventos, y el enlace a cada página. Ningún texto de la documentación entra en el paquete. Las contradicciones que encontramos en la documentación están en tiendanube-skills/docs/divergencias.md.

Desarrollo

git clone https://github.com/commentemeapp/tiendanube-mcp.git
cd tiendanube-mcp
npm ci
npm run check

npm run check es el gate: Prettier, tipos, build, las pruebas (las herramientas de documentación leen páginas sintéticas de test/fixtures/, sin red), probar-mcp, que arranca el servidor por stdio como un cliente, y la búsqueda de rastros. Para probarlo en un cliente:

claude mcp add tiendanube-local -- node /ruta/a/tiendanube-mcp/build/index.js

Actualizar los índices

Corre npm run ingerir: baja las páginas de recursos de la versión 2025-03, el llms.txt, la autenticación y los webhooks, y reescribe data/. Después, npm run check y commitea data/: el paquete lo necesita.

Ramas y publicación

El trabajo nace en una rama salida de dev y el PR va contra dev. Después de probar localmente, dev se promueve a main con merge de la rama completa. El CI corre npm run check en Node 18, 20 y 22.

Para publicar, sube la versión en package.json, server.json y CHANGELOG.md y empuja un tag v*: el workflow publish.yml corre el gate, publica en npm con provenance, crea el GitHub Release y publica server.json en el MCP Registry. Los cambios de cada versión están en CHANGELOG.md.

Contribuir · Licencia

Abre un PR contra dev, con Conventional Commits y npm run check en verde.

MIT. Lo que el paquete trae y lo que no, en NOTICE.

---

Hecho por commente.me · hablecon@commente.me