Servidor MCP BuchPilot

Servidor MCP para contabilidad en la región DACH: gestiona contactos, facturas, comprobantes y presupuestos directamente desde Claude, Cursor o cualquier cliente compatible con MCP.

npm version License: MIT

¿Qué es esto?

BuchPilot MCP es un servidor del Model Context Protocol que conecta tu sistema contable (actualmente Lexoffice) con asistentes de IA. Puedes crear facturas, gestionar contactos y comprobar pagos vencidos mediante lenguaje natural, directamente en Claude Desktop, Cursor o cualquier otro cliente MCP.

Características

15 herramientas para una automatización contable completa
Contactos: crear, obtener, listar, actualizar
Facturas: crear, obtener, listar, actualizar, descargar PDF
Comprobantes: crear, obtener, listar (facturas recibidas, notas de crédito)
Presupuestos: crear, obtener
Facturas vencidas: con importes y días de retraso
Arquitectura backend: actualmente Lexoffice, ampliable para sevDesk, Billomat, etc.
Preparado para plugins: puede integrar herramientas MCP de factura electrónica (einvoice-mcp)
Sin base de datos, sin estado: un proxy de API puro

Instalación

Requisitos previos

Node.js >= 18
Una cuenta de Lexoffice con clave de API

npm (global)

npm install -g buchpilot-mcp

Desde el código fuente

git clone https://github.com/makririch/buchpilot-mcp.git
cd buchpilot-mcp
npm install
npm run build

Configuración

Crea un archivo de configuración .buchpilot.json en una de las siguientes ubicaciones:

Ruta desde la variable de entorno BUCHPILOT_CONFIG
~/.buchpilot.json (directorio home)
./.buchpilot.json (directorio actual)

Contenido de .buchpilot.json

{
  "backends": {
    "lexoffice": {
      "api_key": "DEIN_LEXOFFICE_API_KEY"
    }
  },
  "default_backend": "lexoffice"
}

Crear clave de API de Lexoffice

Ve a Lexoffice Public API
Haz clic en API-Key erstellen (Crear clave de API)
Copia la clave y pégala en .buchpilot.json

Aviso de seguridad: Nunca guardes la clave de API en Git. Añade .buchpilot.json a tu .gitignore.

Uso

Iniciar el servidor (standalone)

# Nach npm install -g:
buchpilot-mcp

# Oder von Source:
npm start

# Entwicklung mit Auto-Reload:
npm run dev

El servidor se ejecuta a través de stdio y espera mensajes MCP.

Uso en Claude Desktop

Consulta la Guía de configuración de Claude Desktop para obtener instrucciones detalladas.

Versión corta: añade esto a claude_desktop_config.json:

{
  "mcpServers": {
    "buchpilot": {
      "command": "npx",
      "args": ["-y", "buchpilot-mcp"],
      "env": {
        "BUCHPILOT_CONFIG": "/Users/DEIN_NAME/.buchpilot.json"
      }
    }
  }
}

Ejemplos (lenguaje natural en Claude)

Una vez configurado el servidor, puedes preguntar a Claude, por ejemplo:

"Crea un contacto para la empresa Beispiel GmbH con el correo electrónico info@beispiel.de"
"Muéstrame todas las facturas abiertas"
"Crea una factura para el contacto XYZ: 10 horas de consultoría a 150 EUR cada una"
"¿Qué facturas están vencidas?"
"Descarga el PDF de la factura ABC"
"Crea un presupuesto para 5 licencias a 49 EUR/mes"

Referencia de herramientas

Encontrarás una referencia completa de las 15 herramientas con parámetros, ejemplos de entrada y salida en docs/tool-reference.md.

Resumen rápido

Herramienta	Descripción
`create_contact`	Crear un nuevo contacto (persona o empresa)
`get_contact`	Obtener contacto por ID
`list_contacts`	Listar contactos con filtros
`update_contact`	Actualizar contacto
`create_invoice`	Crear nueva factura con posiciones
`get_invoice`	Obtener factura por ID
`list_invoices`	Listar facturas (filtrable por estado)
`get_invoice_pdf`	Descargar factura como PDF (Base64)
`update_invoice`	Actualizar factura en borrador
`create_voucher`	Crear nuevo comprobante
`get_voucher`	Obtener comprobante por ID
`list_vouchers`	Listar comprobantes
`create_quotation`	Crear nuevo presupuesto con posiciones
`get_quotation`	Obtener presupuesto por ID
`get_overdue_invoices`	Facturas vencidas con análisis

Integración de factura electrónica

BuchPilot MCP puede integrar opcionalmente el paquete E-Invoice MCP para generar XRechnung y ZUGFeRD directamente desde el sistema contable:

// In deinem eigenen MCP-Server:
import { registerEInvoiceTools } from "einvoice-mcp";
registerEInvoiceTools(server);
// Ergebnis: 15 + 4 = 19 Tools

FAQ / Solución de problemas

"No .buchpilot.json found"

El servidor no encuentra el archivo de configuración. Crea un .buchpilot.json en tu directorio home:

echo '{"backends":{"lexoffice":{"api_key":"DEIN_KEY"}},"default_backend":"lexoffice"}' > ~/.buchpilot.json

"401 Unauthorized" en Lexoffice

¿Es correcta la clave de API en .buchpilot.json?
¿Sigue activa la clave? Compruébalo en Lexoffice Public API
Las claves de API pueden caducar; si es necesario, crea una nueva.

"429 Too Many Requests"

Lexoffice permite un máximo de 2 solicitudes por segundo. Si realizas muchas operaciones seguidas, espera un poco entre solicitudes.

El servidor arranca, pero Claude no reconoce las herramientas

Comprueba si el archivo claude_desktop_config.json es correcto
Reinicia Claude Desktop después de realizar cambios en la configuración
Revisa los registros: ~/Library/Logs/Claude/mcp.log (macOS)

No se puede actualizar la factura

Solo se pueden actualizar las facturas en estado draft (borrador). Las facturas finalizadas son inmutables.

Backend "sevDesk" no disponible

Actualmente solo se admite Lexoffice como backend. La compatibilidad con sevDesk está planificada. Puedes usar los nodos de n8n (n8n-nodes-buchpilot) para sevDesk.

Licencia

MIT: de uso libre, incluso comercial.

Autor

MaKri — GitHub

buchpilot-mcp