mcp-buchhaltungsbutler

德语 | 英文

一个 MCP（Model Context Protocol）服务器，将 BuchhaltungsButler API（v1）——一款德国簿记/会计 SaaS——以一组精选、token 高效的工具形式提供给 LLM 智能体。

非官方社区项目。与 BuchhaltungsButler 无关联，也未经其认可。

为智能体而构建，而非仅仅封装 API

• 覆盖全部 48 个端点的 30 个工具 —— 同一操作的批量、列表和单个变体被合并为一个工具，这样你的上下文窗口就不会塞满几乎重复的工具定义。

• 默认精简 —— 列表工具开箱即返回经过裁剪、对 LLM 友好的字段；需要完整记录时传入 full: true 即可。

• 无需摆弄数组 —— 发票行项目、过账拆分和其他 API 特殊之处都以简洁的普通对象形式暴露。不必再手动保持五个并行数组同步。

• 始终与规范保持同步 —— 端点定义直接从 BuchhaltungsButler 官方 API 规范生成，而非手工维护。

Related MCP server: Cuéntica MCP

设置

1. npm install

2. 将 .env.example 复制为 .env，并填写 BB_API_CLIENT、BB_API_SECRET、BB_API_KEY（BuchhaltungsButler → 设置 → API）。

3. npm test —— 针对模拟的 HTTP 响应运行，无需真实凭据。

4. npm run build && npm start —— 或者使用 npm run dev 快速本地运行，无需先行构建。

npm run generate 会根据仓库内置的规范（spec/buchhaltungsbutler-v1.json）重新生成 src/bb-client/generated/endpoints.ts；该输出已提交到仓库，因此仅在更新规范文件本身后才需要运行。

配合 MCP 客户端使用

.env 仅适用于本地 npm run dev/npm start 运行。实际的 MCP 客户端（例如 Claude Desktop）会自行启动服务器，而不会读取 .env —— 请改为通过客户端自身的 env 配置传递凭据。例如 claude_desktop_config.json 条目：

{
  "mcpServers": {
    "buchhaltungsbutler": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-buchhaltungsbutler/dist/index.js"],
      "env": {
        "BB_API_CLIENT": "your-api-client",
        "BB_API_SECRET": "your-api-secret",
        "BB_API_KEY": "your-customer-api-key"
      }
    }
  }
}

请先运行 npm run build，确保存在 dist/index.js。

工具

架构

src/
  config.ts              # env var loading, fail-fast validation
  bb-client/
    generated/            # spec-derived endpoint metadata (regenerate with npm run generate)
    client.ts              # generic HTTP client: auth, api_key injection, error mapping
  formatting/trim.ts       # trims list responses to LLM-friendly fields
  tools/                   # one file per category, curated MCP tools on top of the client
  server.ts, index.ts      # MCP server bootstrap (stdio)
scripts/generate-client.ts # parses spec/buchhaltungsbutler-v1.json into src/bb-client/generated/

单租户，仅支持本地 stdio 传输 —— 无远程托管、无多租户支持、无 OAuth。凭据永远不会到达模型；它们由客户端层从环境变量注入到请求中。

状态

上述 30 个工具覆盖了 BuchhaltungsButler 的全部 48 个端点，并已针对模拟的 HTTP 响应进行测试。尚未在真实账户上验证 —— 如果你遇到意外错误，尤其是在四个以 *_id_by_customer 为后缀的端点（get_receipt、set_receipt_deleted、get_transaction）上，或者在使用成本位置混合存在（部分有、部分无）的批次调用 add_receipt_postings/add_transaction_postings 时，请提交 issue。

开发

git clone https://github.com/si0nDE/mcp-buchhaltungsbutler.git && cd mcp-buchhaltungsbutler
npm install
npm test           # vitest run
npm run build       # tsc, strict mode