Xero MCP Server

Servidor MCP de Xero

Esta es una implementación de servidor del Protocolo de Contexto de Modelo (MCP) para Xero. Proporciona un puente entre el protocolo MCP y la API de Xero, permitiendo un acceso estandarizado a las funciones contables y empresariales de Xero.

Características

• Autenticación OAuth2 de Xero con conexiones personalizadas
• Gestión de contactos
• Gestión del plan de cuentas
• Creación y gestión de facturas
• Cumplimiento del protocolo MCP

Requisitos previos

• Node.js (v18 o superior)
• npm o pnpm
• Una cuenta de desarrollador de Xero con credenciales de API

Documentación y enlaces

• Documentación de la API pública de Xero
• Explorador de API de Xero
• Especificaciones OpenAPI de Xero
• Documentación del SDK de API pública Xero-Node
• Documentación para desarrolladores

Configuración

Crear una cuenta de Xero

Si aún no tienes una cuenta y organización de Xero, puedes crear una registrándote aquí usando la prueba gratuita.

Recomendamos empezar con una Empresa de Demostración porque incluye algunos datos de ejemplo precargados. Una vez que hayas iniciado sesión, cambia a ella usando el menú desplegable superior izquierdo y seleccionando "Empresa de Demostración". Puedes restablecer los datos de una Empresa de Demostración, o cambiar el país, en cualquier momento usando el menú desplegable superior izquierdo y navegando a Mi Xero.

NOTA: Para usar consultas específicas de nómina, la región debe ser NZ o UK.

Autenticación

Hay 2 modos de autenticación soportados en el servidor MCP de Xero:

1. Conexiones personalizadas

Esta es una mejor opción para pruebas y desarrollo, ya que te permite especificar el ID de cliente y los secretos para una organización específica. También es el enfoque recomendado si estás integrando esto en clientes MCP de terceros como Claude Desktop.

Configuración de tu cuenta de desarrollador de Xero

Configura una Conexión Personalizada siguiendo estas instrucciones: https://developer.xero.com/documentation/guides/oauth2/custom-connections/

Ámbitos requeridos

Las conexiones personalizadas requieren diferentes ámbitos dependiendo de cuándo se crearon. Todos los ámbitos de la lista correspondiente deben agregarse a tu conexión personalizada:

Conexión Personalizada Creada	Ámbitos Requeridos
Antes del 29 de abril de 2026	SCOPES_V1 (permisos agrupados)
Desde el 29 de abril de 2026	SCOPES_V2 (permisos granulares)

Nota: El servidor MCP prueba automáticamente primero los ámbitos V1 y recurre a V2 si es necesario.

Puedes anular esto configurando la variable de entorno XERO_SCOPES con una lista de ámbitos separados por espacios.

Integración del servidor MCP con Claude Desktop

Para agregar el servidor MCP a Claude, ve a Configuración > Desarrollador > Editar configuración y agrega lo siguiente a tu archivo claude_desktop_config.json:

{
  "mcpServers": {
    "xero": {
      "command": "npx",
      "args": ["-y", "@xeroapi/xero-mcp-server@latest"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here",
        "XERO_SCOPES": "accounting.invoices accounting.contacts accounting.settings"
      }
    }
  }
}

La variable XERO_SCOPES es opcional. Si se omite, se usarán los ámbitos predeterminados listados arriba.

NOTA: Si estás usando Node Version Manager en la sección "command": "npx", cámbiala para que sea la ruta completa al ejecutable, es decir: your_home_directory/.nvm/versions/node/v22.14.0/bin/npx en Mac / Linux o "your_home_directory\\.nvm\\versions\\node\\v22.14.0\\bin\\npx" en Windows

2. Token de Portador

Esta es una mejor opción si necesitas soportar múltiples cuentas de Xero en tiempo de ejecución y permitir que el cliente MCP ejecute un flujo de autenticación (como PKCE) según sea necesario. En este caso, usa la siguiente configuración:

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

NOTA: El XERO_CLIENT_BEARER_TOKEN tendrá prioridad sobre el XERO_CLIENT_ID si está definido.

Ámbitos requeridos para el Token de Portador

Al obtener un token de portador, debes solicitar los ámbitos apropiados. Los ámbitos que debes solicitar son:

Nota: Algunos ámbitos están siendo obsoletos en favor de ámbitos más granulares. Consulta la documentación de Ámbitos de Xero OAuth 2.0 para detalles sobre los plazos de obsolescencia.

accounting.transactions (Deprecated)
accounting.transactions.read (Deprecated)
accounting.invoices
accounting.invoices.read
accounting.payments
accounting.payments.read
accounting.banktransactions
accounting.banktransactions.read
accounting.manualjournals
accounting.manualjournals.read
accounting.reports.read (Deprecated)
accounting.reports.aged.read
accounting.reports.balancesheet.read
accounting.reports.profitandloss.read
accounting.reports.trialbalance.read
accounting.contacts 
accounting.settings 
payroll.settings 
payroll.employees 
payroll.timesheets

Comandos MCP disponibles

• list-accounts: Recuperar una lista de cuentas
• list-contacts: Recuperar una lista de contactos de Xero
• list-credit-notes: Recuperar una lista de notas de crédito
• list-invoices: Recuperar una lista de facturas
• list-items: Recuperar una lista de artículos
• list-manual-journals: Recuperar una lista de diarios manuales
• list-organisation-details: Recuperar detalles sobre una organización
• list-profit-and-loss: Recuperar un informe de pérdidas y ganancias
• list-quotes: Recuperar una lista de presupuestos
• list-tax-rates: Recuperar una lista de tasas impositivas
• list-payments: Recuperar una lista de pagos
• list-trial-balance: Recuperar un informe de balance de comprobación
• list-bank-transactions: Recuperar una lista de transacciones de cuentas bancarias
• list-payroll-employees: Recuperar una lista de Empleados de Nómina
• list-report-balance-sheet: Recuperar un informe de balance general
• list-payroll-employee-leave: Recuperar los registros de licencias de un Empleado de Nómina
• list-payroll-employee-leave-balances: Recuperar los saldos de licencias de un Empleado de Nómina
• list-payroll-employee-leave-types: Recuperar una lista de tipos de licencia de Nómina
• list-payroll-leave-periods: Recuperar una lista de los períodos de licencia de un Empleado de Nómina
• list-payroll-leave-types: Recuperar una lista de todos los tipos de licencia disponibles en Xero Nómina
• list-timesheets: Recuperar una lista de Hojas de Tiempo de Nómina
• list-aged-receivables-by-contact: Recupera cuentas por cobrar vencidas para un contacto
• list-aged-payables-by-contact: Recupera cuentas por pagar vencidas para un contacto
• list-contact-groups: Recuperar una lista de grupos de contactos
• list-tracking-categories: Recuperar una lista de categorías de seguimiento
• create-bank-transaction: Crear una nueva transacción bancaria
• create-contact: Crear un nuevo contacto
• create-credit-note: Crear una nueva nota de crédito
• create-invoice: Crear una nueva factura
• create-item: Crear un nuevo artículo
• create-manual-journal: Crear un nuevo diario manual
• create-payment: Crear un nuevo pago
• create-quote: Crear un nuevo presupuesto
• create-payroll-timesheet: Crear una nueva Hoja de Tiempo de Nómina
• create-tracking-category: Crear una nueva categoría de seguimiento
• create-tracking-option: Crear una nueva opción de seguimiento
• update-bank-transaction: Actualizar una transacción bancaria existente
• update-contact: Actualizar un contacto existente
• update-invoice: Actualizar una factura borrador existente
• update-item: Actualizar un artículo existente
• update-manual-journal: Actualizar un diario manual existente
• update-quote: Actualizar un presupuesto borrador existente
• update-credit-note: Actualizar una nota de crédito borrador existente
• update-tracking-category: Actualizar una categoría de seguimiento existente
• update-tracking-options: Actualizar opciones de seguimiento
• update-payroll-timesheet-line: Actualizar una línea en una Hoja de Tiempo de Nómina existente
• approve-payroll-timesheet: Aprobar una Hoja de Tiempo de Nómina
• revert-payroll-timesheet: Revertir una Hoja de Tiempo de Nómina aprobada
• add-payroll-timesheet-line: Agregar una nueva línea en una Hoja de Tiempo de Nómina existente
• delete-payroll-timesheet: Eliminar una Hoja de Tiempo de Nómina existente
• get-payroll-timesheet: Recuperar una Hoja de Tiempo de Nómina existente

Para documentación detallada de la API, consulta la Especificación del Protocolo MCP.

Para desarrolladores

Instalación

# Using npm
npm install

# Using pnpm
pnpm install

Ejecutar una compilación

# Using npm
npm run build

# Using pnpm
pnpm build

Integración con Claude Desktop

Para vincular tu servidor MCP de Xero en desarrollo con Claude Desktop, ve a Configuración > Desarrollador > Editar configuración y agrega lo siguiente a tu archivo claude_desktop_config.json:

NOTA: Para Windows, asegúrate de que la ruta args escape el \ entre carpetas, es decir, "C:\\projects\xero-mcp-server\\dist\\index.js"

{
  "mcpServers": {
    "xero": {
      "command": "node",
      "args": ["insert-your-file-path-here/xero-mcp-server/dist/index.js"],
      "env": {
        "XERO_CLIENT_ID": "your_client_id_here",
        "XERO_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}

Licencia

MIT

Seguridad

Por favor, no subas tu archivo .env ni ninguna credencial sensible al control de versiones (está incluido en .gitignore como una configuración predeterminada segura).