baselinker-mcp

Un servidor MCP que pone toda la API de BaseLinker — pedidos, facturas, devoluciones, mensajería, CRM, almacenes, productos — delante de un cliente LLM como Claude Code, Claude Desktop o Cursor.

• Completo. Los 179 métodos de API documentados, ninguno simulado.

• Solo lectura hasta que se indique lo contrario. Los 92 métodos de escritura permanecen invisibles a menos que se active la opción; con la escritura desactivada, cada herramienta informa de readOnlyHint: true.

• Local o remoto. stdio para un cliente en tu máquina, o Streamable HTTP con OAuth 2.1 (Keycloak) para un endpoint compartido en Internet.

"How many orders came in yesterday that aren't paid yet?"
"Which catalog products dropped below 5 in stock this week?"
"Pull the courier label for order 1234567 and tell me the tracking number."

Contenidos

• Inicio rápido

• Conexión de un cliente

• Herramientas

• Métodos de escritura

• Comportamiento que conviene conocer

• Despliegue remoto (HTTP + OAuth)

• Referencia de configuración

• Solución de problemas

• Desarrollo

Related MCP server: TextQL MCP Server

Inicio rápido

Requisitos: Node.js 20 o superior, y un token de API de BaseLinker desde el panel de BaseLinker en Cuenta y otros → Mi cuenta → API.

git clone https://github.com/PiotrRaszkowski/baselinker-mcp.git
cd baselinker-mcp
npm install
npm run build
cp .env.example .env     # paste your token into BASELINKER_API_TOKEN

El token también puede venir directamente del entorno, que tiene prioridad sobre .env. .env se lee desde la raíz del paquete, por lo que el servidor se inicia correctamente sin importar desde qué directorio lo lance tu cliente MCP.

Conexión de un cliente

Claude Code

claude mcp add baselinker -e BASELINKER_API_TOKEN=your-token -- node /path/to/baselinker-mcp/dist/index.js

Claude Desktop, Cursor o cualquier configuración de mcpServers

{
  "mcpServers": {
    "baselinker": {
      "command": "node",
      "args": ["/path/to/baselinker-mcp/dist/index.js"],
      "env": { "BASELINKER_API_TOKEN": "your-token" }
    }
  }
}

Para un endpoint compartido accesible desde claude.ai, consulta Despliegue remoto.

Herramientas

179 herramientas separadas saturarían el contexto de un modelo y su capacidad para elegir entre ellas, así que los métodos se agrupan de la misma manera que los agrupa la propia BaseLinker: diez herramientas, una por categoría de API. Cada una acepta un nombre de method y un objeto parameters, y la descripción de cada herramienta enumera los métodos que acepta junto con sus parámetros y sugerencias de paginación.

Los recuentos siguientes son lectura + escritura; los métodos de escritura solo aparecen cuando BASELINKER_ALLOW_WRITES=true.

Los parámetros se validan contra un esquema Zod por método antes de enviar nada, por lo que una llamada mal formada devuelve un error legible en lugar de un código de error de BaseLinker. Las claves desconocidas se reenvían sin tocar: BaseLinker añade parámetros sin previo aviso, y el servidor no se rompe cuando lo hace.

Métodos de escritura

Desactivados por defecto. Para activarlos:

BASELINKER_ALLOW_WRITES=true

Mientras estén desactivados, los métodos de escritura no aparecen en la enumeración method de ninguna herramienta ni se pueden llamar. Activarlos enciende los 92 a la vez: crear, actualizar y eliminar pedidos, productos, existencias, precios, facturas, envíos, devoluciones y documentos de almacén. Algunos de ellos eliminan registros; otros envían envíos reales de mensajería que cuestan dinero real. No hay control por método, así que activa la escritura solo para un cliente en el que confíes y considera ejecutar una segunda instancia de solo lectura para todo lo demás.

Comportamiento que conviene conocer

Límite de peticiones. BaseLinker permite 100 peticiones por minuto. Un limitador de ventana deslizante del lado del cliente lo hace cumplir: las llamadas excesivas esperan su turno en lugar de fallar.

Paginación. Las respuestas de listas están limitadas (normalmente 100 elementos para pedidos, facturas y devoluciones; 1000 para productos de catálogo). La descripción de cada método incluye la sugerencia específica, por ejemplo, getOrders requiere que date_confirmed_from se establezca en el date_confirmed del último pedido devuelto más un segundo, mientras que getInventoryProductsList acepta una page basada en 1.

Descargas de archivos. getLabel, getProtocol, getCourierDocument, getInvoiceFile, getInventoryDocumentFile y getInventoryFulfillmentDeliveryLabels devuelven el archivo como un recurso incrustado de MCP con un tipo MIME real. Pasa el parámetro adicional save_to_path (gestionado localmente, nunca enviado a BaseLinker) para decodificarlo en disco y obtener { saved_to, extension, bytes }. Esto solo tiene sentido a través de stdio, donde el servidor se ejecuta en tu propia máquina; a través de HTTP se rechaza con un error explicativo.

Despliegue remoto (HTTP + OAuth)

Con --transport http, el servidor habla Streamable HTTP y actúa como un servidor de recursos OAuth 2.0 (RFC 9728): publica metadatos de recursos protegidos, responde a llamadas no autenticadas con 401 más un desafío WWW-Authenticate, y verifica cada token de acceso como un JWT RS256 contra el JWKS de un reino de Keycloak. Los clientes descubren el reino a partir de esos metadatos y se registran mediante el registro dinámico de clientes, por lo que no se configura ningún ID de cliente ni secreto en ninguno de los dos lados.

node dist/index.js --transport http --host 0.0.0.0 --port 8000 --path /mcp

El transporte HTTP se niega a arrancar sin un reino de autenticación a menos que se desactive explícitamente con BASELINKER_MCP_AUTH_DISABLED=true. Es deliberado: con la escritura activada, un endpoint no autenticado entrega tu cuenta de BaseLinker a Internet.

deploy/ contiene la guía completa: configuración del reino de Keycloak, un servicio Compose endurecido con etiquetas de Traefik, fragmentos de proxy inverso para Caddy y nginx, comandos de verificación y un modelo de amenazas. La versión corta:

docker build -t baselinker-mcp:0.2.0 .
docker run -d --name baselinker-mcp -p 8000:8000 \
  -e BASELINKER_API_TOKEN=your-token \
  -e BASELINKER_MCP_AUTH_REALM_URL=https://keycloak.example.com/realms/myrealm \
  -e BASELINKER_MCP_AUTH_BASE_URL=https://mcp.example.com \
  baselinker-mcp:0.2.0

Luego apunta un cliente a él:

claude mcp add --transport http baselinker https://mcp.example.com/mcp

En claude.ai es Configuración → Conectores → Añadir conector personalizado, URL https://mcp.example.com/mcp, con ID de cliente y Secreto de cliente vacíos.

Una cosa que debe quedar clara antes de exponerlo: el token de BaseLinker es compartido. Todos los que puedan iniciar sesión en el reino operan en la misma cuenta de BaseLinker. Consulta SECURITY.md para el resto de los límites.

Referencia de configuración

Todo es una variable de entorno; .env en la raíz del paquete se carga automáticamente.

Siempre

Transporte

Las banderas de línea de comandos tienen prioridad sobre estas.

OAuth: obligatorio cuando el transporte es http

Las listas aceptan comas o espacios.

Solución de problemas

Hay más casos específicos de OAuth en deploy/README.md.

Desarrollo

npm run dev         # run from sources (tsx), stdio transport
npm run start:http  # built server, HTTP transport
npm test            # unit tests — fully offline, no live API calls
npm run check       # format check + typecheck + tests, what CI runs
npm run smoke       # manual smoke test against the live API (uses .env)
npm run inspect     # MCP Inspector against the built server

CONTRIBUTING.md cubre cómo se compone el registro de herramientas y qué tener en cuenta al añadir un método.

Licencia

MIT. No está afiliado ni respaldado por BaseLinker.