内容
# 比利-MCP服务器 - 比利（billy.dk）MCP服务器，用于Claude和AI助手
**连接Claude、Cursor、VS Code和任何与MCP兼容的AI助手到[比利](https://www.billy.dk/) - 丹麦会计平台（billysbilling）。** 创建发票、记录日记账分录、查看账户余额、核对银行交易记录和附件收据 - 内置人工审批保护，确保AI在未获得您批准的情况下不会进行任何操作。
[](https://www.npmjs.com/package/billy-mcp)
[](LICENSE)
[](https://modelcontextprotocol.io)
> 比利会计 · 比利.dk API · 丹麦记账（bogføring/regnskab）· AI记账代理 · 模型上下文协议服务器 · Claude桌面集成
## 它能做什么？
询问您的AI助手：
- *"为Acme ApS创建发票：10小时咨询服务，费用为1200 DKK，14天后到期"*
- *"这个季度的账户5211的余额是多少？"* （来自实时记账的试算表）
- *"将上个月的工资作为日记账分录 - 草拟，我会审批"*
- *"取消这34个重复条目"* （一个调用，一个审批，每个项目的结果）
- *"上传这个收据PDF并将其附加到日记账分录#67"*
- *"哪些发票已过期且未支付？"*
**40种工具** 涵盖发票、供应商账单、联系人、产品、银行付款、手动日记账分录（日记账交易）、记账、试算表、银行对账、文件附件、沙盒批量脚本工具和原始API逃生通道。
## 快速入门
### 1. 获取比利访问令牌
登录 [mit.billy.dk](https://mit.billy.dk/) → **设置 → 访问令牌 → 创建访问令牌**。令牌是每个公司独有的，不会过期。
### 2. 添加到您的MCP客户端
**Claude桌面** (`claude_desktop_config.json`) / **Cursor** / 任何JSON配置主机：
```json
{
"mcpServers": {
"billy": {
"command": "npx",
"args": ["-y", "billy-mcp"],
"env": {
"BILLY_ACCESS_TOKEN": "<您的令牌>"
}
}
}
}
```
**Claude代码** （CLI）：
```sh
claude mcp add billy -e BILLY_ACCESS_TOKEN=<您的令牌> -- npx -y billy-mcp
```
**VS Code** (`.vscode/mcp.json`)：
```json
{
"servers": {
"billy": {
"command": "npx",
"args": ["-y", "billy-mcp"],
"env": { "BILLY_ACCESS_TOKEN": "${input:billy-token}" }
}
}
}
```
就这样 - 无需克隆，无需构建。`npx` 会获取已发布的软件包。
### 从源代码（开发）
```sh
git clone https://github.com/thourum/billy-mcp.git
cd billy-mcp
npm install
cp .env.example .env # 粘贴您的令牌
npm run dev # 通过stdio运行
npm run inspector # 在MCP Inspector UI中尝试工具
```
## 写保护 - 对真实财务数据安全
每次写入（创建/更新/审批/取消/支付/上传）都由 `BILLY_WRITE_MODE` 控制：
| 模式 | 行为 |
| --- | --- |
| `read-only` | 不注册写入工具；原始请求拒绝非GET |
| `confirm` **（默认）** | 每个写入都暂停并显示 **您** 的原生审批对话框（MCP询问）以及完整的有效载荷 - AI无法审批自己的写入 |
| `full` | 写入在无需审批的情况下执行 |
关闭失败：如果您的MCP主机不支持询问对话框，`confirm` 模式 **阻止写入** 并附带说明，而不是执行它们。不可逆操作（审批发票、取消分录、银行付款）额外标记为 `destructiveHint`，以便主机添加自己的防护措施。拒绝、关闭或未勾选复选框 = 不会记账。
## 环境变量
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `BILLY_ACCESS_TOKEN` | 是 | 比利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` |
## 工具
<details>
<summary><b>完整工具列表（40个）</b></summary>
**组织和联系人** — `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` （任意比利v2端点）
</details>
### 为LLM代理而构建，而不仅仅是人类
- **默认情况下响应紧凑** （~90%较少的令牌）；传递 `verbose: true` 以获取完整有效载荷
- **`appliedFilters` 透明度**：比利静默忽略未知的查询参数 - 每个列表工具报告哪些过滤器在服务器端与客户端运行，以便代理永远不会将“过滤器忽略”误认为是“无结果”
- **飞行前验证**：不平衡的日记账分录在请求审批之前在客户端被拒绝，带有每种货币的借贷总额
- **幂等重试**：日记账分录上的 `idempotencyKey` 在超时后安全地重复
- **批量审批**：`execute_script` 运行循环（例如34个取消操作）并返回完整的审计日志，即使脚本在运行中途失败
## 常见问题
**这是官方比利集成吗？** 否 - 社区项目使用比利的公共REST API v2。
**它适用于比利的免费计划吗？** 是的，任何可以在mit.billy.dk创建访问令牌的账户。
**AI会花费我的钱吗？** 在默认的`confirm`模式下，在模型无法触及的对话框中点击审批后，不会发生任何写入操作。 使用`read-only`进行纯分析会话。
**支持哪些AI应用？** 任何通过stdio的Model Context Protocol：Claude Desktop，Claude Code，Cursor，Windsurf，VS Code（GitHub Copilot），Zed等。
## 开发
```sh
npm run typecheck # tsc --noEmit
npm run build # 编译到dist/
npm run inspector # 交互式工具测试
```
技术栈：TypeScript，[MCP TypeScript SDK v2](https://ts.sdk.modelcontextprotocol.io/v2/)，Zod v4模式。比利API参考文档镜像在[`docs/billy-api.md`](docs/billy-api.md)。
## 许可证
[MIT](LICENSE)
---
*关键词：比利MCP服务器，billy.dk API，billysbilling集成，丹麦会计AI，记账自动化，会计AI，Claude会计，MCP会计服务器，AI记账丹麦，发票API。*
