sevdesk-mcp

sevdesk-mcp

English · Deutsch

面向 sevDesk 的完整 MCP 服务：涵盖所有 API 端点、受保护的写入操作，以及内置的簿记审计层。

将 Claude（或任何 MCP 客户端）连接到你的 sevDesk 账户：列出并创建凭证和发票、对账银行交易、调用全部 151 个 API 操作，还能运行审计，识别各种错误记账：例如将境外供应商按国内 0 % 记账，而非采用 Reverse Charge §13b；使用记账科目不允许的税务规则；或付款没有对应的收据。

状态：v0.5.0。 已针对真实 sevDesk 账户（簿记系统 2.0）进行实时验证——审计恰好发现了本工具旨在识别的那类错误记账。请参阅 CHANGELOG.md。

快速开始

你需要： Node.js ≥ 22、一个 sevDesk 账户，以及一个 MCP 客户端（Claude Code、Claude Desktop 或其他客户端）。

1. 获取 API 令牌

在 sevDesk 中：Settings → Users → your user → API。令牌是一个 32 位十六进制字符串。

⚠️ sevDesk API 令牌没有作用域——它能执行你的登录账户可执行的一切操作。请像对待密码一样保管，并从只读模式开始。

2. 连接 MCP 客户端

Claude Code — 运行一条命令，然后将你的真实令牌填入它写入的配置文件（~/.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 — 添加到 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"
      }
    }
  }
}

其他 MCP 客户端的使用方式也相同：采用 stdio 传输，通过 npx -y sevdesk-mcp（或在克隆的仓库中运行 node dist/index.js）启动，并通过环境变量配置。若要从源代码运行：git clone https://github.com/joosthel/sevdesk-mcp && cd sevdesk-mcp && npm install && npm run build。

3. 首次运行

重启客户端，并让它运行 sevdesk_ping。你应该会看到 ok: true、簿记系统版本（2.0 = taxRule，1.0 = 旧版 taxType）以及模式（READ-ONLY）。然后就可以开始提问：

• “运行今年的增值税审计，并解释每项高严重性发现。”
• “我的美国软件订阅是否按反向收费记账？本季度的 §13b 基数是多少？”
• “哪些银行付款还没有收据？”
• “为联系人 1009 起草一张发票：咨询 3 天，每天 800 €。”（需要写入模式）
• “哪些记账科目允许使用 taxRule 12？”
• “调用 sevDesk API：获取最近 10 个订单。” — 通用目录涵盖了所有精选工具未覆盖的操作。

审计发现示例：

{
  "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. 启用写入（可选，稍后再做）

确认设置无误后，将 SEVDESK_READ_ONLY 设为 "false"，然后重启客户端。每个写入工具都支持 dryRun（并遵循全局设置 SEVDESK_DRY_RUN）——它会准确显示将要发送的内容，但不会实际发送。请参阅写入安全。

工具

24 个工具涵盖全部 151 个 API 操作。

审计

工具	功能
sevdesk_audit_vat	标记反向征税误记、使用了错误账目方向的规则、记账账户不允许的税务规则、与税务规则矛盾的税率、金额合计不符，以及供应商记账不一致等问题。有供应商联系人所在国家/地区信息时会使用该信息
sevdesk_reverse_charge_report	汇总某一期间的 §13b 税基，并拆分为净额归零（规则 12/14）、实际应缴（规则 13）和自有收入（规则 5）
sevdesk_find_duplicates	查找重复的单据编号、N 天内同一供应商和金额的记录，以及卡在 Entwurf 状态的凭证
sevdesk_subscription_gaps	检测各供应商的月度周期，并报告缺失的月份
sevdesk_diff_receipt_folder	将本地文件夹中的收据 PDF 与已记账凭证进行双向比对（需要 SEVDESK_RECEIPT_DIRS）
sevdesk_reconcile_transactions	按金额和日期接近程度，将银行交易与凭证进行匹配：无收据的付款、无付款的凭证
sevdesk_invoice_aging	谁欠你钱、欠了多久：按逾期天数分组的未结发票、部分付款后的剩余金额，以及从未发送的草稿

日常操作

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

亮点：sevdesk_summarize 在服务端汇总发票或凭证，按月份、状态或联系人分组统计数量以及净额/税额/总额，因此无论账簿有多大，回答“Q2 的收入”或“各供应商的支出”等问题都只需几百个 token。sevdesk_receipt_guidance 根据 sevDesk 自己的验证表，回答“sevDesk 实际接受哪些记账账户 / 税务规则 / 税率组合”。sevdesk_set_tax_rule 可在安全检查的保护下，将草稿凭证重新记账到另一项增值税规则。sevdesk_create_invoice 始终只创建草稿，未经审核的内容不会发送给客户。sevdesk_get_invoice_pdf 会保存生成的 PDF，不会更改发票的发送状态。

完整覆盖

sevdesk_list_operations · sevdesk_describe_operation · sevdesk_call

服务不会注册 151 个工具来淹没客户端的工具列表，而是提供一个可搜索的目录，该目录根据 sevDesk 的 OpenAPI 文档生成。搜索所需内容，查看其签名，然后调用即可。每个端点都可访问。

常见工作流

这些工具可以组合使用，以下是日常记账任务，每项只需一条提示词：

• 月末结账： “检查 6 月的月末情况：待处理草稿、没有收据的银行付款、没有付款的凭证、增值税问题，以及金额合计不符的情况。”
• 催收款项： “谁欠我钱？按逾期时间显示逾期发票，并告诉我哪些发票甚至从未标记为已发送。”
• 收据管理： “将我的收据文件夹与 sevDesk 比较，并列出哪一方缺少哪些内容。”（需要 SEVDESK_RECEIPT_DIRS）
• 经常性支出： “哪些订阅不再出现了？哪些供应商的记账方式不一致？”
• 提交增值税申报前： “运行本季度的增值税审计和 §13b 报告，并总结我的 Steuerberater 应了解的事项。”
• 其他事项： “调用 sevDesk API：…”——订单、贷项通知单、导出、零件以及其他所有端点，都可以通过目录访问。

Agent Skill（可选）

此软件包附带一套 Agent Skill，详细列出了这些工作流——月结顺序、收据分类、§13b 调查、审计发现解读——让 Agent 按需加载相关知识，而不必在每次会话中重新摸索。对于 Claude Code，请将其复制到项目旁边：

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

（也可以从此仓库的克隆副本中复制）。不支持 Skill 的客户端也不会因此缺少任何内容：服务自身的 instructions 和工具描述涵盖了核心信息。

配置

变量	默认值	用途
SEVDESK_API_TOKEN	（必填）	你的 sevDesk API 令牌
SEVDESK_READ_ONLY	false	布尔值（可接受 1/true/yes/on 或 0/false/no/off；其他值会导致启动失败）。隐藏写入工具；sevdesk_call 仍会列出，但在调用时拒绝执行会修改数据的操作
SEVDESK_DRY_RUN	false	布尔值，可接受的值相同。显示写入操作将会发送的内容，但不实际发送
SEVDESK_RECEIPT_DIRS	（未设置——文件工具已禁用）	收据文件工具可读写的绝对目录白名单，以平台路径分隔符分隔（macOS/Linux 上为 :，Windows 上为 ;）。会解析符号链接，因此指向列表之外的链接会被拒绝
SEVDESK_BASE_URL	https://my.sevdesk.de/api/v1	覆盖 API 主机。必须使用 https://（令牌会作为标头发送）；仅当主机为 localhost、127.0.0.1 和 [::1] 时，才接受纯 http://
SEVDESK_TIMEOUT_MS	30000	每次请求的超时时间（大于 0 的整数）
SEVDESK_MAX_RETRIES	3	大于等于 0 的整数；0 表示完全不重试。采用带抖动的退避重试，并对 Retry-After 值进行限制。遇到 429 时始终重试（被限流的调用从未执行）；只有读取操作在遇到 5xx 或网络故障时才会重试——写入操作在结果不确定的故障后绝不会重放，因此超时不会创建重复的草稿
SEVDESK_RATE_LIMIT	4	客户端侧请求速率限制（令牌桶），单位为请求/秒，避免突发式审计扇出请求触发 sevDesk 的限流。0 表示禁用速率限制
SEVDESK_DEBUG	false	布尔值，可接受的值相同。将 METHOD /path -> status 记录到 stderr——绝不记录查询字符串、请求正文或令牌

请在 MCP 客户端的 env 块中设置这些变量——这是受支持的方式，也由客户端控制。若在客户端之外运行（例如执行克隆仓库中的 npm run dev 或 node dist/index.js），请将 .env.example 复制到软件包根目录并命名为 .env，服务将在启动时读取该文件。文件始终从软件包根目录读取，而非工作目录；并且实际环境变量的优先级始终高于文件中的值，因此客户端的 env 块不会被过时的 .env 覆盖。.env 已加入 gitignore。

威胁模型、安全保障和漏洞报告方式见 SECURITY.md。

隐私政策

所有操作都在本地进行：你的令牌和会计数据只会在 MCP 客户端与 sevDesk API 之间流转——不存储、不收集遥测数据，也不涉及第三方。完整政策见：PRIVACY.md。

写入安全

只读模式通过三层机制强制执行：写入工具不会显示在工具列表中，分派器会拒绝调用这些工具，而且 HTTP 客户端会独立拒绝每个修改请求。sevdesk_call 会将会更改状态的 GET 请求（sendByWithRender、值为真值的 enshrine* 标志、关闭 preventSendBy）视为写入操作。启用写入后：

• 每个写入工具都接受单次调用的 dryRun，并遵循全局设置 SEVDESK_DRY_RUN。
• sevdesk_create_voucher 和 sevdesk_create_invoice 默认创建草稿——不会在用户不知情的情况下入账或发送。
• sevdesk_set_tax_rule 和 sevdesk_mark_invoice_sent 会拒绝已封存的单据，并通过重新读取单据来验证更改。
• 我们有意不提供发送邮件的工具，而且 sevdesk_get_invoice_pdf 绝不会覆盖现有文件。
• 已入账和已付款的凭证明确不支持通过 API 重新入账。 sevDesk API 只会更新草稿，而重置已付款的外币凭证会按今日汇率重新计算其欧元金额，从而在不提示的情况下更改历史金额。请在 sevDesk UI 中更正已入账的凭证，原始金额会继续显示在收据上。

税务模型

在 sevdesk-Update 2.0 中，sevDesk 通过 taxRule 对增值税进行建模，分为收入规则集和支出规则集。较早的单据仍带有已弃用的 taxType 字符串；服务端同时支持这两代格式。

支出规则（收到的凭证，creditDebit: "C"）：

taxRule	含义	税率	旧版 taxType
8	欧盟内部采购	0 / 7 / 19 %	—
9	可抵扣进项税的支出	0 / 7 / 19 %	default
10	不可抵扣进项税的支出	0 %	ss
12	§13b 第 2 款反向征税，可抵扣进项税	0 %	—
13	§13b 反向征税，不可抵扣进项税	0 %	—
14	§13b 第 1 款反向征税，欧盟	0 %	—
16	不属于应税范围（支出）	0 %	—

收入规则（开出的单据，creditDebit: "D"）：

taxRule	含义	税率	旧版 taxType
1	应缴增值税的交易	0 / 7 / 19 %	default
2	出口	0 %	—
3	欧盟内部供应	0 / 7 / 19 %	eu
4	§4 UStG 规定的免税交易	0 %	—
5	§13b 反向征税（第 60 栏）	0 %	—
11	根据 §19 UStG 不征收税款	0 %	ss
17	在本国境内不征税的服务	0 %	noteu
22	不属于应税范围（收入）	0 %	—

（规则 18–21——一站式服务和 §18b——存在于发票中，但不适用于凭证；如果出现，审计会将其标记出来。）

典型的错误入账：向注册地在国外的供应商购买订阅服务，却将其作为普通的国内支出（taxRule 9）入账，税率为 0 %。这看起来无关紧要——对于可以抵扣进项税的人而言，反向征税后的净额为零——但这会悄悄导致 §13b 的计税基础从增值税申报表中漏掉。正确的入账规则是 taxRule 12（或视具体情况而定的 13/14）。CSV 导出无法显示这种差异，因为其中只包含税率，不包含规则。sevdesk_audit_vat 可以发现这一问题。

开发

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

请参阅 CONTRIBUTING.md。

路线图

• 针对真实账户进行实时验证（记账系统 2.0）
• 联系人国家/地区检测、记账科目指导检查、银行对账
• 受保护的发票工作流（仅创建草稿、导出 PDF、标记为已发送）
• 通过 Streamable HTTP 传输进行远程托管，并使用逐请求令牌——服务端组装已与传输方式无关（src/server.ts）
• 根据 OpenAPI 规范生成编译时端点类型
• 针对 sevDesk 沙盒的集成测试
• 年度增值税申报表（Kz 46 / 47）的导出辅助工具

许可证

MIT