mcp-buchhaltungsbutler

Alemán | Inglés

Un servidor MCP (Model Context Protocol) que expone la API de BuchhaltungsButler (v1) — un SaaS alemán de contabilidad — como un conjunto de herramientas seleccionadas y eficientes en tokens para agentes LLM.

Proyecto no oficial, de la comunidad. No afiliado ni respaldado por BuchhaltungsButler.

Hecho para agentes, no solo una envoltura de la API

• 30 herramientas que cubren los 48 endpoints — las variantes por lotes, lista y singular de la misma acción se fusionan en una sola herramienta, para que tu ventana de contexto no se llene de definiciones de herramientas casi duplicadas.

• Ligero por defecto — las herramientas de lista devuelven campos recortados y amigables para LLM de forma predeterminada; pasa full: true cuando necesites el registro completo.

• Sin malabares con arrays — los elementos de línea de factura, los desgloses de asientos y otras peculiaridades de la API se exponen como objetos limpios y ordinarios. No más mantener cinco arrays paralelos sincronizados a mano.

• Siempre sincronizado con la especificación — las definiciones de endpoints se generan directamente desde la especificación oficial de la API de BuchhaltungsButler, no se mantienen a mano.

Related MCP server: Cuéntica MCP

Configuración

1. npm install

2. Copia .env.example a .env y completa BB_API_CLIENT, BB_API_SECRET, BB_API_KEY (BuchhaltungsButler → Configuración → API).

3. npm test — se ejecuta contra respuestas HTTP simuladas, no se necesitan credenciales reales.

4. npm run build && npm start — o npm run dev para una ejecución local rápida sin compilar primero.

npm run generate regenera src/bb-client/generated/endpoints.ts a partir de la especificación incluida (spec/buchhaltungsbutler-v1.json); la salida ya está confirmada, por lo que solo se necesita después de actualizar el propio archivo de especificación.

Uso con un cliente MCP

.env solo cubre ejecuciones locales de npm run dev/npm start. Un cliente MCP real (por ejemplo, Claude Desktop) inicia el servidor por sí mismo y no leerá .env — pasa las credenciales a través de la configuración env del propio cliente. Ejemplo de entrada en claude_desktop_config.json:

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-buchhaltungsbutler/dist/index.js"],
      "env": {
        "BB_API_CLIENT": "your-api-client",
        "BB_API_SECRET": "your-api-secret",
        "BB_API_KEY": "your-customer-api-key"
      }
    }
  }
}

Ejecuta npm run build primero para que exista dist/index.js.

Herramientas

Arquitectura

src/
  config.ts              # env var loading, fail-fast validation
  bb-client/
    generated/            # spec-derived endpoint metadata (regenerate with npm run generate)
    client.ts              # generic HTTP client: auth, api_key injection, error mapping
  formatting/trim.ts       # trims list responses to LLM-friendly fields
  tools/                   # one file per category, curated MCP tools on top of the client
  server.ts, index.ts      # MCP server bootstrap (stdio)
scripts/generate-client.ts # parses spec/buchhaltungsbutler-v1.json into src/bb-client/generated/

Solo transporte stdio local de un solo inquilino — sin alojamiento remoto, sin soporte multiinquilino, sin OAuth. Las credenciales nunca llegan al modelo; se inyectan en las solicitudes por la capa de cliente desde variables de entorno.

Estado

Los 48 endpoints de BuchhaltungsButler están cubiertos por las 30 herramientas anteriores, probadas contra respuestas HTTP simuladas. Aún no verificado contra una cuenta real — si encuentras un error inesperado, especialmente en los cuatro endpoints con sufijo *_id_by_customer (get_receipt, set_receipt_deleted, get_transaction) o en add_receipt_postings/add_transaction_postings con un lote de centros de coste de presencia mixta, por favor abre un issue.

Desarrollo

git clone https://github.com/si0nDE/mcp-buchhaltungsbutler.git && cd mcp-buchhaltungsbutler
npm install
npm test           # vitest run
npm run build       # tsc, strict mode