BuchPilot MCP – sevDesk & Lexoffice for n8n/AI

BuchPilot MCP 服务

面向 DACH 会计的 MCP 服务——可直接通过 Claude、Cursor 或任何兼容 MCP 的客户端管理联系人、发票、凭证和报价。

这是什么？

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

功能

• 15 个工具，实现全面的会计自动化
• 联系人：创建、获取、列出、更新
• 发票：创建、获取、列出、更新、下载 PDF
• 凭证：创建、获取、列出（供应商发票、贷项通知单）
• 报价：创建、获取
• 逾期发票：显示金额和逾期天数
• 后端架构——目前支持 Lexoffice，可扩展支持 sevDesk、Billomat 等
• 支持插件——可集成电子发票 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：

1. 环境变量 BUCHPILOT_CONFIG 指定的路径
2. ~/.buchpilot.json（主目录）
3. ./.buchpilot.json（当前目录）

.buchpilot.json 的内容

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

创建 Lexoffice API 密钥

1. 前往 Lexoffice Public API
2. 点击 创建 API 密钥
3. 复制密钥并将其填入 .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 创建一个联系人，电子邮箱为 [email protected]”
• “显示所有未结清的发票”
• “为联系人 XYZ 创建一张发票：10 小时咨询服务，每小时 150 EUR”
• “哪些发票已经逾期？”
• “下载发票 ABC 的 PDF”
• “创建一份报价：5 个许可证，每个每月 49 EUR”

工具参考

所有 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	获取逾期发票及其分析

电子发票集成

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