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

... View full README on GitHub