sevdesk-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SEVDESK_DRY_RUN | No | Show what a write would send, without sending it | false |
| SEVDESK_BASE_URL | No | Override the API host | https://my.sevdesk.de/api/v1 |
| SEVDESK_API_TOKEN | Yes | Your sevDesk API token | |
| SEVDESK_READ_ONLY | No | Hide write tools; sevdesk_call stays listed but refuses mutating operations at call time | false |
| SEVDESK_TIMEOUT_MS | No | Per-request timeout | 30000 |
| SEVDESK_MAX_RETRIES | No | Retries on 429/5xx, with backoff and Retry-After | 3 |
| SEVDESK_RECEIPT_DIRS | No | Colon-separated allowlist of directories the receipt file tools may read and write | |
| SEVDESK_KLEINUNTERNEHMER | No | §19 UStG small-business scheme: audit suggestions point to the KU rule set (13/10/11), new invoices default to rule 11 at 0 % | false |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
sevDesk accounting (German SMB bookkeeping) for AI agents. Mode: read/write — writes default to drafts; booking payments is off (SEVDESK_ALLOW_BOOKING not set), including through sevdesk_call. Start with sevdesk_ping: it verifies the token and reports the account's bookkeeping generation. Tax rules are never guessed: write tools that need one take taxRuleId explicitly, and sevdesk_receipt_guidance lists what each booking account allows. Prefer the curated sevdesk_* tools; for anything else use sevdesk_call after sevdesk_list_operations / sevdesk_describe_operation. Every write accepts dryRun:true for a preview. Dates are yyyy-mm-dd; amounts EUR unless stated.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| sevdesk_pingA | Verify the API token, report server mode, bookkeeping generation (1.0 taxType / 2.0 taxRule). Run this first. |
| sevdesk_list_vouchersB | List incoming/outgoing vouchers with the fields that matter for bookkeeping: date, supplier, gross/net/tax, status and the decoded VAT treatment. Read-only. |
| sevdesk_get_voucherA | Fetch a single voucher including its line items, with the VAT treatment and per-position tax rates decoded. Read-only. |
| sevdesk_list_invoicesB | List invoices you issued, with number, customer, sums, status and dates. Read-only. |
| sevdesk_summarizeA | Aggregate invoices or vouchers over a date range WITHOUT returning rows: counts plus net/tax/gross sums, grouped by month, status, contact or nothing. Use this for totals ('revenue in Q2', 'expenses by supplier') instead of the list tools — the response stays small however large the ledger is. Read-only. |
| sevdesk_list_contactsB | List customers and suppliers. Read-only. |
| sevdesk_list_transactionsB | List bank transactions, optionally for one account and period. Read-only. |
| sevdesk_upload_voucher_fileA | Upload a local PDF/image/XML e-invoice to sevDesk's temporary voucher storage and return the filename token you pass to sevdesk_create_voucher. WRITE operation — refused under SEVDESK_READ_ONLY. ⚠️ This tool can change data in sevDesk. |
| sevdesk_create_voucherA | Create a voucher via /Voucher/Factory/saveVoucher. Defaults to status 50 (Entwurf) so nothing is booked without you reviewing it in sevDesk. Check sevdesk_receipt_guidance for the account's allowed tax rules first — expense-side reverse charge is 12/13/14, not 5. WRITE operation. For anything this wrapper does not cover, use sevdesk_call with operationId 'voucherFactorySaveVoucher'. ⚠️ This tool can change data in sevDesk. |
| sevdesk_receipt_guidanceA | sevDesk's own booking guidance: which DATEV/SKR accounts exist for expenses or revenue and which tax rules and rates each of them allows — the table sevDesk validates against when a voucher is booked. Filter by text, account number or tax rule; output is capped, never the full account dump. Read-only. |
| sevdesk_set_tax_ruleA | Rebook a voucher onto a different VAT rule (e.g. from 'Vorsteuerabziehbare Aufwendungen' onto Reverse Charge §13b, taxRule 12) with guardrails: refuses enshrined vouchers and rules from the wrong side of the books, verifies the result afterwards, and previews the request with dryRun. The voucher's positions keep their rates. Only works on draft vouchers — the sevDesk API refuses updates on booked/paid ones, and resetting a paid foreign-currency voucher via the API recalculates its EUR amounts at today's rate. Correct paid vouchers in the sevDesk UI instead. ⚠️ This tool can change data in sevDesk. |
| sevdesk_create_invoiceA | Create an outgoing invoice as a draft (status 50) — always a draft, so nothing reaches a customer without review in sevDesk. Positions carry name, quantity, price and tax rate; the contact's address is filled in automatically. Honors SEVDESK_DRY_RUN. ⚠️ This tool can change data in sevDesk. |
| sevdesk_get_invoice_pdfA | Fetch the rendered PDF of an invoice and save it into a directory from the SEVDESK_RECEIPT_DIRS allowlist. Never changes the invoice's send state (preventSendBy). Read-only towards sevDesk. |
| sevdesk_mark_invoice_sentA | Mark an invoice as sent without emailing anything (send types: PDF download, print, postal — deliberately no email). Refuses enshrined invoices and verifies the result. Honors SEVDESK_DRY_RUN. ⚠️ This tool can change data in sevDesk. |
| sevdesk_upload_voucher_file_contentA | Upload a receipt sent inline as base64 (e.g. an e-mail attachment) to sevDesk's temporary voucher storage — for hosted clients that cannot use sevdesk_upload_voucher_file's local path. Returns fileName, the token sevdesk_create_voucher attaches to a new voucher. PDF, PNG, JPG and XML (XRechnung / ZUGFeRD e-invoice) only, checked by content and not only the name, at most 10 MB. Accepts standard and URL-safe base64 and data: URLs. Creates no voucher by itself. ⚠️ This tool can change data in sevDesk. |
| sevdesk_update_draft_voucherA | Correct a draft voucher (status 50, Entwurf): date, document number, supplier name, tax rule and the positions (amounts, tax rate, booking account). positions replaces all positions: give the full new list; existing positions are reused in order (they keep their booking account unless accountDatevId is given), extra old ones are deleted. Example: gross 214.20 booked at 0 % -> positions [{sumNet: 180, taxRate: 19}] gives 180.00 + 34.20 VAT = 214.20. Positions you do not replace are sent back as they were entered, net or gross. A new taxRuleId is checked against the voucher's side (expense or revenue) and its position rates. finalize=true also sets the voucher to open (100), needed before sevdesk_link_transaction; every position then needs a booking account. finalize is refused unless the server runs with SEVDESK_ALLOW_BOOKING=true; without it the draft can still be corrected. Refuses open, paid and enshrined vouchers; keeps the attached file; verifies sums and status afterwards. ⚠️ This tool can change data in sevDesk. |
| sevdesk_audit_vatB | Sweep vouchers (Belege) and flag VAT problems: foreign suppliers booked as plain domestic expenses (taxRule 9/10) instead of Reverse Charge §13b (taxRule 12/13/14), revenue rules sitting on expense vouchers, tax rates that contradict the chosen rule, sums that do not add up, and the same supplier booked inconsistently across vouchers. Read-only. |
| sevdesk_reverse_charge_reportA | Total the reverse-charge (§13b) tax base for a period, split by meaning: expense vouchers with input-tax deduction (taxRule 12/14, nets to zero), without deduction (taxRule 13, VAT actually payable), and your own §13b revenue (taxRule 5). Separately lists vouchers that look like they belong in the report but are not booked that way. Read-only. |
| sevdesk_find_duplicatesA | Detect vouchers booked twice (same document number, or same supplier + amount within a few days) and vouchers left in Entwurf/offen status. Read-only. |
| sevdesk_subscription_gapsA | Detect suppliers that bill on a monthly cadence and report months with no voucher. A subscription that appears in March, April and June but not May almost always means a receipt was never entered. Read-only. |
| sevdesk_diff_receipt_folderA | Compare a local folder of receipt PDFs against the vouchers booked in sevDesk and report both directions: files that appear to have no voucher, and vouchers with no matching file. Matching uses the #reference in the filename first, then date + amount. Filenames are expected to look like '260626_Acme-Cloud_#INV-2043.pdf' or '2026-06-26_AcmeCloud_45.60.pdf'. Reads the filesystem but never writes; sevDesk access is read-only. |
| sevdesk_reconcile_transactionsA | Match bank transactions against vouchers by amount and date proximity, in both directions: payments with no plausible voucher (missing receipts) and non-draft vouchers no payment covers. Matching is a heuristic — treat the result as a checklist, not a verdict. Read-only. |
| sevdesk_invoice_agingA | Who owes you money and for how long: open and partially paid invoices bucketed by days overdue (invoice date + payment terms), the outstanding remainder per invoice, drafts that were never sent, and open invoices missing a send mark. Read-only. |
| sevdesk_list_operationsA | Search the sevDesk API catalogue (154 operations, API 2.0.0) for the operationId of anything not covered by a dedicated tool. Available tags: AccountingContact, Basics, CheckAccount, CheckAccountTransaction, CommunicationWay, Contact, ContactAddress, ContactField, CreditNote, CreditNotePos, Export, Invoice, InvoicePos, Layout, Order, OrderPos, Part, PrivateTransactionRule, Report, Tag, Voucher, VoucherPos. |
| sevdesk_describe_operationA | Show the full parameter list, request-body shape and an example call for one operationId. Always do this before sevdesk_call on an operation you have not used before. |
| sevdesk_callA | Execute any operation from the catalogue. Path parameters are taken from |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 26 tools
Most tools have clearly distinct targets: reads (list_vouchers, list_invoices, get_voucher), writes (create_voucher, create_invoice, update_draft_voucher, set_tax_rule), diagnostics (audit_vat, find_duplicates, subscription_gaps, diff_receipt_folder, reconcile_transactions) and API escape hatches (list_operations, describe_operation, call). The weakest boundaries are sevdesk_set_tax_rule vs. sevdesk_update_draft_voucher (both can rebook a draft's tax rule) and the four receipt-gap detectors, which a hurried agent could confuse even though the descriptions differentiate them (filesystem, bank transactions, duplicates, subscription cadence). sevdesk_call overlaps every dedicated tool by design, but is explicitly framed as the fallback.
All 26 tools share a sevdesk_ prefix and snake_case, so the family is instantly recognisable and the verb_noun pattern dominates (list_vouchers, get_voucher, create_invoice, mark_invoice_sent, find_duplicates). A handful of names drop the verb (invoice_aging, receipt_guidance, reverse_charge_report, subscription_gaps) and ping is a bare verb, which are minor but real deviations from the pattern.
26 tools is at the heavy end: the domain is genuinely broad (vouchers, invoices, contacts, bank transactions, VAT audits, file upload, plus a generic API gateway), so most tools earn their place rather than duplicating each other. Still, an agent has to triage a large surface, and a few niche diagnostics (subscription_gaps, reverse_charge_report) could plausibly have been folded into summarize/audit_vat.
Coverage is broad — read, aggregate, create, correct, upload, PDF export, send-marking and a generic catalogue gateway that can reach all 154 sevDesk operations — but there are notable holes: no delete operations, no contact or transaction write tools, and no explicit payment/booking tool. Most damaging, sevdesk_link_transaction is referenced twice inside other descriptions ('needed before sevdesk_link_transaction', 'prefer sevdesk_link_transaction') yet is absent from the tool set, leaving a dangling pointer that will send agents chasing a nonexistent tool (the call gateway is the only workaround).