mcp-xubio

Un servidor MCP que expone la API de contabilidad de Xubio como herramientas para Claude, así podés consultar clientes, facturas, productos y saldos hablando en lenguaje natural en vez de navegar la interfaz web.

¿Sos contador y solo querés instalarlo? Guía paso a paso con capturas y descarga en un clic: https://ignacio-llabot.github.io/mcp-xubio/

Solo lectura. Las 52 herramientas son endpoints GET. Los endpoints de escritura de Xubio crean comprobantes fiscales reales y piden el CAE a la AFIP — esos quedan deliberadamente afuera.

Requisitos

• Una cuenta de Xubio en el plan PLUS o superior — la API no está disponible en planes menores
• Para usarlo: Claude Desktop (trae su propio Node — no hay que instalar nada más)
• Para armar el bundle: Node 18+ (desarrollado sobre 22.19)

Instalación para usuarios finales (contadores) — sin terminal, sin Node

Distribuí el único archivo mcp-xubio.mcpb (se arma más abajo). El usuario:

1. Hace doble clic en mcp-xubio.mcpb → Claude Desktop abre el diálogo de instalación.
2. Pega su Client ID y su Secret ID en el formulario (se obtienen en Xubio: Configuración → Integraciones → API de Xubio → Nueva App Cliente — requiere el plan PLUS).
3. Hace clic en Instalar.

Claude Desktop trae su propio Node.js, así que no hay nada que instalar ni ningún archivo de configuración que editar. Las credenciales van directo al llavero (keychain) del sistema desde el formulario — nunca a un archivo de texto. Si Windows SmartScreen advierte sobre un bundle sin firmar descargado de la web, hacé clic en Más información → Ejecutar de todas formas; alojá el archivo en un lugar de confianza para evitar la advertencia.

Armar el bundle .mcpb (mantenedor, una vez por release)

npm install
npm run bundle     # tsc → dist, después mcpb pack → mcp-xubio.mcpb

manifest.json declara los dos campos de credenciales como el formulario de instalación. El bundle se verifica desempaquetándolo y corriendo dist/index.js de forma autónoma.

Instalación para desarrolladores (Claude Code / CLI)

npm install
npm run build

Credenciales

En Xubio: Configuración → Integraciones → API de Xubio → Nueva App Cliente. Obtenés un Client_id y un Secret_id.

El servidor las lee del entorno y nunca las escribe en disco:

Variable	Requerida	Significado
XUBIO_CLIENT_ID	sí, al momento de llamar	Client_id de la app de Xubio
XUBIO_SECRET_ID	sí, al momento de llamar	Secret_id de la app de Xubio
XUBIO_TOOLS	no	operationIds separados por coma. Acota el set de herramientas. Vacío = sin filtro.

Las credenciales solo hacen falta cuando una herramienta se llama. El servidor arranca y responde tools/list sin ellas, que es lo que permite que toda la suite de tests corra offline.

Registrar en Claude (CLI)

claude mcp add xubio \
  --env XUBIO_CLIENT_ID=... \
  --env XUBIO_SECRET_ID=... \
  -- node /ruta/absoluta/a/mcp-xubio/dist/index.js

52 herramientas ocupan bastante contexto en cada sesión. Si usás solo algunas, acotá:

--env XUBIO_TOOLS=getClienteBeans,getFacturaVentaBeans,getProductoVentaBeans

En Claude Code, las herramientas MCP se difieren por defecto (tool search): solo se cargan los nombres hasta que Claude las busca, así que el costo de contexto real es mínimo y no hace falta filtrar. En Claude Desktop, filtrar con XUBIO_TOOLS sí reduce lo que se envía.

Qué obtenés

Los nombres de las herramientas son los operationId del spec; las descripciones vienen directo de Xubio:

getClienteBeans                 Obtiene todos los Clientes
getFacturaVentaBeans            Obtiene listado de Facturas de Venta
getAsientoContableManualBeans   Obtiene listado de Asientos Contables Manuales
getEmpresaBean                  Obtiene los datos de Mi Empresa

Listarlas todas:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| node dist/index.js \
| node -e "let s='';process.stdin.setEncoding('utf8').on('data',d=>s+=d).on('end',()=>{const r=s.trim().split('\n').map(JSON.parse).find(m=>m.id===2);r.result.tools.forEach(t=>console.log(t.name))})"

En Windows PowerShell, escribí los frames a un archivo y redirigí en vez de pipear — PowerShell 5.1 antepone un BOM UTF-8 al stdin de un comando nativo, lo que corrompe el primer frame.

Prueba en vivo

export XUBIO_CLIENT_ID='...' XUBIO_SECRET_ID='...'
# después llamá getClienteBeans desde cualquier cliente MCP

Fallas esperables que conviene reconocer:

Respuesta	Causa
XUBIO_CLIENT_ID / XUBIO_SECRET_ID are not set	Al entorno del servidor le faltan. Ojo: un cliente MCP de escritorio no hereda tu shell interactiva.
HTTP 400: {"error":"invalid_client"}	Las credenciales están seteadas pero son incorrectas.
HTTP 403	Normalmente, una cuenta por debajo del plan PLUS.

Cómo funciona

src/index.ts tiene ~172 líneas. Las herramientas se generan al arrancar desde un swagger.json incluido en el repo — una herramienta por operación GET, mapeando los tipos de parámetro de Swagger a un esquema Zod. Nada se escribe a mano por endpoint, así que un endpoint nuevo de Xubio aparece simplemente refrescando el spec:

curl -o swagger.json https://xubio.com/API/1.1/swagger.json
npm test

El spec se commitea en vez de descargarse en tiempo de ejecución: la lista de herramientas queda determinística, el servidor no depende de la red al arrancar, y un cambio en la API de Xubio aparece como un diff revisable.

Tests

npm test        # compila, después corre node --test (30 tests, sin framework)
npx tsc --noEmit

Todo es offline — el intercambio de token y las llamadas a la API se testean contra mocks de node:test. Lo único que los mocks no pueden probar es una vuelta completa con credenciales reales; para eso está la prueba en vivo de arriba.

Límites conocidos

Marcados en el código con comentarios, cada uno indicando su camino de mejora:

• Paginación. /comprobanteVentaBean y /comprobanteCompraBean paginan mediante headers HTTP que Xubio documenta solo en prosa y no declara como parámetros de Swagger, así que el generador no puede verlos. Obtenés una única página sin paginar por llamada.
• Forma de las respuestas. El spec declara las respuestas de listado como un único objeto, pero la API devuelve un array. El JSON se pasa tal cual, así que el desajuste no cuesta nada — no lo "arregles" validando contra el esquema declarado.
• Concurrencia. Llamadas iniciales simultáneas pueden generar cada una un token. Es inocuo (todos los tokens son válidos, gana el último) y no amerita un lock hasta que aparezca en la práctica.

Aviso

Proyecto no oficial, hecho por la comunidad. Sin afiliación, respaldo ni soporte de Xubio. "Xubio" y las marcas relacionadas pertenecen a su respectivo dueño. El swagger.json incluido es la propia especificación pública de la API de Xubio, incorporada solo para que la lista de herramientas quede determinística — refrescala desde el endpoint oficial (ver Cómo funciona). Usalo bajo tu propia responsabilidad: accede a tus datos contables reales. Es solo lectura, pero siguen siendo tus datos.

Licencia

MIT — ver LICENSE.