ohneben's Buchhaltungsbutler MCP

Gestiona tu contabilidad de BuchhaltungsButler en lenguaje natural desde asistentes de IA como Claude, Cursor y cualquier otro cliente MCP.

GitHub

Documentación

ohneben's Buchhaltungsbutler MCP

Licencia y comprobaciones

Registro MCP

Identificadores de paquete

Este servidor tiene sus propios identificadores. Lo que se llame de otra forma no forma parte de esto:

Dónde	Identificador
Registro MCP	`io.github.ohneben/buchhaltungsbutler-mcp`
Contenedor (GHCR)	`ghcr.io/ohneben/buchhaltungsbutler-mcp`
npm	`@ohneben/buchhaltungsbutler-mcp` (aún no publicado)

El paquete npm buchhaltungsbutler-mcp sin ámbito es otro proyecto de otro autor (mrvnklm/buchhaltungsbutler-mcp) y no tiene nada que ver con este. Los directorios que enlazan desde esta página hacia allí enlazan al paquete equivocado.

Gestiona tu contabilidad de BuchhaltungsButler en lenguaje natural desde asistentes de IA como Claude, Cursor y cualquier otro cliente MCP.

Este servidor de Model-Context-Protocol proporciona la API de BuchhaltungsButler v1 — todos los 54 endpoints como 46 herramientas MCP, generados a partir de la especificación oficial OpenAPI (versión de especificación 1.9.1). Cada herramienta está categorizada por seguridad (solo lectura / escritura / destructiva), para que tu asistente sepa qué hace una acción antes de ejecutarla. Funciona a través de stdio (Claude Desktop y otros lanzadores locales) o Streamable HTTP (alojado en Docker).

Por qué este servidor

Algunos servidores MCP simplemente reenvían una API. Este está diseñado para entregarse sin riesgo a un modelo de lenguaje y operarse en el día a día:

Lo que obtienes	Por qué importa
Los 54 endpoints, generados automáticamente a partir de la especificación oficial	Cobertura completa de comprobantes, transacciones, asientos, facturas, evaluaciones y datos maestros. Nada seleccionado a mano, nada olvidado.
Cada herramienta está categorizada por seguridad 🟢 / 🟡 / 🔴	Un banner al inicio de cada descripción de herramienta le dice al modelo exactamente qué ocurre — leer, crear, modificar, revertir o eliminar — antes de actuar.
Anotaciones MCP legibles por máquina (`readOnlyHint`, `destructiveHint`)	Los hosts que evalúan anotaciones (Claude entre ellos) pueden permitir automáticamente accesos de lectura y exigir confirmación antes de acciones destructivas.
Dos transportes: stdio y Streamable HTTP	Úsalo localmente en Claude Desktop — u opera un servidor de ejecución continua al que cualquier número de clientes MCP acceda por HTTP.
Docker + docker-compose, health-check, reinicio automático	Despliegue cercano a producción desde el inicio: `docker compose up`, y se mantiene activo.
Autenticación por Bearer-Token en el endpoint HTTP	Obligatoria en cuanto el servidor se vincula más allá del loopback: sin `MCP_AUTH_TOKEN` se niega a iniciar, en lugar de exponer la API sin protección.
Limitación de tasa integrada	Se autorregula por debajo del límite de BuchhaltungsButler de 100 solicitudes/cliente/minuto, para que nunca lo superes.
Tus credenciales nunca llegan al modelo	Las credenciales residen en el entorno del servidor y se inyectan por solicitud — el asistente solo ve entradas de herramientas y respuestas de la API.

En comparación

Según el estado actual, este es el único servidor MCP dedicado para BuchhaltungsButler. Alternativamente podrías apuntar un wrapper genérico OpenAPI→MCP a la especificación — pero eso deja bastante de lado:

Capacidad	Este proyecto	Wrapper genérico OpenAPI→MCP*
Los 54 endpoints de BuchhaltungsButler cubiertos	✅	✅
Categoría de seguridad 🟢 / 🟡 / 🔴 + banner por herramienta	✅	❌
Anotaciones MCP `readOnlyHint` / `destructiveHint`	✅	➖
Resolución de `$ref` para payloads por lotes + descripciones limpiadas de HTML	✅	➖
Limitación de tasa integrada (se mantiene bajo los 100/cliente/min. de BB)	✅	❌
Transporte `stdio`	✅	✅
Transporte Streamable HTTP	✅	➖
Docker + docker-compose, health-check, reinicio automático	✅	❌
Autenticación Bearer-Token forzada en el endpoint	✅	❌
Credenciales inyectadas en el servidor, nunca enviadas al modelo	✅	➖
Licencia	MIT	variable

_{*Los wrappers genéricos OpenAPI→MCP convierten cualquier especificación Swagger/OpenAPI en herramientas MCP.
Alcanzan los mismos endpoints, pero tratan cada operación por igual — sin
categorías de seguridad, sin historial operativo, sin salvaguardas adaptadas a datos
contables reales. "➖" = según la herramienta, variable / no garantizado.}

Qué puedes hacer con esto

Una vez que el servidor está conectado, puedes pedirle a tu asistente, por ejemplo:

"Enumera todos los comprobantes de entrada del último mes que sigan abiertos."
"Crea un borrador de factura para ACME GmbH: 10 horas de consultoría a 120 €."
"Contabiliza esta transacción bancaria en la cuenta de costos 4400."
"Sube este comprobante PDF y asígnalo a la transacción correspondiente."
"Muéstrame mis acreedores y crea uno nuevo para nuestro proveedor de hosting."
"Genérame la BWA del último trimestre y muéstrame la hoja de cuenta para la cuenta 4400."

Las herramientas se generan automáticamente a partir de la API oficial y se agrupan en 🟢 solo lectura, 🟡 escritura y 🔴 destructivas — un host bien implementado puede tratar cada grupo de forma diferente.

Cómo funciona

Claude / Cursor / beliebiger MCP-Client  ──MCP──►  dieser Server  ──HTTPS──►  BuchhaltungsButler API (Cloud)

El servidor lee la especificación OpenAPI incluida y la convierte en herramientas MCP (incluida la resolución de payloads por lotes de $ref y la eliminación de HTML de las descripciones), etiqueta cada herramienta con su categoría de seguridad y adjunta tus credenciales de autenticación básica así como el api_key a cada solicitud saliente. Tus credenciales permanecen en el entorno del servidor — el modelo nunca las ve ni las toca.

Requisitos previos

Una cuenta de BuchhaltungsButler con acceso a la API — un API Client + API Secret (Ajustes → API) así como un api_key de cliente (ver Obtener credenciales de API).
Docker (Docker Desktop en macOS/Windows) para el inicio rápido a continuación — o Node.js ≥ 18, para iniciar desde el código fuente.

Inicio rápido (Docker)

1. Guarda las credenciales. Copia la configuración de ejemplo y complétala:

cp .env.example .env
# .env bearbeiten → BB_API_CLIENT, BB_API_SECRET, BB_API_KEY setzen
#                 → MCP_AUTH_TOKEN setzen. PFLICHT, sonst startet der Server
#                   nicht, denn .env.example bindet auf 0.0.0.0:
#                   openssl rand -hex 32

2. Inicia el servidor:

docker compose up -d --build

3. Comprueba que se está ejecutando:

curl -s http://localhost:3000/health     # → {"status":"ok","server":"buchhaltungsbutler-mcp"}

4. Conecta el cliente MCP. Los endpoints remotos se añaden en Claude como Custom Connector (Ajustes → Connectors) o localmente con mcp-remote como puente. Introduce lo siguiente bajo mcpServers en la configuración de tu cliente y reinicia la aplicación por completo después:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header", "Authorization: Bearer DEIN_MCP_AUTH_TOKEN"
      ]
    }
  }
}

(La línea de --header solo se omite si vinculas sin token en loopback. En el inicio rápido de Docker anterior, el token es obligatorio.)

¿Prefieres una imagen ya lista?

Cada push a main publica una imagen lista para usar en la GitHub Container Registry — así puedes omitir por completo la compilación local:

docker run -d --name buchhaltungsbutler-mcp -p 3000:3000 --env-file .env \
  ghcr.io/ohneben/buchhaltungsbutler-mcp:latest

Obtener credenciales de API

BuchhaltungsButler utiliza dos niveles de autenticación (ver la documentación oficial):

Autenticación básica HTTP — un API Client + API Secret, tus credenciales globales de API. Se encuentran o se crean en BuchhaltungsButler en Ajustes → API.
api_key — determina a qué cuenta de cliente se refiere una solicitud. Se encuentra en los ajustes de datos de la empresa del cliente correspondiente.

Introduce los tres valores en .env. El servidor los adjunta a cada solicitud; tu asistente nunca los ve. Una llamada de herramienta individual puede opcionalmente incluir su propio api_key para dirigirse a otra cuenta de cliente.

Configuración

Todo se define en .env (copiado de .env.example):

Variable	Obligatoria	Valor predeterminado	Descripción
`BB_API_CLIENT`	✅	—	API Client (usuario de autenticación básica)
`BB_API_SECRET`	✅	—	API Secret (contraseña de autenticación básica)
`BB_API_KEY`	✅	—	`api_key` de cliente estándar
`MCP_TRANSPORT`	—	`stdio`	`stdio` o `http` (la imagen Docker usa `http` por defecto)
`PORT`	—	`3000`	Puerto HTTP en el que escucha
`HOST`	—	`0.0.0.0`	Dirección de enlace HTTP
`MCP_HTTP_PATH`	—	`/mcp`	Ruta HTTP para MCP
`MCP_AUTH_TOKEN`	⚠️	(desactivado)	Exige `Authorization: Bearer <Token>` en `/mcp`. Obligatorio, si `HOST` no es una dirección de loopback — de lo contrario el servidor no inicia
`MCP_ALLOWED_HOSTS`	—	(automático)	Cabeceras `Host` permitidas, separadas por comas (protección contra DNS-rebinding). Necesario detrás de un proxy inverso
`MCP_ALLOW_INSECURE`	—	(desactivado)	Levanta la negativa de inicio sin token. Solo para endpoints demostrablemente inalcanzables
`MCP_SESSION_TTL`	—	`1800`	Segundos de inactividad antes de descartar una sesión
`MCP_MAX_SESSIONS`	—	`256`	Límite máximo de sesiones simultáneas
`BB_ALLOW_API_KEY_OVERRIDE`	—	(desactivado)	Permite que una llamada de herramienta sobrescriba el `api_key`
`BB_RATE_LIMIT`	—	`90`	Límite de solicitudes por minuto del lado del cliente
`BB_BASE_URL`	—	(de la especificación)	Sobrescribe la URL base de la API

Después de cambios en .env, recarga con docker compose up -d --force-recreate.

Nombres de herramientas

Cada herramienta se llama <ressource>_<verb>. Los verbos son fijos: list, get, create, update, delete, upload, assign, unassign, unconfirm, restore, cancel. Así la misma cosa se llama igual en todas partes, independientemente de cómo esté escrito la ruta BB correspondiente (la API mezcla add y create, y dos rutas por lotes están en camelCase).

La creación siempre se realiza a través de una herramienta que acepta una lista. receipts_create crea un comprobante o cien; un único registro es una lista con una entrada. Por eso hay 46 herramientas para 54 endpoints: ocho endpoints individuales se han fusionado en su contraparte por lotes.

Los nombres antiguos siguen siendo invocables

Los nombres hasta 1.1.1 siguen funcionando. Ya no aparecen en el catálogo, pero se resuelven al invocarlos, para que las llamadas fijadas de versiones anteriores no fallen. Una llamada a receipts_add con campos individuales sigue llegando a /receipts/add.

BB_READ_ONLY y BB_TOOL_ALLOWLIST se aplican antes: a través de un nombre antiguo no se puede alcanzar ninguna herramienta que la política excluya.

Antiguo (hasta 1.1.1)	Nuevo
`accounts_get`	`accounts_list`
`receipts_get`	`receipts_list`
`receipts_get_id_by_customer`	`receipts_get_by_id`
`receipts_add`, `receipts_addBatch`	`receipts_create`
`transactions_add`, `transactions_addBatch`	`transactions_create`
`settings_get_creditors`	`creditors_list`
`settings_add_creditor`, `settings_add_batch_creditors`	`creditors_create`
`settings_get_postingaccounts`	`postingaccounts_list`
`postings_add_free`, `postings_add_batch_free`	`postings_create_free`
`transactions_assign_receipt`, `transactions_assign_batch_receipt`	`transactions_assign_receipts`

La asignación completa está en src/naming.ts.

Categorías de seguridad de las herramientas

Cada descripción de herramienta comienza con uno de estos banners y lleva las anotaciones MCP correspondientes:

Banner	Anzahl	`readOnlyHint`	`destructiveHint`	Bedeutung
🟢 SOLO LECTURA	15	`true`	`false`	Solo recupera datos. Inofensivo.
🟡 ESCRITURA · crea datos	17	`false`	`false`	Genera registros (no idempotente; si se llama varias veces, se crean duplicados).
🟡 ESCRITURA · modifica datos	4	`false`	`false`	Modifica directamente datos maestros existentes.
🟡 ESCRITURA · vincula/desvincula	3	`false`	`false`	Asigna o desasigna un comprobante a una transacción. Reversible.
🟡 ESCRITURA · revierte estado	4	`false`	`false`	Marca asientos como no confirmados / restaura comprobantes. Reversible.
🔴 DESTRUCTIVO · elimina	3	`false`	`true`	Elimina o anula un registro. Solicitar confirmación antes.

Los hosts que respetan las anotaciones (incluido Claude) pueden solicitar confirmación para las herramientas destructiveHint y confiar automáticamente en las herramientas readOnlyHint.

Cada herramienta incluye además un outputSchema, es decir, la forma de la respuesta de éxito. Por eso, las llamadas exitosas no solo devuelven la respuesta como texto, sino también como structuredContent.

Con npm run list-tools (sin credenciales) se puede mostrar el catálogo completo en cualquier momento.

🟢 SOLO LECTURA (15)

Herramienta	Endpoint
`accounts_list`	`POST /accounts/get`
`cost_locations_list`	`POST /cost-locations/get`
`creditors_list`	`POST /settings/get/creditors`
`debtors_list`	`POST /settings/get/debtors`
`postingaccounts_list`	`POST /settings/get/postingaccounts`
`postings_list`	`POST /postings/get`
`receipts_get_by_id`	`POST /receipts/get/id_by_customer`
`receipts_list`	`POST /receipts/get`
`receipts_list_assigned_transactions`	`POST /receipts/assigned-transactions/get`
`reports_get_bwa`	`POST /reports/get/bwa`
`reports_get_sums`	`POST /reports/get/sums`
`reports_get_sums_ledger`	`POST /reports/get/sums/ledger`
`transactions_get_by_id`	`POST /transactions/get/id_by_customer`
`transactions_list`	`POST /transactions/get`
`transactions_list_assigned_receipts`	`POST /transactions/assigned-receipts/get`

🟡 ESCRITURA · crea datos (17)

Las herramientas con dos endpoints aceptan una lista. Si la llamada se hace con campos individuales, se envía al endpoint individual.

Herramienta	Endpoint	Endpoint individual
`accounts_create`	`POST /accounts/add`
`comments_create`	`POST /comments/add`
`cost_locations_create`	`POST /cost-locations/add`
`creditors_create`	`POST /settings/add-batch/creditors`	`POST /settings/add/creditor`
`debtors_create`	`POST /settings/add-batch/debtors`	`POST /settings/add/debtor`
`invoices_create`	`POST /invoices/create`
`invoices_create_draft`	`POST /invoices/create/draft`
`invoices_create_e_invoice`	`POST /invoices/create/e-invoice`
`postingaccounts_create`	`POST /settings/add/postingaccount`
`postings_create_for_receipt`	`POST /postings/add-batch/receipts`	`POST /postings/add/receipt`
`postings_create_for_transaction`	`POST /postings/add-batch/transactions`	`POST /postings/add/transaction`
`postings_create_free`	`POST /postings/add-batch/free`	`POST /postings/add/free`
`receipts_create`	`POST /receipts/addBatch`	`POST /receipts/add`
`receipts_upload`	`POST /receipts/upload`
`reports_create_bwa`	`POST /reports/create/bwa`
`reports_create_sums`	`POST /reports/create/sums`
`transactions_create`	`POST /transactions/addBatch`	`POST /transactions/add`

🟡 ESCRITURA · modifica (4) · vincula (3) · revierte (4)

Herramienta	Endpoint	Subcategoría
`cost_locations_update`	`POST /cost-locations/update`	modifica
`creditors_update`	`POST /settings/update/creditor`	modifica
`debtors_update`	`POST /settings/update/debtor`	modifica
`postingaccounts_update`	`POST /settings/update/postingaccount`	modifica
`postings_assign_receipt_to_free`	`POST /postings/assign/receipt-to-free-posting`	vincula
`transactions_assign_receipts`	`POST /transactions/assign-batch/receipt`	vincula
`transactions_unassign_receipt`	`POST /transactions/unassign/receipt`	vincula
`postings_unconfirm_free`	`POST /postings/unconfirm/free`	revierte
`postings_unconfirm_for_receipt`	`POST /postings/unconfirm/receipt`	revierte
`postings_unconfirm_for_transaction`	`POST /postings/unconfirm/transaction`	revierte
`receipts_restore`	`POST /receipts/restore/id_by_customer`	revierte

🔴 DESTRUCTIVO · elimina (3)

Herramienta	Endpoint	Nota
`receipts_delete`	`POST /receipts/delete/id_by_customer`	Recuperable mediante `receipts_restore`
`cost_locations_delete`	`POST /cost-locations/delete`	No recuperable
`postings_cancel`	`POST /postings/cancel`	Los asientos aún no confirmados se eliminan; los confirmados se compensan con un asiento de anulación

Lo que la API v1 no puede hacer

Estas limitaciones están deliberadamente también en las descripciones de las herramientas, para que el modelo no busque un endpoint que no existe:

Recurso	Falta
Acreedores, deudores, cuentas contables	sin eliminación
Cuentas (`accounts`)	sin modificación, sin eliminación
Comentarios	sin lectura, sin modificación, sin eliminación
Facturas	sin lectura, sin modificación, sin anulación
Transacciones	sin modificación, sin eliminación

Iniciar desde el código fuente (stdio, sin Docker)

¿Prefieres el modo stdio clásico para Claude Desktop? Entonces compila localmente:

npm install
npm run build

Luego, en claude_desktop_config.json, haz que Claude Desktop apunte al punto de entrada compilado:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/ABSOLUTER/PFAD/Buchhaltungsbutler MCP/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BB_API_CLIENT": "dein-api-client",
        "BB_API_SECRET": "dein-api-secret",
        "BB_API_KEY": "dein-kunden-api-key"
      }
    }
  }
}

O ejecuta el contenedor mediante stdio:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "BB_API_CLIENT", "-e", "BB_API_SECRET", "-e", "BB_API_KEY",
        "buchhaltungsbutler-mcp:latest"
      ],
      "env": {
        "BB_API_CLIENT": "dein-api-client",
        "BB_API_SECRET": "dein-api-secret",
        "BB_API_KEY": "dein-kunden-api-key"
      }
    }
  }
}

(Compila la imagen antes: docker build -t buchhaltungsbutler-mcp:latest .)

Mantener la spec actualizada

El spec.json incluido es la spec oficial de OpenAPI de BuchhaltungsButler v1 — la fuente autoritativa para las herramientas. Así la actualizas a un estado más reciente de la API:

curl -s https://app.buchhaltungsbutler.de/docs/api/v1.de.json -o spec.json
npm run build

Las nuevas rutas se adoptan automáticamente; regístralas en PATH_CATEGORY en src/categories.ts para que reciban la categoría de seguridad correcta (las rutas no asignadas caen de forma conservadora en la categoría create).

Nota sobre el número de versión: BuchhaltungsButler no mantiene de forma fiable el campo info.version en la spec — el contenido puede cambiar sin que el número aumente. Por lo tanto, no te bases en la versión para la comparación, sino compara la lista de rutas (paths) y los parámetros de los endpoints.

Desarrollo

npm install
npm run build      # TypeScript → dist/ kompilieren
npm test           # Vitest-Suite ausführen
npm run list-tools # kategorisierten Tool-Katalog ausgeben (ohne Zugangsdaten)

La CI compila y prueba cada push en Node 20 y 22; los pushes a main publican además una imagen Docker en la GitHub Container Registry.

Notas y convenciones

Fechas: YYYY-MM-DD. Montos: punto como separador decimal (p. ej., -12.30).
Cargas de archivos (receipts_upload): El archivo se envía como cadena Base64 en el campo file. receipts_create crea comprobantes sin archivo.
Paginación: La mayoría de las herramientas list aceptan limit y offset e informan el total en rows.
Crear siempre se hace mediante una herramienta que acepta un array; los esquemas de los elementos se resuelven desde las definiciones de la spec y se entregan al modelo. Un único registro es un array con una entrada.
Evaluaciones (BWA, suma y saldos) se generan asincrónicamente en segundo plano: primero llama a reports_create_*, luego a reports_get_* con el id_by_customer devuelto. Una nueva evaluación del mismo tipo reemplaza la anterior.
Límite de tasa: BuchhaltungsButler permite 100 solicitudes/cliente/minuto; el servidor se autorregula con BB_RATE_LIMIT (estándar 90) para mantenerse por debajo de ese límite.

Seguridad

Tus credenciales de API residen exclusivamente en .env, y este archivo está excluido de Git. Nunca hagas commit de secretos reales. Si algo se filtra, rota los datos en BuchhaltungsButler → Configuración → API.
El endpoint HTTP exige un token en cuanto se vincula más allá de loopback. Sin MCP_AUTH_TOKEN, el servidor se niega a iniciar y explica en el mensaje de error qué hacer. Envía el token como encabezado Authorization: Bearer <Token>, idealmente detrás de TLS.
También en localhost: sin token, el encabezado Host se limita a nombres de localhost, para que ninguna página web arbitraria pueda acceder al endpoint mediante DNS-rebinding. Detrás de un proxy inverso, configura MCP_ALLOWED_HOSTS para ello.
Detrás de un proxy inverso, fija el encabezado Host en el proxy al nombre interno del upstream y regístralo exactamente en MCP_ALLOWED_HOSTS. Así la verificación no depende del dominio público y sobrevive un cambio de dominio. (Consejo de @WinFuture23.)
Si configuras MCP_ALLOWED_HOSTS y tu plataforma tiene un health-check HTTP, su hostname debe estar también en la lista. Railway envía Host: healthcheck.railway.app, las sondas de Kubernetes consultan según la configuración a través de la IP del contenedor. Si falta el nombre, el health-check recibe un 403 y la plataforma considera el despliegue como roto.
/health está detrás de la verificación de host, pero antes de la verificación de token: un health-check de la plataforma no necesita token. Además, /health siempre acepta localhost, 127.0.0.1 y [::1], para que el HEALTHCHECK del Dockerfile incluido siga funcionando si configuras MCP_ALLOWED_HOSTS en tu dominio público. Si tu health-check consulta a través de la IP del contenedor o un nombre de servicio, debes incluir ese nombre en MCP_ALLOWED_HOSTS.
El api_key por llamada de herramienta está desactivado por defecto (BB_ALLOW_API_KEY_OVERRIDE=1 lo habilita), para que el modelo no pueda decidir por sí mismo sobre qué cliente se escribe.

La política completa y el canal para reportar vulnerabilidades están en SECURITY.md.

Créditos y licencia

Una integración comunitaria no oficial para BuchhaltungsButler; no está afiliada ni respaldada por BuchhaltungsButler. Basada en el Model Context Protocol. Publicada bajo la licencia MIT.