Skip to main content
Glama
sevdesk-mcp

sevdesk-mcp

by joosthel

Create a voucher

sevdesk_create_voucher

Create a sevDesk voucher as a draft for review, specifying supplier, date, tax rule, and line items; verify allowed tax rules first to prevent VAT mis-bookings.

Instructions

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "supplierName": "<supplierName>",
      "voucherDate": "<voucherDate>",
      "taxRuleId": "<taxRuleId>",
      "positions": "<positions>"
    },
    "name": "sevdesk_create_voucher"
  }
}

Input Schema

NameRequiredDescriptionDefault
extraNoAdditional top-level voucher fields merged into the payload verbatim.
dryRunNoShow the payload instead of sending it.
statusNo50 = Entwurf (default). 100 = offen and 1000 = bezahlt need SEVDESK_ALLOW_BOOKING=true.
payDateNoPayment date, dd.mm.yyyy — only with status 1000. Needs SEVDESK_ALLOW_BOOKING=true.
fileNameNoFilename token returned by sevdesk_upload_voucher_file.
positionsYesLine items.
taxRuleIdYesVAT regulation id — every rule sevDesk accepts on a voucher, both sides. Required — never guessed. sevdesk_receipt_guidance lists the ones the booking account actually allows. Expense rules go with creditDebit C, revenue rules with D.
creditDebitNoC = credit, D = debit.
descriptionNoDocument/invoice number.
voucherDateYesVoucher date, dd.mm.yyyy.
supplierNameYesSupplier name as it should appear on the voucher.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.6.0
    • changedInput schema / properties / payDate / description
      Previous value: -"Payment date, dd.mm.yyyy — only with status 1000."New value: +"Payment date, dd.mm.yyyy — only with status 1000. Needs SEVDESK_ALLOW_BOOKING=true."
    • addedInput schema / properties / positions / items / properties / accountDatevId
      Added value: +{
      +  "description": "Booking account id for sevdesk-Update 2.0 (accountDatevId from sevdesk_receipt_guidance). Replaces accountingTypeId.",
      +  "type": "string"
      +}
    • changedInput schema / properties / positions / items / properties / accountingTypeId / description
      Previous value: -"sevDesk accounting type id."New value: +"sevDesk accounting type id (legacy bookkeeping only)."
    • changedInput schema / properties / status / description
      Previous value: -"50 = Entwurf, 100 = offen, 1000 = bezahlt (default 50)."New value: +"50 = Entwurf (default). 100 = offen and 1000 = bezahlt need SEVDESK_ALLOW_BOOKING=true."
  2. Changed3 schema fields changedv0.5.0
    • changedInput schema / properties / taxRuleId / description
      Previous value: -"VAT regulation id."New value: +"VAT regulation id — every rule sevDesk accepts on a voucher, both sides. Required — never guessed. sevdesk_receipt_guidance lists the ones the booking account actually allows. Expense rules go with creditDebit C, revenue rules with D."
    • changedInput schema / properties / taxRuleId / enum
      Previous value: -[
      -  "1",
      -  "2",
      -  "3",
      -  "4",
      -  "5",
      -  "11"
      -]New value: +[
      +  "1",
      +  "2",
      +  "3",
      +  "4",
      +  "5",
      +  "8",
      +  "9",
      +  "10",
      +  "11",
      +  "12",
      +  "13",
      +  "14",
      +  "16",
      +  "17",
      +  "22"
      +]
    • changedInput schema / required
      Previous value: -[
      -  "supplierName",
      -  "voucherDate",
      -  "positions"
      -]New value: +[
      +  "supplierName",
      +  "voucherDate",
      +  "taxRuleId",
      +  "positions"
      +]
  3. First observedv0.4.0

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, and the description goes further by disclosing the default status 50 draft behavior (nothing booked without review) and the SEVDESK_ALLOW_BOOKING gate for status 100/1000. No contradiction: warning that it can change data is consistent with a non-readOnly write tool flagged non-destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then the default-status behavior, then the prerequisite, then the fallback — a sensible order with no filler sentences. Minor waste in restating 'WRITE operation' and an emoji warning that the annotations already convey via readOnlyHint=false.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter mutation with nested positions and no output schema, the description covers the creation path, booking gate, tax-rule prerequisite and uncovered-case fallback. It omits what the call returns (voucher id) and the coupling to sevdesk_upload_voucher_file, though the schema's fileName description partly closes that gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real tax-domain meaning: expense-side reverse charge rules are 12/13/14, not 5, and creditDebit C pairs with expense rules while D pairs with revenue rules. That is context the schema's own taxRuleId description does not fully supply.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('Create a voucher') and pins the exact endpoint (/Voucher/Factory/saveVoucher), so an agent knows precisely what happens. It also distinguishes itself from the sibling fallback sevdesk_call by defining this as the covered wrapper path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete prerequisite ('Check sevdesk_receipt_guidance for the account's allowed tax rules first') and an explicit escape hatch ('For anything this wrapper does not cover, use sevdesk_call with operationId ...'). It does not address relationship to sevdesk_update_draft_voucher or the file-upload flow, but the primary when-to-use routing is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.