billy-mcp

billy-mcp — 面向 Claude 和 AI 助手的 Billy（billy.dk）MCP 服务

将 Claude、Cursor、VS Code 以及任何兼容 MCP 的 AI 助手连接到 Billy——丹麦的会计平台（billysbilling）。 创建发票、登记日记账分录、查看账户余额、核对银行流水并附上收据——内置人工审批写入保护，确保 AI 未经你批准绝不记账。

Billy 会计 · Billy.dk API · 丹麦簿记（bogføring/regnskab）· AI 簿记 Agent · Model Context Protocol 服务 · Claude Desktop 集成

它能做什么？

你可以向 AI 助手提出这类请求：

• “为 Acme ApS 创建一张发票：10 小时咨询服务，单价 1.200 DKK，14 天后到期”
• “本季度账户 5211 的余额是多少？”（根据实时入账记录生成试算平衡表）
• “把上个月的工资登记为日记账分录——先草拟，我来批准”
• “作废这 34 条重复分录”（一次调用、一次审批，并提供逐项结果）
• “上传这份收据 PDF，并将其附加到日记账分录 #67”
• “哪些发票已逾期且未付款？”

40 个工具，涵盖发票、供应商账单、联系人、产品、银行付款、手工日记账分录（日记账交易）、入账记录、试算平衡表、银行对账、文件附件、沙盒批量脚本工具，以及可处理其他所有需求的原始 API 接口。

快速开始

1. 获取 Billy 访问令牌

登录 mit.billy.dk → Settings → Access tokens → Create access token。令牌按公司区分，且不会过期。

2. 添加到 MCP 客户端

Claude Desktop（claude_desktop_config.json）/ Cursor / 任意采用 JSON 配置的宿主：

{
  "mcpServers": {
    "billy": {
      "command": "npx",
      "args": ["-y", "billy-mcp"],
      "env": {
        "BILLY_ACCESS_TOKEN": "<your token>"
      }
    }
  }
}

Claude Code（CLI）：

claude mcp add billy -e BILLY_ACCESS_TOKEN=<your token> -- npx -y billy-mcp

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "billy": {
      "command": "npx",
      "args": ["-y", "billy-mcp"],
      "env": { "BILLY_ACCESS_TOKEN": "${input:billy-token}" }
    }
  }
}

完成——无需克隆或构建。npx 会获取已发布的软件包。

从源码运行（开发）

git clone https://github.com/thourum/billy-mcp.git
cd billy-mcp
npm install
cp .env.example .env      # paste your token
npm run dev               # run over stdio
npm run inspector         # try tools in the MCP Inspector UI

写入保护——保障真实财务数据安全

每项写入操作（创建/更新/批准/作废/付款/上传）均受 BILLY_WRITE_MODE 控制：

模式	行为
read-only	完全不注册写入工具；原始请求会拒绝非 GET 请求
confirm （默认）	每项写入操作都会暂停，并显示包含完整负载的原生审批对话框（MCP elicitation），由你确认——AI 无法批准自己的写入操作
full	写入操作无需审批即可执行

默认拒绝：如果你的 MCP 宿主不支持 elicitation 对话框，confirm 模式会阻止写入并显示说明，而不是执行操作。批准发票、作废分录、银行付款等不可逆操作还会标记为 destructiveHint，以便宿主添加自己的防护措施。拒绝、关闭对话框或不勾选复选框，都不会记入任何账目。

环境变量

变量	必填	描述
BILLY_ACCESS_TOKEN	是	Billy API 访问令牌（通过 X-Access-Token 发送）
BILLY_WRITE_MODE	否	read-only、confirm（默认）或 full
BILLY_ORGANIZATION_ID	否	当令牌对应一家公司的账号时，会自动解析
BILLY_BASE_URL	否	默认为 https://api.billysbilling.com/v2
BILLY_LOCALE	否	en_US、da_DK、fr_FR、nl_NL、de_DE

工具

完整工具列表（40 个）

组织与联系人 — get_organization、list_contacts、get_contact、create_contact、update_contact、list_contact_persons、create_contact_person

产品 — list_products、get_product、create_product、update_product

发票 — list_invoices、get_invoice、create_invoice（嵌入明细行，可设为草稿或立即批准）、approve_invoice、delete_invoice

账单（费用） — list_bills、get_bill、create_bill

付款 — create_bank_payment（将发票/账单标记为已付款）、list_bank_payments、list_balance_modifiers

日记账分录（流水账） — create_daybook_transaction（客户端借/贷余额验证 + 支持通过幂等键安全重试）、void_daybook_transaction、batch_void_daybook_transactions（N 笔作废，一次批准）、list_daybook_transactions、list_daybooks

报告与对账 — get_account_balances（根据记账记录提供试算平衡表/各账户余额）、list_postings、list_transactions、list_accounts、get_account、list_bank_lines、list_bank_line_matches

文件与附件 — upload_file（pdf/jpg/png/gif）、attach_file（关联至发票/账单/日记账分录）、list_files、list_attachments

强大工具 — execute_script（沙盒化 JS 批处理运行器，服务端强制执行变更日志并支持 dry_run）、billy_raw_request（任意 Billy v2 端点）

专为大模型 Agent 打造，而不只是面向人类

• 默认返回紧凑响应（减少约 90% 的令牌）；传入 verbose: true 可获取完整载荷
• appliedFilters 透明度：Billy 会静默忽略未知查询参数 — 每个列表工具都会报告哪些筛选条件由服务端执行、哪些由客户端执行，因此 Agent 不会把“筛选条件被忽略”误认为“没有结果”
• 预先验证：不平衡的日记账分录会在客户端被拒绝，并提供按币种统计的借方/贷方总额，之后才会请求批准
• 幂等重试：日记账分录上的 idempotencyKey 可在超时后安全去重
• 一次批准即可批量处理：execute_script 可运行循环（例如作废 34 笔交易）；即使脚本中途失败，也会返回完整审计日志

常见问题

这是官方的 Billy 集成吗？ 不是 — 这是使用 Billy 公共 REST API v2 的社区项目。

它适用于 Billy 免费套餐吗？ 是的，任何能在 mit.billy.dk 创建访问令牌的账户都可以使用。

AI 能用我的钱付款吗？ 在默认的 confirm 模式下，不会有任何写入操作，除非你在模型无法操作的对话框中点击批准。纯分析场景请使用 read-only。

支持哪些 AI 应用？ 任何通过 stdio 使用 Model Context Protocol 的应用：Claude Desktop、Claude Code、Cursor、Windsurf、VS Code（GitHub Copilot）、Zed 等。

开发

npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run inspector   # interactive tool testing

技术栈：TypeScript、MCP TypeScript SDK v2、Zod v4 schemas。Billy API 参考文档镜像位于 docs/billy-api.md。

许可证

MIT

---

关键词：Billy MCP 服务、billy.dk API、billysbilling 集成、丹麦会计 AI、簿记自动化、财务 AI、Claude 会计、MCP 会计服务、丹麦 AI 簿记、开票 API。