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

24 tools cover all 151 API operations.

Audit

Everyday

sevdesk_ping · sevdesk_summarize · 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_summarize aggregates invoices or vouchers server-side — counts and net/tax/gross sums grouped by month, status or contact — so questions like "revenue in Q2" or "expenses by supplier" cost a few hundred tokens however large the ledger is. 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.

Agent Skill (optional)

The package ships an Agent Skill with these workflows spelled out — monthly close order, receipt triage, §13b investigation, audit-finding interpretation — so agents load the know-how on demand instead of rediscovering it each session. For Claude Code, copy it next to your project:

cp -r node_modules/sevdesk-mcp/skills/sevdesk-bookkeeping .claude/skills/

(or copy from a clone of this repo). Clients without skill support lose nothing: the server's own instructions and tool descriptions carry the essentials.

Configuration

Set these in the env block of your MCP client — that is the supported path and the one the client controls. For runs outside a client (npm run dev, node dist/index.js from a clone), copy .env.example to .env in the package root and the server reads it at startup. The file is read from the package root, never the working directory, and real environment variables always win over it, so a client's env block can never be shadowed by a stale .env. .env is gitignored.

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