mcp-buchhaltungsbutler
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-buchhaltungsbutler
Deutsch | English
An MCP (Model Context Protocol) server that exposes the BuchhaltungsButler API (v1) — a German bookkeeping/accounting SaaS — as a set of curated, token-efficient tools for LLM agents.
Unofficial, community project. Not affiliated with or endorsed by BuchhaltungsButler.
Built for agents, not just wrapped from the API
58 tools covering 58 of the 61 endpoints (the three
/settings/delete/*endpoints added to the live API documentation in November 2026 have no tool yet) — batch, list, and singular variants of the same action are merged into one tool, so your context window isn't full of near-duplicate tool definitions.Lean by default — list tools return trimmed, LLM-friendly fields out of the box; pass
full: truewhenever you need the complete record.No array-juggling — invoice line items, posting splits, and other API quirks are exposed as clean, ordinary objects. No more keeping five parallel arrays in sync by hand.
Always in sync with the spec — endpoint definitions are generated straight from BuchhaltungsButler's official API spec, not hand-maintained.
Related MCP server: Cuéntica MCP
Setup
npm installCopy
.env.exampleto.envand fill inBB_API_CLIENT,BB_API_SECRET,BB_API_KEY(BuchhaltungsButler → Settings → API).npm test— runs against mocked HTTP responses, no live credentials needed.npm run build && npm start— ornpm run devfor a quick local run without building first.
npm run generate regenerates src/bb-client/generated/endpoints.ts from the vendored spec (spec/buchhaltungsbutler-v1.json); the output is already committed, so this is only needed after updating the spec file itself.
Using with an MCP client
.env only covers local npm run dev/npm start runs. A real MCP client (e.g. Claude Desktop) launches the server itself and won't read .env — pass credentials via the client's own env config instead. Example claude_desktop_config.json entry:
{
"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"
}
}
}
}Run npm run build first so dist/index.js exists.
Bewirtungsbeleg (business entertainment receipts)
generate_entertainment_receipt fills the gap between a restaurant bill and a legally complete
Bewirtungsbeleg (§ 4 Abs. 5 Satz 1 Nr. 2 EStG). generate_and_upload_entertainment_receipt does the
same and uploads the result via the same endpoint upload_receipt calls, so the full base64 PDF
doesn't have to round-trip through the model twice. See
docs/bewirtungsbeleg-faq.md for the legal background (German only, since
it documents German tax law).
Appending the original from BuchhaltungsButler (source_receipt_id_by_customer)
If the bill already exists in BuchhaltungsButler, call generate_and_upload_entertainment_receipt with
source_receipt_id_by_customer. The connector loads the original server-side (memory only), appends the
Bewirtungsangaben page as the last page and uploads one new receipt (original + page). No base64 passes
through the model. Use bill_file only for files that are not in BuchhaltungsButler.
Without a restaurant invoice, set original_invoice_status (missing_requested | lost) together with gross_amount,
payment_evidence, entertainment_type and, for business entertainment, missing_invoice_treatment (always ask the user, no default).
The generated page then is the receipt itself (no input VAT, one upload), and the response carries a booking_hint.
host_confirmed on the posting tools is deprecated (use bewirtungsangaben_signed and original_invoice_status);
combining it with bewirtungsangaben_signed or original_invoice_status is rejected. Input-VAT codes are refused on every account when the invoice is missing (codes without input VAT such as 19_both_1_no_pre and reverse-charge cases are not affected).
Sources and open points: docs/bewirtungsbeleg-faq.md.
Parameter | Meaning |
| id_by_customer of the original. Mutually exclusive with |
| SHA-256 of the original in the page footer. |
| Reuse the original's date, invoice number, amount, counterparty, account and type ( |
Flow: validate → load original → check type (PDF/JPEG/PNG, max 15 MB) → amount check (parts sum = original's
amount, tolerance 0.01 EUR) → merge → dry check (page count, text, embedded files) → one upload → duplicate
check. Any failure before the upload uploads nothing; a failed upload is never retried automatically. The original
is never modified or deleted - after the user confirms, remove it with set_receipt_deleted (restorable), then
book on the new receipt.
Returns: status, new_receipt_id_by_customer, original_receipt_id_by_customer, original_deleted (always
false), pages_before/pages_after, original_sha256, duplicates_found, checks, amounts, warnings,
next_step_hint. new_receipt_id_by_customer comes from the upload response (fallback: resolved via the internal filename from the receipt list; otherwise null with a warning). duplicates_found lists only other receipts with the same date, counterparty and amount (invoice number alone does not count) or linked to the original, each with matches and linked_to_original so old Fall-B pages are recognisable; the original and the new receipt never appear. Fall A (bill_file) and Fall B (link_to_receipt_id_by_customer) behave as before.
Mixed receipts (private and business items on one receipt)
For a receipt paid privately that also contains business items (Auslage):
Upload the scan to BuchhaltungsButler as usual (black-and-white, one page, no OCR text layer).
prepare_mixed_receiptreturns the receipt with line numbers and the questions to clarify first.Clarify business lines, Pfand/Rabatt, receipt number, who paid, occasion, VAT lines.
generate_mixed_receiptreturns the rendered A4 Auslagenbeleg (redacted receipt, net/tax per rate) as an image; nothing is uploaded.After approval
generate_and_upload_mixed_receiptwithconfirm: trueuploads it and comments on the original. Once the new receipt is confirmed in BuchhaltungsButler (active, same receipt number, amount = reimbursement), the tool soft-deletes the original (archived, restorable). If it cannot confirm the new receipt or the deletion fails, the original stays andnext_stepssays what to do. The tool never deletes without that confirmation, and the preview tools never delete.Whether the upload assigns the receipt to the paying person's Auslagenkonto depends on the house rule
debitoren_kreditoren(set_policy, mirrors the BuchhaltungsButler setting 'Debitoren und Kreditoren aktivieren'). Withausthe account is passed so BuchhaltungsButler can create the payment (account 'Beleg erzeugt Zahlung'); it is detected by name (the person's name plus "Gesellschafter" or "Auslage"), shown in the preview (auslagenkonto), and can be given (auslagenkonto) or switched off (without_auslagenkonto). Withaktivor not set the account is not passed (a receipt on such an account cannot be booked on a Kreditor); the payment is assigned later.After the delete step the result contains
booking_proposal, following the house ruledebitoren_kreditoren.aktiv: the proposal books the receipt on the merchant's Kreditor (add_receipt_postings) and the payment only settles it (add_transaction_postingsagainst the Kreditor, vat0_none); the Kreditor is derived from earlier bookings of the same merchant (never by name) or given ascreditor.aus: no receipt booking, the payment is booked; with only business accounts there may be no payment at all (the person paid privately), the proposal says so plainly and names the ways forward. Not set:needs_decision, nothing proposed. It is a proposal only, the connector books, assigns and creates nothing. Booking account suggestion 4653 (SKR03); the Steuerberater decides.
Details: docs/gemischte-belege-faq.md, legal background: docs/rechtsgrundlagen-gemischte-belege.md.
Remote deployment (Docker)
For clients that can't launch a local process (e.g. Claude on mobile), the server also runs as a Streamable HTTP service instead of stdio, container-ready.
Pull the published image:
ghcr.io/si0nde/mcp-buchhaltungsbutler:latest(built automatically frommainby.github/workflows/docker-publish.yml), or build locally withdocker build -t mcp-buchhaltungsbutler ..Run it with the usual
BB_API_CLIENT/BB_API_SECRET/BB_API_KEY, plus:MCP_AUTH_TOKEN(required) — a long random secret, at least 32 characters (e.g.openssl rand -base64 48); the server refuses to start with a shorter one. Every request must sendAuthorization: Bearer <token>. The token grants full read and write access to the bookkeeping.MCP_ALLOWED_HOSTS(recommended) — comma-separated hostnames this server is reachable as (e.g. your reverse proxy's domain), for DNS-rebinding protection.MCP_TRUST_PROXY(recommended behind a reverse proxy) — number of proxies in front of the server, usually1. The server blocks an address for up to a minute after 10 failed attempts (429withRetry-After); without this setting it only sees the proxy's address, so the block hits all clients together. Do not set it when the server is reachable without a proxy: anyone could then forge their address viaX-Forwarded-For.BHB_READ_ONLY(optional) —1ortrueoffers only the reading tools; booking, creating, uploading and deleting tools are not registered at all. Also applies to the local stdio start. Useful for a second, reporting-only access.PORT(optional, default3000).BHB_POLICY_FILE(optional) — whereset_policystores the house rules (default~/.mcp-buchhaltungsbutler/policy.json). In a container, mount a volume writable by thenodeuser (uid 1000), e.g.-v bhb-policy:/data -e BHB_POLICY_FILE=/data/policy.json; otherwise the rule is gone after a restart.BHB_TRAVEL_RATES_ONLINE(optional) —0orfalsedisables the online lookup of a missing BMF foreign per-diem table (travel expense reports are then calculated provisionally with the latest built-in table). Default: enabled (https tolsth./ksth.bundesfinanzministerium.deonly).
docker run -d --name mcp-buchhaltungsbutler \ -e BB_API_CLIENT=... -e BB_API_SECRET=... -e BB_API_KEY=... \ -e MCP_AUTH_TOKEN=... -e MCP_ALLOWED_HOSTS=mcp.your-domain.example -e MCP_TRUST_PROXY=1 \ -p 127.0.0.1:3000:3000 \ ghcr.io/si0nde/mcp-buchhaltungsbutler:latestPut a reverse proxy (Caddy, nginx, Traefik, ...) in front for TLS — this container only speaks plain HTTP.
GET /healthreturns200 {"status":"ok"}with no auth, for health checks; the MCP endpoint isPOST /mcpand requires the bearer token.Add it to Claude as a remote/custom connector using
https://mcp.your-domain.example/mcpand anAuthorization: Bearer <token>header — this is what makes it reachable from Claude on iOS/iPadOS, not just Desktop.
Security of a remote deployment. The endpoint depends on a single token, so:
Generate the token randomly, keep it nowhere in plain text except the client configuration, and replace it as soon as a device holding that configuration is lost or retired.
If you can, do not expose the endpoint to the whole internet: restrict it to known addresses or a VPN in the reverse proxy. TLS and HSTS belong to the reverse proxy.
Do not publish the container's port 3000 to the outside, only to the proxy (
-p 127.0.0.1:3000:3000or an internal Docker network).Text from the bookkeeping (payment references, receipt text, contact names) is written by third parties and reaches the model. Writing tools therefore require a confirmation; for reporting only, start with
BHB_READ_ONLY=1.
Reisekostenabrechnung (travel expense reports)
generate_travel_expense_report turns trip data (times, stops, meals, journeys, receipts) into a travel expense report PDF
plus a booking hint; the calculation (domestic and foreign per-diem rates from the 2026 BMF table, meal reductions,
three-month rule) runs deterministically in the connector. generate_and_upload_travel_expense_report also uploads the PDF
(never retried automatically, check list_receipts first). For employees, including shareholder managing directors with
an employment contract (employee), and for self-employed persons, sole proprietors and shareholder managing directors
without an employment contract (self_employed); nothing is booked automatically. The foreign rates table is built in
for 2026; for other years with foreign days the connector fetches the BMF table from the LStH page
(lsth.bundesfinanzministerium.de, validated; opt-out BHB_TRAVEL_RATES_ONLINE=0), otherwise it calculates with the
latest built-in table and marks the result as provisional (rates_provisional, VORLÄUFIG in the PDF). The interpretation
points should be reviewed by a tax advisor before production use. FAQ: docs/reisekosten-faq.md (German only, it documents German
tax law), legal basis: docs/rechtsgrundlagen-reisekosten.md.
Tools
Category | Tools |
Accounts |
|
Comments |
|
Cost Locations |
|
Contacts (Debtors/Creditors) |
|
Posting Accounts |
|
Receipts |
|
Mixed receipts |
|
Transactions |
|
Postings |
|
Invoices |
|
Month-end |
|
USt-VA |
|
Booking guide |
|
Reports |
|
House rules |
|
Version |
|
Bewirtungsbeleg |
|
Reisekostenabrechnung |
|
Correcting wrong postings (cancel_posting)
/postings/cancel deletes postings that are not fixed and cancels fixed ones with a reversal posting.
cancel_posting wraps it per posting with guard rails — see docs/buchungen-korrigieren-faq.md:
Preview first (
confirm: false, default): lists the affected postings (accounts, amount,fixed, receipt/transaction). Nothing is changed.Execute (
confirm: true): not fixed postings are deleted. Fixed postings are only reversed when their ids are passed inreverse_posting_ids(taken from the preview, approved by the user). Afterwards the postings are read again;gelöscht: true/falseand the new reversal postings (neu_angelegt) are reported.type=transaction/receiptremoves all postings of that transaction/receipt, onlytype=freea single posting.Recommended booking order: check receipt → book receipt → assign payment → book payment.
Not for periods already covered by a VAT pre-return or annual accounts without the Steuerberater.
BuchhaltungsButler logic
The server sends BHB's bookkeeping rules (booking order, Ist/Soll, Leistungsdatum, tax codes, opening balances) as MCP
instructions and in the tool descriptions, and get_booking_guide returns the documented rule, accounts and example for a special case on demand; see docs/bhb-systematik.md.
Architecture
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)
http-server.ts # MCP server bootstrap (Streamable HTTP, bearer auth) — for remote/Docker deployment
scripts/generate-client.ts # parses spec/buchhaltungsbutler-v1.json into src/bb-client/generated/Single-tenant, no multi-tenant support, no OAuth. Credentials never reach the model; they're injected into requests by the client layer from env vars. Runs locally over stdio (Claude Desktop) or as a Streamable HTTP service behind your own reverse proxy and bearer token (see "Remote deployment" above) for clients that need a network-reachable server.
Status
All 58 BuchhaltungsButler endpoints are covered by 40 of these tools (get_booking_guide and get_ustva_position make no API call, check_month_end and calculate_account_balance only combine read calls); generate_entertainment_receipt is a client-side PDF generator that makes no BuchhaltungsButler API calls of its own, while generate_and_upload_entertainment_receipt reuses the same receiptsUpload endpoint upload_receipt already covers rather than adding a 59th one (see docs/bewirtungsbeleg-faq.md). Verified against a live account (both a read call and a create+delete round trip). The endpoints added in the October 2026 spec update (/postings/cancel, reports, transactions/delete, accounts/update|delete, invoice_correction, OSS fields) are covered by unit tests only and not yet verified live.
Development
git clone https://github.com/si0nDE/mcp-buchhaltungsbutler.git && cd mcp-buchhaltungsbutler
npm install
npm test # vitest run
npm run build # tsc, strict modeLicense
MIT + Commons Clause — free to use (including commercially, e.g. for your own bookkeeping), modify, and contribute to. The one thing it doesn't permit is reselling this software or offering it as a paid hosted/managed service. If you find it useful, consider supporting development instead of building a rival funding page around it.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for Codat — companies, connections, invoices, bills and financial statements.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for Quaderno — tax-rate calculation, invoices, contacts, products, receipts & expenses.
Bokio MCP server for ChatGPT, Claude and any AI agent: create invoice, send invoice, upload receipt, create journal entry and list unpaid invoices in your own Bokio account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Bokio yourself; Cotlet does not store your password and you need no Bokio API key. About the official Bokio API: Yes, Bokio has a public REST API for invoices, customers, journal entries, uploads and supplier invoices (checked 14 Oct 2026), but it depends on your price plan and on the kind of integration: a private integration token works for one company only, and a tool that serves several companies must be registered as a public integration with OAuth 2.0. Bokio publishes no MCP server of its own. Setup and FAQ: https://cotlet.dev/integrations/bokio-api-mcp-server
Related MCP Servers
- FlicenseBqualityDmaintenanceMCP server for DACH accounting automation. Connect AI assistants to sevDesk and Lexoffice — create invoices, manage contacts, handle bookings and vouchers for German-speaking businesses.1555 npm-
- AlicenseBqualityDmaintenanceMCP server to interact with the Cuéntica accounting API, allowing users to manage invoices, expenses, income, clients, providers, and bank accounts via natural language.5931 PyPI2MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for the FreeAgent accounting API, enabling LLMs to securely access and manage accounting data including contacts, invoices, bills, bank transactions, and more.5 npm1MIT
- AlicenseBqualityDmaintenanceAn MCP server for Danish accounting via Billy.dk API, enabling natural-language control over invoices, bank lines, reports, and more, with a write-guard for safety.651MIT