BuchhaltungsButler MCP Server

MCP server wrapping the BuchhaltungsButler REST API for invoice/accounting automation.

Setup

1. Copy .env.example to .env and fill in your credentials:

   cp .env.example .env

2. Install dependencies:

   pip install -r requirements.txt

3. Run the server:

   # stdio mode (for MCP clients)
   python server.py --transport stdio
   
   # HTTP/SSE mode (port 8000)
   python server.py

API Reference

• Docs: https://app.buchhaltungsbutler.de/docs/api/v1/
• Swagger: https://app.buchhaltungsbutler.de/docs/api/v1.de.json
• API version: 1.9.1

Authentication

Uses HTTP Basic Auth (API Client + API Secret) plus api_key in the JSON body for customer selection.

Implemented Tools (14/48 API endpoints)

Receipts (Belege)

• bb_list_receipts — List receipts (inbound/outbound)
• bb_get_receipt — Get single receipt by id_by_customer
• bb_upload_receipt — Upload receipt file (PDF/image)

Invoices (Rechnungen)

• bb_create_invoice — Create an invoice

Accounts (Konten)

• bb_list_accounts — List all accounts

Postings (Buchungssätze)

• bb_list_postings — List postings
• bb_create_posting — Create posting (free/receipt/transaction)

Settings

• bb_list_debtors — List debtors (Debitoren)
• bb_list_creditors — List creditors (Kreditoren)
• bb_list_postingaccounts — List posting accounts

Comments

• bb_add_comment — Add comment to receipt or transaction

Missing API Endpoints (34)

High Priority

• receipts/add — Add receipt without file
• receipts/delete/id_by_customer — Delete receipt
• receipts/restore/id_by_customer — Restore deleted receipt
• receipts/addBatch — Batch add receipts
• receipts/assigned-transactions/get — Get transactions for receipt
• transactions/get — List transactions
• transactions/get/id_by_customer — Get single transaction
• transactions/assign/receipt — Assign receipt to transaction
• transactions/unassign/receipt — Unassign receipt from transaction
• transactions/assigned-receipts/get — Get receipts for transaction
• postings/unconfirm/free — Unconfirm free posting
• postings/unconfirm/receipt — Unconfirm receipt posting
• postings/assign/receipt-to-free-posting — Assign receipt to free posting

Medium Priority

• invoices/create/draft — Create invoice draft
• invoices/create/e-invoice — Create e-invoice
• accounts/add — Add a basic account
• settings/add/creditor — Create creditor
• settings/add/debtor — Create debtor
• settings/update/creditor — Update creditor
• settings/update/debtor — Update debtor
• settings/add/postingaccount — Add posting account
• settings/update/postingaccount — Update posting account
• postings/add-batch/free — Batch add free postings
• postings/add-batch/receipts — Batch add receipt postings
• postings/add-batch/transactions — Batch add transaction postings
• transactions/add — Add transaction
• transactions/addBatch — Batch add transactions
• transactions/assign-batch/receipt — Batch assign receipts

Low Priority

• cost-locations/add — Add cost location
• cost-locations/get — Get cost locations
• cost-locations/update — Update cost location
• cost-locations/delete — Delete cost location
• settings/add-batch/creditors — Batch create creditors
• settings/add-batch/debtors — Batch create debtors

Known Issues

• bb_get_receipt: Missing get_file parameter (to download file as base64)
• bb_list_receipts: Missing order, include_offers, deleted, invoicenumber, due_date params
• bb_list_postings: Missing date_last_action_from, date_last_action_to, postingaccount, cost_location, order params
• bb_create_posting (free): Missing postingtext, postingaccount_debit, postingaccount_credit, vat, cost_location_two params
• bb_create_posting (receipt/transaction): Missing multi-posting support (postingtexts, vats, amounts, creditor, debtor)
• No error handling for API rate limits (100 req/min)
• No retry logic for transient failures
• No logging
• No tests