内容
# ohneben's 记账管家 MCP
[](https://github.com/ohneben/Buchhaltungsbutler-MCP/actions/workflows/ci.yml)
[](https://github.com/ohneben/Buchhaltungsbutler-MCP/actions/workflows/docker-publish.yml)
[](./LICENSE.md)
使用类似 **Claude**, **Cursor** 等 AI 助手或任意 [MCP](https://modelcontextprotocol.io) 客户端管理您的 [记账管家](https://www.buchhaltungsbutler.de/) 记账。
该 [Model Context Protocol](https://modelcontextprotocol.io) 服务器暴露了 **[记账管家 API v1](https://app.buchhaltungsbutler.de/docs/api/v1/)** 的全部 **48 个接口**，所有接口均从官方 OpenAPI 规范自动生成为 MCP 工具。每个工具都经过 **安全分类**（只读 / 写 / 销毁），以便您的助手在调用前了解每个操作的作用。该服务器运行在 **stdio**（Claude Desktop 和其他本地启动器）或 **Streamable HTTP**（在 Docker 中托管）。
## 为什么您需要这个
一些 MCP 服务器只是转发 API。而这个服务器是为 **安全交给 LLM** 和 **易于实际运行** 而构建的：
| 您获得的功能 | 原因 |
| --- | --- |
| **所有 48 个接口自动生成**，涵盖官方规范 | 涵盖所有收据、交易、记账、发票和主数据 — 无需手动挑选或遗漏。 |
| **每个工具都有安全分类** 🟢 / 🟡 / 🔴 | 每个工具描述的顶部都有标识，告诉模型它能做什么 — 获取、创建、更新、恢复或删除 — 在执行前。 |
| **机器可读的 MCP 注释** (`readOnlyHint`, `destructiveHint`) | 遵循注释的主机（包括 Claude）可以自动信任读取并在销毁前要求确认。 |
| **两种传输方式：stdio 和 Streamable HTTP** | 在 Claude Desktop 上本地使用，或运行一个始终在线的服务器，任意数量的 MCP 客户端都可以通过 HTTP 访问。 |
| **Docker + docker-compose，健康检查，自动重启** | 开箱即用的生产环境部署：`docker compose up` 然后保持运行。 |
| **可选的 bearer-token 认证**，在 HTTP 端点 | 在服务器可访问范围超出 localhost 时，添加共享密钥。 |
| **内置速率限制** | 在 BuchhaltungsButler 的 100 请求/客户/分钟上限下自我限制，以免触发限制。 |
| **您的密钥永远不会到达模型** | 凭证存储在服务器的环境中，并在每个请求中注入 — 助手只会看到工具输入和 API 响应。 |
### 比较
在编写本文时，这似乎是唯一专门的 记账管家 MCP 服务器。您也可以将通用的 OpenAPI→MCP 包装器指向规范 — 但这样会失去以下功能：
| 功能 | **此项目** | 通用 OpenAPI→MCP 包装器\* |
| --- | :---: | :---: |
| 所有 48 个 记账管家 接口作为工具 | ✅ | ✅ |
| 每个工具的 🟢 / 🟡 / 🔴 安全分类 + 标识 | ✅ | ❌ |
| `readOnlyHint` / `destructiveHint` MCP 注释 | ✅ | ➖ |
| `$ref` 批量有效载荷解析 + HTML 剥离描述 | ✅ | ➖ |
| 内置速率限制（保持在 BB 的 100/客户/分钟限制内） | ✅ | ❌ |
| `stdio` 传输 | ✅ | ✅ |
| **Streamable-HTTP 传输** | ✅ | ➖ |
| **Docker + docker-compose**，健康检查，自动重启 | ✅ | ❌ |
| **可选的 bearer-token 认证**，在端点上 | ✅ | ❌ |
| 服务器端注入凭证，永不发送到模型 | ✅ | ➖ |
| 许可证 | MIT | 各不相同 |
<sub>\* 通用 OpenAPI→MCP 包装器将任何 Swagger/OpenAPI 规范转换为 MCP 工具。它们可以访问相同的接口，但将每个操作视为相同 — 无安全分类，无部署故事，无针对实时会计数据的防护。 "➖" = 取决于工具 / 不保证。 2026 年 7 月的快照。</sub>
## 您可以使用
连接后，向您的助手提问，例如：
- "列出上个月所有未付款的进账单。"
- "为 ACME GmbH 创建一份草稿发票：10 小时咨询，每小时 120 欧元。"
- "将此银行交易记入记账账户 4400。"
- "上传此 PDF 收据并将其分配给匹配的交易。"
- "显示我的债权人，并添加一个新债权人用于我们的托管提供商。"
工具会自动从官方 API 生成并分为 🟢 只读、🟡 写和 🔴 销毁 — 以便表现良好的主机可以区别对待每个组。
## 工作原理
```
Claude / Cursor / 任意 MCP 客户端 ──MCP──► 此服务器 ──HTTPS──► 记账管家 API (云)
```
服务器解析捆绑的 OpenAPI 规范为 MCP 工具（解析 `$ref` 批量有效载荷并剥离 HTML 描述），为每个工具分配其安全分类，并将您的 Basic-auth 凭证和 `api_key` 注入每个传出的请求。您的凭证存储在服务器的环境中 — 模型永远不会看到或处理它们。
## 要求
- **具有 API 访问权限的 记账管家 账户** — 一个 **API 客户端 + API 密钥**（设置 → API）和一个 **客户 `api_key`**（参见 [获取您的 API 凭证](#获取您的-api-凭证)）。
- **Docker**（适用于以下快速入门的 macOS/Windows） — 或 **Node.js ≥ 18** 以 [从源代码运行](#从源代码运行-stdio-无-docker)。
## 快速入门（Docker）
**1. 添加您的凭证。** 复制示例配置文件并填写：
```bash
cp .env.example .env
# 编辑 .env → 设置 BB_API_CLIENT, BB_API_SECRET, BB_API_KEY
# → 设置 MCP_AUTH_TOKEN 为 localhost 以外的长随机字符串
```
**2. 启动服务器：**
```bash
docker compose up -d --build
```
**3. 确认它正在运行：**
```bash
curl -s http://localhost:3000/health # → {"status":"ok","server":"buchhaltungsbutler-mcp"}
```
**4. 连接您的 MCP 客户端。** 远程端点在 Claude 中作为 **自定义连接器**（设置 → 连接器）添加，或使用 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) 桥接本地。将其添加到您的客户端配置中的 `mcpServers` 下，然后完全退出并重新打开应用程序：
```json
{
"mcpServers": {
"buchhaltungsbutler": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:3000/mcp",
"--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
]
}
}
}
```
（如果您将 `MCP_AUTH_TOKEN` 留空，请删除 `--header` 行。）
### 更喜欢预构建的镜像？
每次推送到 `main` 都会将一个现成的镜像发布到 GitHub 容器注册表，因此您可以完全跳过本地构建：
```bash
docker run -d --name buchhaltungsbutler-mcp -p 3000:3000 --env-file .env \
ghcr.io/ohneben/buchhaltungsbutler-mcp:latest
```
## 获取您的 API 凭证
记账管家 使用两层身份验证（参见 [官方文档](https://app.buchhaltungsbutler.de/docs/api/v1/)）：
1. **HTTP 基本身份验证** — 一个 **API 客户端** + **API 密钥**，您的全局 API 凭证。在 记账管家 下找到或创建它们 **设置 → API**。
2. **`api_key`** — 确定 **哪个客户账户** 请求生效。它位于客户的公司数据设置中。
将所有三个放入 `.env`。服务器在每个请求上注入它们，因此您的助手永远不会看到它们。单个工具调用可以选择传递自己的 `api_key` 以针对不同的客户。
## 配置
所有内容都在 `.env` 中设置（从 `.env.example` 复制）：
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `BB_API_CLIENT` | ✅ | — | API 客户端（基本身份验证用户名） |
| `BB_API_SECRET` | ✅ | — | API 密钥（基本身份验证密码） |
| `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` | HTTP MCP 路由 |
| `MCP_AUTH_TOKEN` | — | _(关闭)_ | 需要 `/mcp` 上的 `Authorization: Bearer <token>` |
| `BB_RATE_LIMIT` | — | `90` | 客户端请求/分钟上限 |
| `BB_BASE_URL` | — | _(来自规范)_ | 覆盖 API 基本 URL |
更改 `.env` 后，使用 `docker compose up -d --force-recreate` 重启。
## 工具安全分类
每个工具的描述以以下标识之一开头，并带有匹配的 [MCP 注释](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations)：
| 标识 | 计数 | `readOnlyHint` | `destructiveHint` | 含义 |
|---|---|---|---|---|
| 🟢 **只读** | 12 | `true` | `false` | 仅获取数据。安全。 |
| 🟡 **写入 · 创建数据** | 22 | `false` | `false` | 创建记录（非幂等 — 可能会重复）。 |
| 🟡 **写入 · 更新数据** | 4 | `false` | `false` | 修改现有主数据。 |
| 🟡 **写入 · 链接/取消链接** | 4 | `false` | `false` | 分配/取消分配收据 ↔ 交易。可逆。 |
| 🟡 **写入 · 恢复状态** | 4 | `false` | `false` | 取消确认记账/恢复收据。可逆。 |
| 🔴 **销毁 · 删除** | 2 | `false` | `true` | 删除记录。确认后。 |
尊重注释的主机（包括 Claude）可以要求 `destructiveHint` 工具的确认，并自动信任 `readOnlyHint` 工具。
> 运行 `npm run list-tools`（无需凭证）即可随时打印完整的目录。
<details>
<summary><strong>🟢 只读（12）</strong></summary>
| 工具 | 接口 |
|---|---|
| `accounts_get` | `POST /accounts/get` |
| `cost_locations_get` | `POST /cost-locations/get` |
| `postings_get` | `POST /postings/get` |
| `receipts_get` | `POST /receipts/get` |
| `receipts_get_id_by_customer` | `POST /receipts/get/id_by_customer` |
| `receipts_assigned_transactions_get` | `POST /receipts/assigned-transactions/get` |
| `transactions_get` | `POST /transactions/get` |
| `transactions_get_id_by_customer` | `POST /transactions/get/id_by_customer` |
| `transactions_assigned_receipts_get` | `POST /transactions/assigned-receipts/get` |
| `settings_get_creditors` | `POST /settings/get/creditors` |
| `settings_get_debtors` | `POST /settings/get/debtors` |
| `settings_get_postingaccounts` | `POST /settings/get/postingaccounts` |
</details>
<details>
<summary><strong>🟡 写入 · 创建数据（22）</strong></summary>
| 工具 | 接口 |
|---|---|
| `accounts_add` | `POST /accounts/add` |
| `comments_add` | `POST /comments/add` |
| `cost_locations_add` | `POST /cost-locations/add` |
| `invoices_create` | `POST /invoices/create` |
| `invoices_create_draft` | `POST /invoices/create/draft` |
| `invoices_create_e_invoice` | `POST /invoices/create/e-invoice` |
| `postings_add_free` | `POST /postings/add/free` |
| `postings_add_receipt` | `POST /postings/add/receipt` |
| `postings_add_transaction` | `POST /postings/add/transaction` |
| `postings_add_batch_free` | `POST /postings/add-batch/free` |
| `postings_add_batch_receipts` | `POST /postings/add-batch/receipts` |
| `postings_add_batch_transactions` | `POST /postings/add-batch/transactions` |
| `receipts_add` | `POST /receipts/add` |
| `receipts_addBatch` | `POST /receipts/addBatch` |
| `receipts_upload` | `POST /receipts/upload` |
| `settings_add_creditor` | `POST /settings/add/creditor` |
| `settings_add_debtor` | `POST /settings/add/debtor` |
| `settings_add_postingaccount` | `POST /settings/add/postingaccount` |
| `settings_add_batch_creditors` | `POST /settings/add-batch/creditors` |
| `settings_add_batch_debtors` | `POST /settings/add-batch/debtors` |
| `transactions_add` | `POST /transactions/add` |
| `transactions_addBatch` | `POST /transactions/addBatch` |
</details>
<details>
<summary><strong>🟡 写入 · 更新（4） · 链接（4） · 恢复（4）</strong></summary>
| 工具 | 接口 | 子类别 |
|---|---|
| `cost_locations_update` | `POST /cost-locations/update` | 更新 |
| `settings_update_creditor` | `POST /settings/update/creditor` | 更新 |
| `settings_update_debtor` | `POST /settings/update/debtor` | 更新 |
| `settings_update_postingaccount` | `POST /settings/update/postingaccount` | 更新 |
| `transactions_assign_receipt` | `POST /transactions/assign/receipt` | 链接 |
| `transactions_assign_batch_receipt` | `POST /transactions/assign-batch/receipt` | 链接 |
| `transactions_unassign_receipt` | `POST /transactions/unassign/receipt` | 链接 |
| `postings_assign_receipt_to_free_posting` | `POST /postings/assign/receipt-to-free-posting` | 链接 |
| `postings_unconfirm_free` | `POST /postings/unconfirm/free` | 恢复 |
| `postings_unconfirm_receipt` | `POST /postings/unconfirm/receipt` | 恢复 |
| `postings_unconfirm_transaction` | `POST /postings/unconfirm/transaction` | 恢复 |
| `receipts_restore_id_by_customer` | `POST /receipts/restore/id_by_customer` | 恢复 |
</details>
<details>
<summary><strong>🔴 销毁 · 删除（2）</strong></summary>
| 工具 | 接口 | 注意 |
|---|---|
| `receipts_delete_id_by_customer` | `POST /receipts/delete/id_by_customer` | 可通过 `receipts_restore_id_by_customer` 恢复 |
| `cost_locations_delete` | `POST /cost-locations/delete` | **不** 可恢复 |
</details>
## 从源代码运行（stdio，无 Docker）
喜欢经典的stdio模式适用于Claude Desktop？本地构建：
```bash
npm install
npm run build`
```
然后将本地编译的入口点指向Claude Desktop中的`claude_desktop_config.json`:
```json
{
"mcpServers": {
"buchhaltungsbutler": {
"command": "node",
"args": ["/ABSOLUTE/PATH/BuchhaltungsButler MCP/dist/index.js"],
"env": {
"MCP_TRANSPORT": "stdio",
"BB_API_CLIENT": "your-api-client",
"BB_API_SECRET": "your-api-secret",
"BB_API_KEY": "your-customer-api-key"
}
}
}
}
```
或者在stdio上运行容器：
```json
{
"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": "your-api-client",
"BB_API_SECRET": "your-api-secret",
"BB_API_KEY": "your-customer-api-key"
}
}
}
}
```
（先构建镜像：`docker build -t buchhaltungsbutler-mcp:latest .`）
## 保持规范最新
捆绑的`spec.json` 是官方的 记账管家 v1 OpenAPI 规范 — 工具的源头。刷新为较新的 API 版本：
```bash
curl -s https://app.buchhaltungsbutler.de/docs/api/v1.de.json -o spec.json
npm run build
```
新路径会自动被拾取；在`src/categories.ts`中的`PATH_CATEGORY`添加它们，以便获得正确的类别（未映射的路径会回落到安全但保守的 *创建* 类别）。
## 开发
```bash
npm install
npm run build # 编译 TypeScript → dist/
npm test # 运行 Vitest 套件
npm run list-tools # 打印分类的工具目录（无需凭证）
```
CI 每次推送都会在 Node 20 和 22 上构建、测试；推送到 `main` 还会将 Docker 镜像发布到 GitHub 容器注册表。
## 注释和约定
- **日期**： `YYYY-MM-DD`。 **金额**： 带有小数点分隔符（例如 `-12.30`）。
- **文件上传** (`receipts_upload`, `receipts_add`, `receipts_addBatch`)： 将文件作为 `file` 字段中的 base64 字符串传递。
- **分页**： 大多数 `get` 工具接受 `limit` 和 `offset`。
- **批量工具** 采用对象数组；项目模式从规范定义中解析并显示给模型。
- **速率限制**： 记账管家 允许 100 请求/客户/分钟；服务器在低于该限制时自我限制至 `BB_RATE_LIMIT`（默认为 90）。
## 安全
您的 API 凭证仅存储在 `.env` 中，该文件被 git 忽略。 **切勿提交真实凭证。** 如果发生泄漏，请在 **记账管家 → 设置 → API** 中轮换它们。
默认情况下，HTTP 端点是未认证的（在 localhost 上运行良好）。要将其公开给您的机器以外的范围，请设置 `MCP_AUTH_TOKEN` 并将其作为 `Authorization: Bearer <token>` 头部发送 — 理想情况下在 TLS 后面。
参见 [SECURITY.md](./SECURITY.md) 以获取完整的安全策略以及如何报告漏洞。
## 致谢与许可
[BuchhaltungsButler](https://www.buchhaltungsbutler.de/) 的非官方社区集成；不隶属于或得到 BuchhaltungsButler 的认可或支持。基于 [Model Context Protocol](https://modelcontextprotocol.io) 构建。 [MIT License](./LICENSE.md) 许可。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器