BuchhaltungsButler

ohneben 的 Buchhaltungsbutler MCP

---

许可证与检查

MCP 注册表

软件包标识符

此服务使用专属标识符。名称不同的并非本项目：

位置	标识符
MCP 注册表	io.github.ohneben/buchhaltungsbutler-mcp
容器（GHCR）	ghcr.io/ohneben/buchhaltungsbutler-mcp
npm	@ohneben/buchhaltungsbutler-mcp（尚未发布）

不带作用域的 npm 软件包 buchhaltungsbutler-mcp 是另一个作者的其他项目（mrvnklm/buchhaltungsbutler-mcp），与本项目毫无关系。此页面之外的目录若链接到该项目，指向的就是错误的软件包。

通过 Claude、Cursor 等 AI 助手以及任何其他 MCP 客户端，以自然语言管理你的 BuchhaltungsButler 会计事务。

此 Model-Context-Protocol 服务提供 BuchhaltungsButler API v1——根据官方 OpenAPI 规范（规范版本 1.9.1）生成全部 54 个端点，并封装为 46 个 MCP 工具。每个工具都经过安全性分类（只读／写入／破坏性），让你的助手在执行操作之前就知道它会做什么。支持通过 stdio（Claude Desktop 和其他本地启动器）或 Streamable HTTP（托管于 Docker）运行。

为什么选择此服务

有些 MCP 服务只是简单转发 API。此服务旨在实现安全地交由大模型使用，并且适合日常运行：

你将获得什么	为什么重要
从官方规范自动生成的全部 54 个端点	全面覆盖凭证、交易、记账、发票、报表和主数据。不挑着生成，不会遗漏。
每个工具都经过安全分类 🟢 / 🟡 / 🔴	每个工具描述开头的横幅都会准确告知模型将执行什么操作——读取、创建、更改、撤销或删除——然后模型才会采取行动。
机器可读的 MCP 注解（readOnlyHint、destructiveHint）	会处理注解的宿主（包括 Claude）可以自动允许读取操作，并在执行破坏性操作前要求确认。
两种传输方式：stdio 和 Streamable HTTP	在 Claude Desktop 中本地使用，或运行持久服务，让任意数量的 MCP 客户端通过 HTTP 访问。
Docker + docker-compose、健康检查、自动重启	开箱即用的生产级部署：运行 docker compose up，服务便会持续运行。
HTTP 端点上的 Bearer 令牌身份验证	只要服务绑定到 loopback 之外的地址，此项便是必需的：如果没有 MCP_AUTH_TOKEN，服务会拒绝启动，而不是在未受保护的情况下开放 API。
内置速率限制	自动将请求速率控制在 BuchhaltungsButler 的每客户每分钟 100 次请求限制以下，避免触及限制。
你的凭据永远不会发送给模型	凭据存放在服务环境中，并在每次请求时注入——助手只能看到工具输入和 API 响应。

对比

截至目前，这是唯一专门为 BuchhaltungsButler 打造的 MCP 服务。 或者，你也可以将通用的 OpenAPI→MCP 封装器指向该规范—— 不过这样会缺少不少功能：

功能	本项目	通用 OpenAPI→MCP 封装器*
覆盖全部 54 个 BuchhaltungsButler 端点	✅	✅
每个工具均带有 🟢 / 🟡 / 🔴 安全类别和横幅	✅	❌
readOnlyHint / destructiveHint MCP 注解	✅	➖
解析批量负载中的 $ref + 清理 HTML 格式的描述	✅	➖
内置速率限制（低于 BB 每客户每分钟 100 次的限制）	✅	❌
stdio 传输	✅	✅
Streamable HTTP 传输	✅	➖
Docker + docker-compose、健康检查、自动重启	✅	❌
端点强制要求使用 Bearer 令牌进行身份验证	✅	❌
在服务端注入凭据，永不发送给模型	✅	➖
许可证	MIT	不同

_{*通用 OpenAPI→MCP 封装器可将任意 Swagger/OpenAPI 规范转换为 MCP 工具。 它们能够访问相同的端点，但会以相同方式处理所有操作——没有安全分类、没有运维方面的考量，也没有针对真实会计数据设计的防护措施。“➖”= 因工具而异／不保证。}

你可以用它做什么

连接服务后，你可以这样请求助手：

• “列出上个月所有尚未结清的收到的凭证。”
• “为 ACME GmbH 创建一张发票草稿：咨询 10 小时，每小时 120 欧元。”
• “将这笔银行交易记入总账科目 4400。”
• “上传这张 PDF 凭证，并将其关联到相应的交易。”
• “显示我的供应商，并为我们的托管服务提供商新增一个供应商。”
• “生成上一季度的 BWA，并显示科目 4400 的账户明细。”

这些工具会根据官方 API 自动生成，并分为 🟢 只读、🟡 写入和 🔴 破坏性操作三类——实现完善的宿主可以对每一类采取不同的处理方式。

工作原理

Claude / Cursor / beliebiger MCP-Client  ──MCP──►  dieser Server  ──HTTPS──►  BuchhaltungsButler API (Cloud)

服务器会读取随附的 OpenAPI 规范，并据此生成 MCP 工具（包括解析 $ref 批量负载以及从描述中移除 HTML），为每个工具标注其安全类别，并将你的 Basic-Auth 凭据以及 api_key 附加到每个发出的请求中。你的凭据保留在服务器环境中——模型永远看不到，也不会接触它们。

前提条件

• 一个拥有 API 访问权限的 BuchhaltungsButler 账户——一个 API Client + API Secret （设置 → API），以及一个客户的 api_key （参见获取 API 凭据）。
• 用于下方快速启动的 Docker（macOS/Windows 上的 Docker Desktop）——或者 Node.js ≥ 18，以便从源代码启动。

快速启动（Docker）

1. 填写凭据。 复制示例配置并填写：

cp .env.example .env
# .env bearbeiten → BB_API_CLIENT, BB_API_SECRET, BB_API_KEY setzen
#                 → MCP_AUTH_TOKEN setzen. PFLICHT, sonst startet der Server
#                   nicht, denn .env.example bindet auf 0.0.0.0:
#                   openssl rand -hex 32

2. 启动服务器：

docker compose up -d --build

3. 检查服务器是否正在运行：

curl -s http://localhost:3000/health     # → {"status":"ok","server":"buchhaltungsbutler-mcp"}

4. 连接 MCP 客户端。 在 Claude 中，将远程端点添加为自定义连接器 （设置 → 连接器），或使用 mcp-remote 在本地桥接。将以下内容填入客户端配置中的 mcpServers，然后完全重启应用：

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3000/mcp",
        "--header", "Authorization: Bearer DEIN_MCP_AUTH_TOKEN"
      ]
    }
  }
}

（仅当你在回环地址上绑定且不使用令牌时，才可省略 --header 行。 上方的 Docker 快速启动必须使用令牌。）

想用现成的镜像？

每次推送到 main 都会在 GitHub Container Registry 中发布可直接启动的镜像——这样你就可以完全跳过本地构建：

docker run -d --name buchhaltungsbutler-mcp -p 3000:3000 --env-file .env \
  ghcr.io/ohneben/buchhaltungsbutler-mcp:latest

获取 API 凭据

BuchhaltungsButler 使用两层身份验证（参见 官方文档）：

1. HTTP-Basic-Auth——一个 API Client + API Secret，即你的全局 API 凭据。可在 BuchhaltungsButler 的设置 → API中查看或创建。
2. api_key——用于指定请求针对哪个客户账户。它位于相应客户的公司资料设置中。

将这三个值填入 .env。服务器会将它们附加到每个请求中，因此你的 助手永远不会看到这些凭据。单次工具调用也可以选择提供自己的 api_key，以访问其他客户账户。

配置

所有配置都设置在 .env 中（从 .env.example 复制）：

变量	必填	默认值	说明
BB_API_CLIENT	✅	—	API 客户端（Basic-Auth 用户名）
BB_API_SECRET	✅	—	API 密钥（Basic-Auth 密码）
BB_API_KEY	✅	—	默认客户 api_key
MCP_TRANSPORT	—	stdio	stdio 或 http（Docker 镜像默认使用 http）
PORT	—	3000	监听的 HTTP 端口
HOST	—	0.0.0.0	HTTP 绑定地址
MCP_HTTP_PATH	—	/mcp	MCP 的 HTTP 路由
MCP_AUTH_TOKEN	⚠️	(关闭)	在 /mcp 上要求提供 Authorization: Bearer <Token>。如果 HOST 不是环回地址，则必须设置此项，否则服务不会启动
MCP_ALLOWED_HOSTS	—	(自动)	允许的 Host 标头，使用逗号分隔（防范 DNS 重绑定）。位于反向代理后时需要设置
MCP_ALLOW_INSECURE	—	(关闭)	允许在未设置令牌时启动。仅用于已确认无法访问的端点
MCP_SESSION_TTL	—	1800	Session 被丢弃前的空闲秒数
MCP_MAX_SESSIONS	—	256	并发 Session 数量上限
BB_ALLOW_API_KEY_OVERRIDE	—	(关闭)	允许工具调用覆盖 api_key
BB_RATE_LIMIT	—	90	客户端每分钟请求数限制
BB_READ_TIMEOUT_MS	—	55000	读取工具的总时间预算（毫秒），适用于所有尝试。低于 SDK 客户端放弃等待的 60 秒
BB_READ_RETRIES	—	2	读取工具在超时、网络错误或 HTTP 429/502/503/504 后的额外尝试次数（最多 5 次），前提是时间预算充足。如果客户端中止，则不会启动额外尝试。写入工具不会重试，也没有超时
BB_BASE_URL	—	(来自 Spec)	覆盖 API 基础 URL

更改 .env 后，运行 docker compose up -d --force-recreate 重新加载。

工具名称

每个工具都命名为 <资源>_<动词>。动词固定为：list、get、 create、update、delete、upload、assign、unassign、unconfirm、 restore、cancel。这样，无论相应的 BB 路径如何命名，同一类操作 在各处都保持一致（API 混用了 add 和 create，并且有两个批量路径 使用 camelCase）。

创建操作始终通过接收列表的工具完成。receipts_create 可以创建一张或 一百张收据；单条记录就是只有一个条目的列表。因此，54 个端点对应 46 个工具：8 个单项端点已合并到对应的批量端点中。

旧名称仍可调用

截至 1.1.1 的名称仍然有效。它们不再显示在目录中，但调用时会进行解析， 以免较早版本中硬编码的调用失效。使用单个字段调用 receipts_add， 仍会转到 /receipts/add。

BB_READ_ONLY 和 BB_TOOL_ALLOWLIST 会优先生效：无法通过旧名称访问 被策略排除的工具。

旧名称（截至 1.1.1）	新名称
accounts_get	accounts_list
receipts_get	receipts_list
receipts_get_id_by_customer	receipts_get_by_id
receipts_add、receipts_addBatch	receipts_create
transactions_add、transactions_addBatch	transactions_create
settings_get_creditors	creditors_list
settings_add_creditor、settings_add_batch_creditors	creditors_create
settings_get_postingaccounts	postingaccounts_list
postings_add_free、postings_add_batch_free	postings_create_free
transactions_assign_receipt、transactions_assign_batch_receipt	transactions_assign_receipts

完整映射见 src/naming.ts。

工具安全类别

每个工具描述都以以下横幅之一开头，并带有相应的 MCP 注解：

横幅	数量	readOnlyHint	destructiveHint	含义
🟢 只读	15	true	false	仅获取数据。无害。
🟡 写入 · 创建数据	17	false	false	创建记录（非幂等，多次调用会产生重复记录）。
🟡 写入 · 修改数据	4	false	false	直接修改现有主数据。
🟡 写入 · 关联/解除关联	3	false	false	将凭证与交易关联，或解除关联。可撤销。
🟡 写入 · 撤销状态	4	false	false	将记账设为未确认 / 恢复凭证。可撤销。
🔴 破坏性操作 · 删除	3	false	true	删除或取消一条记录。应事先征求确认。

尊重注解的主机（包括 Claude）可以要求确认后再使用带有 destructiveHint 的工具，并自动信任带有 readOnlyHint 的工具。

每个工具还带有一个 outputSchema，用于定义成功响应的结构。因此， 成功调用不仅会以文本形式返回响应，还会返回 structuredContent。

随时可以运行 npm run list-tools（无需凭据）输出完整目录。

🟢 只读（15）

工具	端点
accounts_list	POST /accounts/get
cost_locations_list	POST /cost-locations/get
creditors_list	POST /settings/get/creditors
debtors_list	POST /settings/get/debtors
postingaccounts_list	POST /settings/get/postingaccounts
postings_list	POST /postings/get
receipts_get_by_id	POST /receipts/get/id_by_customer
receipts_list	POST /receipts/get
receipts_list_assigned_transactions	POST /receipts/assigned-transactions/get
reports_get_bwa	POST /reports/get/bwa
reports_get_sums	POST /reports/get/sums
reports_get_sums_ledger	POST /reports/get/sums/ledger
transactions_get_by_id	POST /transactions/get/id_by_customer
transactions_list	POST /transactions/get
transactions_list_assigned_receipts	POST /transactions/assigned-receipts/get

🟡 写入 · 创建数据（17）

带有两个端点的工具接受列表。如果调用改为传入单个字段，则会转到单条端点。

工具	端点	单条端点
accounts_create	POST /accounts/add
comments_create	POST /comments/add
cost_locations_create	POST /cost-locations/add
creditors_create	POST /settings/add-batch/creditors	POST /settings/add/creditor
debtors_create	POST /settings/add-batch/debtors	POST /settings/add/debtor
invoices_create	POST /invoices/create
invoices_create_draft	POST /invoices/create/draft
invoices_create_e_invoice	POST /invoices/create/e-invoice
postingaccounts_create	POST /settings/add/postingaccount
postings_create_for_receipt	POST /postings/add-batch/receipts	POST /postings/add/receipt
postings_create_for_transaction	POST /postings/add-batch/transactions	POST /postings/add/transaction
postings_create_free	POST /postings/add-batch/free	POST /postings/add/free
receipts_create	POST /receipts/addBatch	POST /receipts/add
receipts_upload	POST /receipts/upload
reports_create_bwa	POST /reports/create/bwa
reports_create_sums	POST /reports/create/sums
transactions_create	POST /transactions/addBatch	POST /transactions/add

🟡 写入 · 修改（4）· 关联（3）· 撤销（4）

工具	端点	子类别
cost_locations_update	POST /cost-locations/update	修改
creditors_update	POST /settings/update/creditor	修改
debtors_update	POST /settings/update/debtor	修改
postingaccounts_update	POST /settings/update/postingaccount	修改
postings_assign_receipt_to_free	POST /postings/assign/receipt-to-free-posting	关联
transactions_assign_receipts	POST /transactions/assign-batch/receipt	关联
transactions_unassign_receipt	POST /transactions/unassign/receipt	关联
postings_unconfirm_free	POST /postings/unconfirm/free	撤销
postings_unconfirm_for_receipt	POST /postings/unconfirm/receipt	撤销
postings_unconfirm_for_transaction	POST /postings/unconfirm/transaction	撤销
receipts_restore	POST /receipts/restore/id_by_customer	撤销

🔴 破坏性操作 · 删除（3）

工具	端点	说明
receipts_delete	POST /receipts/delete/id_by_customer	可通过 receipts_restore 恢复
cost_locations_delete	POST /cost-locations/delete	无法恢复
postings_cancel	POST /postings/cancel	删除尚未提交的记账记录；已提交的记录则通过一笔冲销记录进行抵消

v1 API 无法执行的操作

这些缺失项也会有意写入工具说明，以免模型查找不存在的端点：

资源	缺失项
应付账款方、应收账款方、记账科目	无法删除
账户（accounts）	无法修改或删除
评论	无法读取、修改或删除
发票	无法读取、修改或冲销
交易	无法修改或删除

从源代码启动（stdio，无需 Docker）

更喜欢为 Claude Desktop 使用经典 stdio 模式？可以在本地构建：

npm install
npm run build

然后在 claude_desktop_config.json 中将 Claude Desktop 指向编译后的入口点：

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/ABSOLUTER/PFAD/Buchhaltungsbutler MCP/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BB_API_CLIENT": "dein-api-client",
        "BB_API_SECRET": "dein-api-secret",
        "BB_API_KEY": "dein-kunden-api-key"
      }
    }
  }
}

或者改为通过 stdio 运行容器：

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "BB_API_CLIENT", "-e", "BB_API_SECRET", "-e", "BB_API_KEY",
        "buchhaltungsbutler-mcp:latest"
      ],
      "env": {
        "BB_API_CLIENT": "dein-api-client",
        "BB_API_SECRET": "dein-api-secret",
        "BB_API_KEY": "dein-kunden-api-key"
      }
    }
  }
}

（请先构建镜像：docker build -t buchhaltungsbutler-mcp:latest .）

保持 Spec 为最新版本

随附的 spec.json 是 BuchhaltungsButler v1 官方 OpenAPI Spec，也是工具的权威信息来源。更新到较新的 API 版本：

curl -s https://app.buchhaltungsbutler.de/docs/api/v1.de.json -o spec.json
npm run build

新增路径会自动采用；请将其添加到 src/categories.ts 中的 PATH_CATEGORY，以便为其分配正确的安全类别（未映射的路径会保守地归入 create 类别）。

版本号说明： BuchhaltungsButler 不会可靠地维护 Spec 中的 info.version 字段——内容可能发生变化，而版本号并未递增。因此进行比对时，请勿依赖版本号，而应比较路径列表（paths）和端点参数。

开发

关于已修正的记账和关联响应、部分错误以及写入结果不明确等说明，请参阅：记账凭证并关联付款。

npm install
npm run build      # TypeScript → dist/ kompilieren
npm test           # Vitest-Suite ausführen
npm run list-tools # kategorisierten Tool-Katalog ausgeben (ohne Zugangsdaten)

CI 会在 Node 20 和 22 下构建并测试每次推送；推送到 main 时还会将 Docker 镜像发布到 GitHub Container Registry。

如需使用自己的 API 凭据进行补充检查，请参阅 只读 API/MCP 验证。常规测试套件使用合成数据，无需凭据。

说明与约定

• 日期：YYYY-MM-DD。金额：使用句点作为小数分隔符（例如 -12.30）。
• 文件上传（receipts_upload）：文件以 Base64 字符串的形式传入 file 字段。receipts_create 创建不含文件的凭证。
• 分页：大多数 list 工具接受 limit 和 offset。在已检查的凭证、交易和记账列表中，rows 只统计当前 页，而非总记录数。应识别重复的 ID 和进度停滞。空的末页和去重都不能证明 数据完整：实测中，经过筛选的交易页面存在重叠，同时也有其他 ID 缺失。对于 transactions_list，优先使用 id_by_customer_from，并保持筛选条件和 limit 不变，不使用 offset： 游标为排他边界，并强制按 ID 升序排序。从 0 开始， 然后将获得的最大 ID 原样设为下一个游标；检查 ID 和进度， 直到返回空页，并独立核对。详情和限制：只读验证。
• 单条获取：receipts_get_by_id 和 transactions_get_by_id 要求 id_by_customer 为相应列表工具返回的正整数。服务端会将此编号放入 API 路径。
• 创建始终通过接受数组的工具进行；Item 架构会从 Spec 定义中解析并提供给模型。单条记录就是仅含一个条目的数组。
• 报表（BWA、汇总与余额清单）会在后台异步生成：先调用 reports_create_*，然后使用返回的 id_by_customer 调用 reports_get_*。新生成的同类型报表会替换之前的报表。
• 账户明细账：reports_get_sums_ledger 只需要记账账户编号和 时间段；API 会直接返回结果，无需预先生成 SuSa，也无需报表 ID。
• 速率限制：BuchhaltungsButler 每个客户每分钟允许 100 次请求；服务端会在 BB_RATE_LIMIT（默认值为 90）时自行限流，以确保低于上限。

安全

• 你的 API 凭据仅存放在 .env 中，且该文件已从 Git 中排除。切勿提交真实密钥。 如果发生泄露，请前往 BuchhaltungsButler → 设置 → API 轮换凭据。
• HTTP 端点绑定到回环地址以外时，必须提供令牌。 如果没有 MCP_AUTH_TOKEN，服务将拒绝启动，并在错误信息中说明如何处理。请通过 Authorization: Bearer <Token> 标头发送令牌，最好在 TLS 后使用。
• 即使在 localhost 上也一样： 未提供令牌时，Host 标头会被限制为 localhost 名称，以防任意网页通过 DNS 重绑定访问该端点。在反向代理后使用时，请设置 MCP_ALLOWED_HOSTS。
• **在反向代理后使用时，**最好在代理中将 Host 标头固定为内部上游名称，并将该名称准确填入 MCP_ALLOWED_HOSTS。这样检查就不会依赖公开域名，也能在域名变更后继续正常工作。（感谢 @WinFuture23 提供建议。）
• 如果设置了 MCP_ALLOWED_HOSTS，且你的平台使用 HTTP 健康检查，则必须将其主机名加入列表。 Railway 会发送 Host: healthcheck.railway.app；Kubernetes 探针则会根据配置通过容器 IP 发起请求。如果缺少该名称，健康检查会收到 403，平台会将部署判定为故障。
• **/health 位于 Host 检查之后，**但在令牌检查之前：平台的健康检查无需令牌。此外，/health 始终接受 localhost、127.0.0.1 和 [::1]，以便设置 MCP_ALLOWED_HOSTS 为公开域名时，随附 Dockerfile 中的 HEALTHCHECK 仍能正常运行。但如果健康检查通过容器 IP 或服务名称发起请求，则必须将该名称加入 MCP_ALLOWED_HOSTS。
• 每次工具调用使用的 api_key 默认已禁用（设置 BB_ALLOW_API_KEY_OVERRIDE=1 可启用），以防模型自行决定要向哪个租户写入数据。

完整的安全政策和漏洞报告流程请参阅 SECURITY.md。

致谢与许可证

一个非官方的社区集成，适用于 BuchhaltungsButler；与 BuchhaltungsButler 无关联，也未获得其支持。基于 Model Context Protocol。采用 MIT 许可证发布。