sevdesk-mcp

English · Deutsch

The complete MCP server for sevDesk: every API endpoint, guarded writes, and a built-in bookkeeping audit layer.

Connect Claude (or any MCP client) to your sevDesk account: list and create vouchers and invoices, reconcile bank transactions, reach all 151 API operations — and run audits that know what a wrong booking looks like: a foreign supplier booked as domestic 0 % instead of Reverse Charge §13b, a tax rule the booking account doesn't allow, a payment with no receipt behind it.

Status: v0.4.0. Live-validated against a real sevDesk account (bookkeeping system 2.0) — where the audit found exactly the class of mis-booking it was built for. See CHANGELOG.md.

Quick start

You need: Node.js ≥ 22, a sevDesk account, and an MCP client (Claude Code, Claude Desktop, or any other).

1. Get your API token

In sevDesk: Settings → Users → your user → API. The token is a 32-character hex string.

⚠️ A sevDesk API token has no scopes — it can do everything your login can. Treat it like your password, and start in read-only mode.

2. Connect your MCP client

Claude Code — one command, then put your real token into the config it writes (~/.claude.json):

claude mcp add --scope user sevdesk \
  --env SEVDESK_API_TOKEN=REPLACE_ME \
  --env SEVDESK_READ_ONLY=true \
  -- npx -y sevdesk-mcp

Claude Desktop — add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "sevdesk": {
      "command": "npx",
      "args": ["-y", "sevdesk-mcp"],
      "env": {
        "SEVDESK_API_TOKEN": "your-token",
        "SEVDESK_READ_ONLY": "true"
      }
    }
  }
}

Any other MCP client works the same way: stdio transport, npx -y sevdesk-mcp (or node dist/index.js from a clone), config via environment variables. To run from source instead: git clone https://github.com/joosthel/sevdesk-mcp && cd sevdesk-mcp && npm install && npm run build.

3. First run

Restart your client and ask it to run sevdesk_ping. You should see ok: true, your bookkeeping system version (2.0 = taxRule, 1.0 = legacy taxType) and the mode (READ-ONLY). Then start asking:

• "Run a VAT audit for this year and explain every high-severity finding."
• "Are my US software subscriptions booked as reverse charge? What's my §13b base this quarter?"
• "Which bank payments have no receipt yet?"
• "Draft an invoice for contact 1009: 3 days of consulting at 800 €." (needs write mode)
• "Which booking accounts allow taxRule 12?"
• "Call the sevDesk API: get the last 10 orders." — the generic catalogue covers everything the curated tools don't.

What a finding looks like:

{
  "severity": "high",
  "code": "zero_rate_booked_as_domestic",
  "voucher": "2026-06-24 · Acme Cloud, Inc. · 88.03 EUR · #INV-2043",
  "detail": "Booked as \"Vorsteuerabziehbare Aufwendungen\" (taxRule 9) but every position carries 0 % VAT, and the supplier's contact is registered in \"us\".",
  "suggestion": "If this is a service from a supplier established abroad, it is Reverse Charge: taxRule 12 (§13b Abs. 2, with input-tax deduction) …"
}

4. Enabling writes (optional, later)

Once you trust the setup, set SEVDESK_READ_ONLY to "false" and restart the client. Every write tool accepts dryRun (and honors the global SEVDESK_DRY_RUN) — it shows exactly what would be sent without sending it. See Write safety.

Tools

23 tools cover all 151 API operations.

Audit

Everyday

sevdesk_ping · sevdesk_list_vouchers · sevdesk_get_voucher · sevdesk_list_invoices · sevdesk_list_contacts · sevdesk_list_transactions · sevdesk_receipt_guidance · sevdesk_upload_voucher_file · sevdesk_create_voucher · sevdesk_set_tax_rule · sevdesk_create_invoice · sevdesk_get_invoice_pdf · sevdesk_mark_invoice_sent

Highlights: sevdesk_receipt_guidance answers "which booking account / tax rule / rate combinations does sevDesk actually accept" from sevDesk's own validation table. sevdesk_set_tax_rule rebooks a draft voucher onto a different VAT rule with guardrails. sevdesk_create_invoice always creates drafts — nothing reaches a customer without review. sevdesk_get_invoice_pdf saves the rendered PDF without touching the invoice's send state.

Full coverage

sevdesk_list_operations · sevdesk_describe_operation · sevdesk_call

Rather than registering 151 tools and swamping the client's tool list, the server ships a searchable catalogue generated from sevDesk's OpenAPI document. Search for what you need, read its signature, call it. Every endpoint is reachable.

Common workflows

The tools compose — these are everyday bookkeeping jobs, each a single prompt:

• Month-end close: "Do a month-end check for June: pending drafts, bank payments without receipts, vouchers without payments, VAT findings, sums that don't add up."
• Chasing money: "Who owes me money? Show overdue invoices by age, and tell me which ones were never even marked as sent."
• Receipt discipline: "Compare my receipts folder with sevDesk and list what's missing on either side." (needs SEVDESK_RECEIPT_DIRS)
• Recurring costs: "Which subscriptions stopped appearing, and which suppliers am I booking inconsistently?"
• Before the VAT return: "Run the VAT audit and the §13b report for the quarter and summarize what my Steuerberater should know."
• Anything else: "Call the sevDesk API: …" — orders, credit notes, exports, parts and every other endpoint are reachable through the catalogue.

Configuration

The threat model, guarantees and vulnerability reporting are documented in SECURITY.md.

Privacy Policy

Everything runs locally: your token and accounting data flow only between your MCP client and the sevDesk API — no storage, no telemetry, no third parties. Full policy: PRIVACY.md.

Write safety

Read-only mode is enforced three times: write tools are hidden from the tool list, the dispatcher refuses them, and the HTTP client refuses every mutating request independently. With writes enabled:

• Every write tool accepts a per-call dryRun and honors the global SEVDESK_DRY_RUN.
• sevdesk_create_voucher and sevdesk_create_invoice default to drafts — nothing is booked or sent silently.
• sevdesk_set_tax_rule and sevdesk_mark_invoice_sent refuse enshrined documents and verify their changes by reading the document back.
• There is deliberately no email-send tool, and sevdesk_get_invoice_pdf never overwrites an existing file.
• Booked and paid vouchers are deliberately out of scope for API rebooking. The sevDesk API only updates drafts, and resetting a paid foreign-currency voucher recalculates its EUR amounts at today's exchange rate — silently changing historical values. Correct booked vouchers in the sevDesk UI, where the original amounts stay visible against the receipt.

The tax model

With sevdesk-Update 2.0, sevDesk models VAT through taxRule — split into a revenue set and an expense set. Older documents still carry the deprecated taxType string; the server understands both generations.

Expense rules (incoming vouchers, creditDebit: "C"):

Revenue rules (outgoing documents, creditDebit: "D"):

(Rules 18–21 — One Stop Shop and §18b — exist on invoices but are not accepted on vouchers; the audit flags them if they appear anyway.)

The classic mis-booking: a subscription from a supplier established abroad, booked as a plain domestic expense (taxRule 9) with a 0 % position. It looks harmless — reverse charge nets to zero for anyone with input-tax deduction — but it silently drops the §13b tax base out of your VAT return. The correct booking is taxRule 12 (or 13/14, depending on your situation). A CSV export cannot show you the difference, because it only carries the rate, not the rule. sevdesk_audit_vat finds it.

Development

npm run dev        # run from source
npm test           # unit tests
npm run typecheck  # tsc --noEmit
npm run build:catalog  # regenerate the operation catalogue from openapi/sevdesk-openapi.yaml

See CONTRIBUTING.md.

Roadmap

• Live validation against a real account (bookkeeping system 2.0)
• Contact-country detection, booking-account guidance checks, bank reconciliation
• Guarded invoice workflow (draft-only creation, PDF export, mark-as-sent)
• Remote hosting via the Streamable HTTP transport with a per-request token — server assembly is already transport-agnostic (src/server.ts)
• Compile-time endpoint types generated from the OpenAPI spec
• Integration tests against a sevDesk sandbox
• Export helpers for the annual VAT return (Kz 46 / 47)

License

MIT