BuchPilot MCP 服务器

用于 DACH 地区会计的 MCP 服务器 — 直接从 Claude、Cursor 或任何兼容 MCP 的客户端管理联系人、发票、凭证和报价单。

npm version License: MIT

这是什么？

BuchPilot MCP 是一个 Model Context Protocol 服务器，它将你的会计系统（目前为 Lexoffice）与 AI 助手连接起来。你可以通过自然语言创建发票、管理联系人并检查逾期付款 — 直接在 Claude Desktop、Cursor 或任何其他 MCP 客户端中操作。

功能特性

15 个工具，实现完整的会计自动化
联系人：创建、获取、列出、更新
发票：创建、获取、列出、更新、下载 PDF
凭证：创建、获取、列出（进项发票、贷记单）
报价单：创建、获取
逾期发票：查看逾期金额和逾期天数
后端架构 — 目前支持 Lexoffice，可扩展至 sevDesk、Billomat 等
插件化 — 可集成 E-Invoice MCP 工具 (einvoice-mcp)
无数据库，无状态 — 纯 API 代理

安装

前提条件

Node.js >= 18
一个带有 API 密钥的 Lexoffice 账户

npm (全局)

npm install -g buchpilot-mcp

从源码安装

git clone https://github.com/makririch/buchpilot-mcp.git
cd buchpilot-mcp
npm install
npm run build

配置

在以下位置之一创建配置文件 .buchpilot.json：

环境变量 BUCHPILOT_CONFIG 指定的路径
~/.buchpilot.json (用户主目录)
./.buchpilot.json (当前目录)

.buchpilot.json 内容

{
  "backends": {
    "lexoffice": {
      "api_key": "DEIN_LEXOFFICE_API_KEY"
    }
  },
  "default_backend": "lexoffice"
}

创建 Lexoffice API 密钥

前往 Lexoffice 公共 API
点击 创建 API 密钥 (API-Key erstellen)
复制密钥并将其粘贴到 .buchpilot.json 中

安全提示： 切勿将 API 密钥存入 Git。请将 .buchpilot.json 添加到你的 .gitignore 文件中。

使用方法

启动服务器 (独立运行)

# Nach npm install -g:
buchpilot-mcp

# Oder von Source:
npm start

# Entwicklung mit Auto-Reload:
npm run dev

服务器通过 stdio 运行并等待 MCP 消息。

在 Claude Desktop 中使用

详细指南请参阅 Claude Desktop 设置指南。

简要步骤 — 在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "buchpilot": {
      "command": "npx",
      "args": ["-y", "buchpilot-mcp"],
      "env": {
        "BUCHPILOT_CONFIG": "/Users/DEIN_NAME/.buchpilot.json"
      }
    }
  }
}

示例 (在 Claude 中使用自然语言)

配置好服务器后，你可以问 Claude，例如：

“为公司 Beispiel GmbH 创建一个联系人，邮箱为 info@beispiel.de”
“显示所有未结发票”
“给联系人 XYZ 创建一张发票：10 小时咨询服务，每小时 150 欧元”
“哪些发票逾期了？”
“下载发票 ABC 的 PDF”
“为 5 个许可证创建一份报价单，每个 49 欧元/月”

工具参考

所有 15 个工具的完整参考（包括参数、输入示例和输出示例）请参阅 docs/tool-reference.md。

概览

工具	描述
`create_contact`	创建新联系人（个人或公司）
`get_contact`	通过 ID 获取联系人
`list_contacts`	带过滤条件列出联系人
`update_contact`	更新联系人
`create_invoice`	创建带有明细的新发票
`get_invoice`	通过 ID 获取发票
`list_invoices`	列出发票（可按状态过滤）
`get_invoice_pdf`	下载发票 PDF (Base64)
`update_invoice`	更新草稿发票
`create_voucher`	创建新凭证
`get_voucher`	通过 ID 获取凭证
`list_vouchers`	列出凭证
`create_quotation`	创建带有明细的新报价单
`get_quotation`	通过 ID 获取报价单
`get_overdue_invoices`	分析并获取逾期发票

电子发票 (E-Invoice) 集成

BuchPilot MCP 可选集成 E-Invoice MCP 包，以便直接从会计系统中生成 XRechnung 和 ZUGFeRD 格式发票：

// In deinem eigenen MCP-Server:
import { registerEInvoiceTools } from "einvoice-mcp";
registerEInvoiceTools(server);
// Ergebnis: 15 + 4 = 19 Tools

常见问题 / 故障排除

“No .buchpilot.json found”

服务器找不到配置文件。请在你的主目录中创建一个 .buchpilot.json：

echo '{"backends":{"lexoffice":{"api_key":"DEIN_KEY"}},"default_backend":"lexoffice"}' > ~/.buchpilot.json

Lexoffice 返回 “401 Unauthorized”

.dachflow.json 中的 API 密钥是否正确？
密钥是否仍然有效？请在 Lexoffice 公共 API 检查。
API 密钥可能会过期 — 如有必要，请创建一个新的。

“429 Too Many Requests”

Lexoffice 允许每秒最多 2 个请求。如果你连续执行大量操作，请在请求之间稍作等待。

服务器已启动，但 Claude 无法识别工具

检查 claude_desktop_config.json 是否正确。
修改配置后重启 Claude Desktop。
检查日志：~/Library/Logs/Claude/mcp.log (macOS)。

无法更新发票

只有状态为 draft (草稿) 的发票才能更新。已完成的发票是不可更改的。

后端 “sevDesk” 不可用

目前仅支持 Lexoffice 作为后端。sevDesk 支持计划中。你可以使用 n8n 节点 (n8n-nodes-buchpilot) 来处理 sevDesk。

许可证

MIT — 可自由使用，包括商业用途。

作者

MaKri — GitHub

buchpilot-mcp