Skip to main content
Glama
sevdesk-mcp

sevdesk-mcp

by joosthel

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
SEVDESK_DRY_RUNNoShow what a write would send, without sending itfalse
SEVDESK_BASE_URLNoOverride the API hosthttps://my.sevdesk.de/api/v1
SEVDESK_API_TOKENYesYour sevDesk API token
SEVDESK_READ_ONLYNoHide write tools; sevdesk_call stays listed but refuses mutating operations at call timefalse
SEVDESK_TIMEOUT_MSNoPer-request timeout30000
SEVDESK_MAX_RETRIESNoRetries on 429/5xx, with backoff and Retry-After3
SEVDESK_RECEIPT_DIRSNoColon-separated allowlist of directories the receipt file tools may read and write
SEVDESK_KLEINUNTERNEHMERNo§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

CapabilityDetails
tools
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
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 params by name; remaining params entries become query parameters. Nested objects are encoded in sevDesk's bracket syntax (a[b]=c). Mutating operations are refused when the server runs with SEVDESK_READ_ONLY=true, and are only described (not sent) when SEVDESK_DRY_RUN=true or dryRun is passed. Operations with a preventSendBy query parameter (the *GetPdf reads) default it to true so a read does not mark the document as sent. GETs that change state (sendByWithRender, enshrine flags, preventSendBy=false) count as writes. Booking operations (bookVoucher, bookInvoice, bookCreditNote, their resetToOpen and resetToDraft, createPrivateTransactionRule) and writes that set a transaction status or move a voucher out of draft or mark it paid (updateCheckAccountTransaction, updateVoucher, voucherFactorySaveVoucher) are refused unless SEVDESK_ALLOW_BOOKING=true; prefer sevdesk_link_transaction for vouchers. Can call DELETE operations, which are irreversible. ⚠️ This tool can change data in sevDesk.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.7/5.0

Scored across 26 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count3/5

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.

Completeness3/5

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).

Maintenance

ActivityMaintained
ResponsivenessLimited data