Tutorial: conectar Xero a Claude Code con el MCP oficial de Xero (URL remota o npx local)

En dos frases

Xero ofrece ya una superficie oficial de Model Context Protocol para que Claude Code (y otros clientes MCP) consulten — y, si lo permites, cambien — una organización Xero sin exportar CSV. Una guía de mayo de 2026 escrita desde Madrid muestra un montaje de unos diez minutos que respondió a «¿qué está impagado este mes?»; el FAQ de Xero y el README del servidor open source aclaran las dos vías oficiales, los límites de plan y dónde las tools no te protegen.

Quién lo hace y qué tipo de evidencia es

Los pasos prácticos que convierten esto en un tutorial (y no en una ficha de producto) vienen de Evgeny en techconcepts.org, desde Madrid. En mayo de 2026 publicó una guía en primera persona: creó una Web app en Xero, metió @xeroapi/xero-mcp-server en la configuración MCP de Claude Code, completó el OAuth una vez y pidió facturas impagadas y resúmenes de gasto. Escribe como desarrollador que documenta un montaje que le funcionó, no como partner de Xero.

Tomamos otras tres fuentes como marco oficial y de comunidad, no como ahorro medido:

• El FAQ de Remote MCP de Xero, que fija la URL alojada (https://api.xero.com/mcp/v1), que el cliente debe soportar OAuth 2.0 con PKCE, que las apps Custom Connection no pueden usar Remote MCP, que el plan Starter solo vale contra la Demo Company, que Core o superior sirve para organizaciones reales, que cada llamada de tool actúa sobre una sola organización, y que las tools V1 no piden confirmación antes de cambiar datos.
• El paquete oficial autoalojado XeroAPI/xero-mcp-server en GitHub (licencia MIT; 383 estrellas y unas 12.180 descargas semanales en npm el 19 de octubre de 2026) y sus comandos publicados para listar facturas, contactos, bancos, PyG, balance de sumas y saldos y, con scopes de escritura, crear facturas, pagos y diarios.
• Textos e issues independientes: el resumen de Use Carly de julio de 2026 (el MCP vive en el chat; no es un programador de tareas), la issue #193 sobre fricción en lecturas masivas, y mensajes públicos en X sobre varias organizaciones y sobre contribuir un arreglo al servidor open source con Claude Code.

Nivel de evidencia: experiencia. Alguien hizo el montaje y publicó los pasos; Xero documenta el producto; nadie en estas fuentes publica un estudio controlado de tiempo frente a la interfaz de Xero.

El problema que aborda

Xero ya tiene paneles, informes guardados y conciliación bancaria. Lo que no te da de serie es un sitio donde ya trabajas — un terminal, Claude Desktop, Cursor — que responda «¿qué facturas vencen esta semana?» o «resume el gasto del trimestre por categoría» sin exportar un CSV, abrir tres pantallas y pegar números en un chat. Para un autónomo o un despacho pequeño que vive en Claude Code por otros motivos, ese cambio de contexto es la fricción.

Hay un segundo producto, distinto, que no debes confundir con este tutorial: el conector Xero del marketplace de Claude, añadido en abril de 2026 según la página de Anthropic. Lo firma Xero Limited, inicia sesión con OAuth y expone tools de solo lectura (PyG, posición de caja, vencidos, listados de facturas). Sirve para preguntar dentro de las apps de Claude. No es lo mismo que el Remote MCP para quien construye agentes, y no reivindica escritura.

Herramientas y arquitectura

Tres capas oficiales, un mismo trabajo:

1. Xero Remote MCP (alojado). URL del FAQ: https://api.xero.com/mcp/v1. Autorización OAuth 2.0 con PKCE, sin secreto de cliente que se cuele en un prompt. Documentado para Claude Desktop, Claude Code, Cursor y VS Code. Multi-organización: el usuario puede autorizar varias orgs en la misma app y decirle al agente cuál usar; cada llamada sigue yendo a una sola. Las Custom Connection no son elegibles. Las llamadas a la API aparecen en el Developer Portal bajo tu app; los prompts, no.
2. @xeroapi/xero-mcp-server autoalojado. Ejecutas npx -y @xeroapi/xero-mcp-server@latest (o fijas versión) y pasas XERO_CLIENT_ID / XERO_CLIENT_SECRET, o un bearer token si el cliente hace el OAuth. El README recomienda Custom Connections para Claude Desktop y pruebas locales. Los scopes cambiaron el 29 de abril de 2026: las conexiones anteriores usan scopes V1 agrupados; las nuevas, V2 granulares. El servidor prueba V1 y cae a V2 salvo que fijes XERO_SCOPES.
3. Claude Code (o Claude Desktop / Cursor) como cliente MCP que descubre las tools y convierte tu frase en llamadas.

El montaje de Evgeny en Madrid usó la vía 2 con una Web app (client ID, secreto, redirect http://localhost:3000/callback) porque, escribe, Custom Connection es más simple sobre todo en AU, NZ, UK y US, mientras que la Web app funciona en más sitios. Eso encaja con una limitación regional habitual; el FAQ de Remote MCP, por su parte, prefiere PKCE a pegar secretos de Web app en herramientas de IA. Si Remote MCP está en tu plan, úsalo por esa razón.

Según el README open source y el resumen de Evgeny, las tools alcanzan facturas, contactos, plan contable, pagos, bancos, presupuestos, notas de crédito, diarios manuales, PyG, balance, balance de sumas y saldos, vencidos de cobro y pago, tracking categories y (en regiones NZ/UK) nómina y ausencias. Existen tools de escritura (create-invoice, create-payment, create-bank-transaction, etc.). Trátalas como opcionales y peligrosas hasta tener hábito de revisión.

Paso a paso

Resumido con nuestras palabras. Usa la Demo Company hasta que las respuestas de solo lectura cuadren con las pantallas de Xero.

1. Elige la vía y el plan

Si construyes agentes o quieres un cliente MCP con posibilidad de escritura, parte del FAQ de Remote MCP: plan Core (o superior) para una organización real; Starter solo contra la Demo Company. Si no puedes usar Remote MCP (plan, cliente o restricciones de Custom Connection), usa el paquete npm oficial en local. No inventes un tercer servidor «de la comunidad» cuando existe el del fabricante: el FAQ argumenta que el servidor alojado comparte OAuth, permisos y límites de ritmo con el resto de la API.

2. Crea la app de desarrollador con scopes mínimos

Para Remote MCP, sigue la guía PKCE de Xero y concede solo los scopes de las tools que vas a llamar. Para el paquete local con Custom Connection, créala en el portal de desarrollador y añade todos los scopes de la lista V1 o V2 que corresponda a la fecha de creación de la conexión (el README enlaza ambas). Vía Web app de Evgeny: New app → Web app → redirect http://localhost:3000/callback → copia client ID y secreto a variables de entorno, no al chat ni a un fichero versionado.

Los límites de ritmo del FAQ son los de la API de Xero: 1.000 llamadas al día por organización en Starter, 5.000 en Core o superior.

3. Registra el servidor en Claude Code

Remote MCP. Añade la URL remota en los ajustes de MCP remoto del cliente y completa el login PKCE en el navegador. Xero documenta Claude Code entre los clientes.

Paquete local. En ~/.mcp.json (o claude_desktop_config.json de Claude Desktop) añade un bloque equivalente a:

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_ID": "${XERO_CLIENT_ID}",
        "XERO_CLIENT_SECRET": "${XERO_CLIENT_SECRET}"
      }
    }
  }
}

Si usas Node Version Manager, apunta command a la ruta completa de npx, como avisa el README. Reinicia Claude Code. En el primer uso, termina la ventana OAuth y Allow access para la organización.

4. Pregunta en solo lectura y concilia

Prompts de partida de Evgeny, alineados con lo que exponen las tools:

• «Muéstrame todas las facturas impagadas de los últimos 30 días.»
• «¿Cuáles fueron mis 5 categorías de gasto del último trimestre?»
• «Lista contactos con saldos vencidos.»
• «Resume la cuenta de resultados de este mes.»
• «¿Qué facturas vencen esta semana?»

Abre el mismo informe en Xero y compara totales, fechas y nombres. Si divergen, para: corrige scopes, organización o interpretación de fechas antes de fiarte del chat para decidir.

5. Activa escritura solo con una regla fija de confirmación

El FAQ de Xero es claro: las tools V1 no piden confirmación al usuario antes de cambiar datos. Tienes que decirle al agente que muestre el borrador y espere. En la práctica: deja los scopes de escritura apagados hasta que la lectura sea aburridamente correcta; luego añade solo los que necesites; mete en las instrucciones de Claude algo como «No crees ni actualices un registro de Xero hasta que yo responda OK al payload exacto». Prefiere borradores y Demo Company mientras aprendes.

6. Varias organizaciones, a propósito

En X (7 de octubre de 2026) Erik (@eladvisory) preguntó cómo conectar varias instancias de Xero con Claude Code. Las respuestas esbozaron dos patrones: una entrada MCP por organización con nombres distintos (xero-acme, xero-beta), o un login con cambio explícito de org. El FAQ de Remote MCP dice que un usuario puede autorizar varias organizaciones y debe indicar al agente sobre cuál actuar. En cualquier caso, di el nombre de la organización en cada prompt de escritura. Adivinar es facturar al cliente equivocado.

Un ejemplo concreto (tal como se publicó)

El objetivo declarado de Evgeny era simple: pedir a Claude las facturas impagadas sin salir del terminal. Tras registrar la Web app, el bloque MCP y un consentimiento OAuth, cuenta que Claude tradujo preguntas en lenguaje natural a llamadas a la API de Xero y devolvió respuestas formateadas. No publica captura de importes, nombre de cliente ni tiempo antes/después. Toma el ejemplo como prueba de conectividad, no como KPI.

Una segunda señal concreta de la comunidad open source: el 6 de mayo de 2026 Kalvin Mizzi escribió que encontró un bug en el servidor Xero MCP open source, hizo que Claude Code bifurcara el repositorio, escribiera el arreglo, abriera un pull request y respondiera a la revisión hasta el merge — «primera vez que contribuyo a un proyecto que no había leído». Eso no mide la calidad contable; muestra que la gente ejecuta el mismo paquete de punta a punta.

Resultados declarados y fricción (con fuentes)

Afirmación	Quién lo dice	Qué no es
~10 minutos hasta un camino de lectura Claude Code ↔ Xero	Evgeny, mayo 2026	No es un estudio cronometrado; no se midió frente a la UI
URL de Remote MCP y PKCE; Starter = solo Demo; Core+ para orgs reales	FAQ de Xero	No promete exactitud del modelo
Las tools V1 no confirman escrituras	FAQ de Xero	Tú debes imponer la confirmación en el cliente
list-invoices / list-credit-notes limitados a 10 filas por página; sin filtro de fechas en esas tools de listado	Issue #193 de GitHub (AuthenticIntelligence, 9 jun 2026; aún abierta el 19 oct 2026) al extraer ~500 facturas de un fabricante británico vía Claude Cowork	No consta arreglo en el hilo cuando lo revisamos
El MCP no hace nada con el chat cerrado; no hay disparador «venció una factura»	Use Carly, 17 jul 2026	Productos con horarios son otra arquitectura
Conector de solo lectura en las apps de Claude	Página del conector Anthropic / Xero, abril 2026	No sustituye las tools de escritura de Remote MCP

Límites y riesgos

• Organización equivocada. Una llamada de tool, una org. Sin nombre explícito, un despacho multi-org puede contabilizar en los libros incorrectos.
• Escrituras silenciosas. Como las tools V1 no piden confirmación, un «adelante, limpia eso» educado puede crear facturas o pagos.
• Secretos en prompts. Los secretos de Web app pegados en el chat se filtran. Prefiere Remote MCP con PKCE o variables de entorno.
• Coste de extracción masiva. La issue #193 describe paginación de diez en diez y filtros ausentes que multiplicaron llamadas para unos cientos de facturas.
• Geografía de nómina. El README open source limita las consultas de payroll a regiones NZ o UK.
• Los datos salen del portátil. Lo que ve Claude viaja al proveedor del modelo bajo sus condiciones. Con libros de clientes, eso es una cuestión de RGPD y de carta de encargo, no solo técnica.
• No es un robot de cierre. El MCP responde cuando preguntas. No sustituye la vigilancia de extractos, conciliación programada ni la firma humana de un IVA.

Errores frecuentes

1. Esperar que Custom Connection funcione con Remote MCP. El FAQ dice que no es elegible; usa el tipo de app PKCE que documenta Remote MCP.
2. Empezar en la organización real de un cliente. Mejor reinicia la Demo Company; existe para esto.
3. Conceder scopes de escritura el primer día. Lee facturas y PyG hasta que los números cuadren; luego amplía.
4. Meter secretos a pelo en mcp.json y subirlos a Git. Usa variables de entorno; rota si se filtraron.
5. Creer que el conector del marketplace de Claude es lo mismo que el MCP con escritura. Es de solo lectura y vive en el directorio de conectores de Claude.
6. Paginar cientos de facturas en el chat cuando un informe filtrado de Xero o una exportación dedicada saldría más barato — ver issue #193.
7. Usuarios de nvm que dejan command como npx a secas. Apunta al binario absoluto o el servidor no arranca.

Conclusiones

Si ya llevas la contabilidad en Xero y ya trabajas en Claude Code, las vías oficiales de MCP quitan el CSV de en medio para preguntas ad hoc y borradores supervisados. Prefiere Remote MCP con PKCE cuando el plan lo permita; conserva el paquete npm autoalojado para Custom Connection o montajes locales como la guía Web app de Evgeny desde Madrid; usa el conector del marketplace cuando solo necesites respuestas de lectura dentro de Claude. En todos los casos, que una persona confirme las escrituras — Xero no lo hará por ti en las tools V1 — y trata los trabajos de histórico masivo como algo que las tools de listado actuales hacen mal.

En este sitio: el despacho irlandés que construyó una herramienta offline de IVA a asientos Xero con Claude (sin MCP en vivo), el tutorial de consolidación de grupo que parte de exportaciones de Xero, el lanzamiento del MCP remoto de Holded, el servidor MCP comunitario de Odoo y el tutorial de activos fijos en Business Central que también deja el posteo a una persona.