内容
# 比利特 MCP 服务器
[](https://github.com/eltyBelgium/billit-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://github.com/sponsors/eltyBelgium)
一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于 [比利特](https://www.billit.be/) — 比利时电子发票和 Peppol 平台。
让 Claude、Gemini 或 ChatGPT 通过简单的语言创建和发送发票、管理客户、查找 Peppol 参与者以及处理传入文档。
```
"为 Acme BV 创建发票：3 天咨询服务，每日 €650，30 天后到期。
然后通过 Peppol 发送。"
```
TypeScript，一个代码库，两种运行方式：
- **Cloudflare Worker** — 一个远程的 Streamable-HTTP 端点，位于 `/mcp`，适用于 claude.ai、ChatGPT 和 OpenAI/Anthropic API。无状态；在一分钟内部署到免费层。
- **stdio** — 一个适用于 Claude Desktop、Claude Code 和 Gemini CLI 的本地进程。
## ⚡ 一键部署
[](https://deploy.workers.cloudflare.com/?url=https://github.com/eltyBelgium/billit-mcp)
这将 Worker 部署到 **您的** Cloudflare 账户。部署完成后，添加您的比利特凭证：
```bash
npx wrangler secret put BILLIT_API_KEY # 从 my.sandbox.billit.be → 我的个人资料
npx wrangler secret put BILLIT_PARTY_ID
```
您的 MCP 端点：`https://billit-mcp.<您的子域名>.workers.dev/mcp` —
`GET /` 显示健康/配置状态。
## 功能
- **34 种工具**，涵盖比利特的全部功能：
| 领域 | 工具 |
|---|---|
| 订单 | 列出 · 获取 · 创建发票 / 信用凭证 / 报价 · 更新 · 删除 · 发送（电子邮件/Peppol/信件/SDI/…）· 记录付款 |
| 参与者 | 列出 · 获取 · 按增值税查找 · 创建/更新 · 更新 |
| 产品 | 列出 · 获取 · 按 SKU 更新 |
| 文档和文件 | 列出 · 获取 · 上传 · 下载（base64） |
| Peppol | 参与者查找（无需身份验证！）· 收件箱列表/接受/拒绝 · 注册 |
| 传入 OCR | 提交供应商 PDF · 列出队列 |
| 报告和账户 | 列出/获取报告 · 账户信息 |
| ChatGPT 兼容 | `搜索` + `获取`，使用 Apps SDK / Deep Research 形状 |
- **默认沙盒** — 生产环境需要明确选择（ `--allow-production` / `BILLIT_ALLOW_PRODUCTION=true` 本地；Worker 上进行刻意配置）。
- **幂等写入** — 每个创建/发送调用都带有 `Idempotent-Key`，因此重试永远不会重复发票。
- **工具注释** — 读取标记为只读，删除为破坏性，以便客户端安全批准并在写入时提示。
## 获取比利特凭证
1. 注册一个 **沙盒** 账户： [my.sandbox.billit.be/Account/Register](https://my.sandbox.billit.be/Account/Register) （需要有效的增值税号码 + 电子邮件）。
2. 登录 → **我的个人资料** → 复制您的 `ApiKey` 和 `PartyID`。
3. 生产凭证来自 [my.billit.be](https://my.billit.be) — 它们 **独立** 于沙盒。首先在沙盒中练习：生产调用创建真实发票。
> [!IMPORTANT]
> 比利特的条款允许 **个人、非商业使用** 的 API 密钥身份验证。
> 如果您为其他用户分发或托管此服务，比利特需要 OAuth —
> 请发送电子邮件至 `support@billit.eu` 获取客户端 ID/密钥。参见
> [`docs/GUIDE.md`](docs/GUIDE.md)。
## 连接您的 AI 客户端
完整的演练和故障排除指南位于 [`docs/GUIDE.md`](docs/GUIDE.md)。
简要版本：
### claude.ai / Claude Desktop（远程连接器）
设置 → **连接器** → **添加自定义连接器** →
`https://billit-mcp.<您的子域名>.workers.dev/mcp`
### Claude Desktop（一键 DXT，本地）
从
[最新版本](https://github.com/eltyBelgium/billit-mcp/releases/latest) 下载 `billit-mcp.dxt` 并
双击 — Claude Desktop 在表单中提示您输入凭证。该
软件包是自包含的：无需安装其他内容。
### Claude Code
```bash
# 远程（Worker）：
claude mcp add --transport http billit https://billit-mcp.<您的子域名>.workers.dev/mcp
# 或本地（stdio），在 `npm install && npm run build` 之后：
claude mcp add --transport stdio \
--env BILLIT_API_KEY=sk_... --env BILLIT_PARTY_ID=12345 \
billit -- node /path/to/billit-mcp/dist/stdio.js
```
### Gemini CLI
`~/.gemini/settings.json`:
```json
{
"mcpServers": {
"billit": {
"httpUrl": "https://billit-mcp.<您的子域名>.workers.dev/mcp"
}
}
}
```
（或带有 `command: "node"`、`args: [".../dist/stdio.js"]` 和
`env` 块的 stdio 条目。服务器名称不得包含下划线。）
### ChatGPT（开发者模式）
设置 → **应用和连接器** → 启用 **开发者模式** → 添加自定义
连接器，网址为您的 Worker URL。该服务器提供 ChatGPT
期望的 Deep Research 的 `search`/`fetch` 工具对。
### OpenAI 响应 API / Anthropic 消息 API
```js
// OpenAI
tools: [{ type: "mcp", server_label: "billit",
server_url: "https://billit-mcp.<子域名>.workers.dev/mcp",
require_approval: "never" }]
// Anthropic（header: anthropic-beta: mcp-client-2025-11-20）
mcp_servers: [{ type: "url", name: "billit",
url: "https://billit-mcp.<子域名>.workers.dev/mcp" }]
```
## 部署和发布您自己的实例
### 手动部署
```bash
npm install
npx wrangler login
npm run deploy # → https://billit-mcp.<您的子域名>.workers.dev
npx wrangler secret put BILLIT_API_KEY
npx wrangler secret put BILLIT_PARTY_ID
```
### 从 GitHub 持续部署
复刻此仓库，然后添加两个仓库秘密
（设置 → 机密和变量 → 操作）：
- `CLOUDFLARE_API_TOKEN` — [在此处创建](https://dash.cloudflare.com/profile/api-tokens)
，使用 *编辑 Cloudflare Worker* 模板
- `CLOUDFLARE_ACCOUNT_ID` — 在 Workers 仪表板上显示
`main` 的每个推送都会自动部署
（[工作流](.github/workflows/deploy-worker.yml)）。如果没有机密，
工作流会干净地跳过，因此普通的复刻保持绿色。
### 保护公共端点
未经身份验证的 Worker 会将 **您的** 比利特账户暴露给任何拥有
URL 的人。可接受用于沙盒实验；**不适用于生产**。
#### 推荐：Cloudflare Access（Zero Trust）
将 Worker's 主机名放在 [Cloudflare Access](https://one.dash.cloudflare.com)
（免费适用于最多 50 个用户）后面。未经身份验证的请求会收到 302
跳转到您的 Access 登录页面，然后才到达 Worker — 无需代码更改。
无头 MCP 客户端使用 Access **服务令牌** 进行身份验证：
1. Zero Trust 仪表板 → **Access → 服务身份验证 → 服务令牌 →
创建服务令牌**。复制 Client ID + Secret（显示一次）。
2. 编辑适用于 Worker 主机名的 Access 应用程序 → **添加策略**
，操作为 **服务身份验证** （不是 *允许*）→ 包括 → **服务令牌**。
3. 客户端在每个请求上发送两个标头：
```bash
# Claude Code
claude mcp add --transport http billit https://billit-mcp.<子域名>.workers.dev/mcp \
--header "CF-Access-Client-Id: <CLIENT_ID>.access" \
--header "CF-Access-Client-Secret: <CLIENT_SECRET>"
```
相同的标头适用于 Gemini CLI（`"headers": {...}`）、OpenAI
响应 API 和 Anthropic 消息 API。
> [!NOTE]
> claude.ai 的连接器 UI 无法发送自定义标头。要在受 Access
> 保护的服务器上使用 claude.ai，您需要 OAuth 路由：Worker
> 实现 MCP 的 OAuth 流，Access 作为 OIDC 身份提供者
> （Cloudflare 的 [`workers-oauth-provider`](https://github.com/cloudflare/workers-oauth-provider)
> + [适用于 SaaS 的 Access](https://developers.cloudflare.com/cloudflare-one/access-controls/ai-controls/secure-mcp-servers/))。
> 用户然后通过您的 Access 页面登录，然后添加连接器。
#### 替代：共享的 bearer token（无 Access）
```bash
openssl rand -hex 32 | npx wrangler secret put MCP_AUTH_TOKEN
```
Worker 然后在 `/mcp` 上需要 `Authorization: Bearer <token>` —
由 Claude Code `--header`、ChatGPT 的 API-key 连接器身份验证和
两个供应商 API 支持，但不受 claude.ai 的连接器 UI 支持。如果您使用
Access，这将是多余的。
## 开发
```bash
npm install
npx tsc --noEmit # 类型检查
npm run build && npm run smoke # 构建 stdio + MCP 握手测试
npm run inspect # MCP 检查器，用于 stdio 服务器
cp .dev.vars.example .dev.vars && npm run dev # 本地 Worker，位于 :8787/mcp
```
## 仓库布局
```
├── src/
│ ├── config.ts # 环境变量 → 配置，沙盒默认值，凭证检查
│ ├── errors.ts # BillitError + 状态→提示映射
│ ├── client.ts # 获取客户端：重试，Idempotent-Key，分页
│ ├── server.ts # buildServer(): McpServer + 所有工具模块
│ ├── stdio.ts # 本地入口点（Claude/Gemini）
│ ├── worker.ts # Cloudflare Worker 入口点（/mcp）
│ └── tools/ # 订单 · 参与者 · 产品 · 文档 · peppol
│ # 杂项（报告/收件箱/账户）· 搜索获取
├── wrangler.jsonc # Worker 配置（无状态 — 无持久对象）
├── dxt/ # Claude Desktop 一键式软件包资产
├── docs/ # GUIDE.md（每个客户端设置）· tools.md（参考）
├── scripts/smoke.mjs # CI 握手测试
└── .github/workflows/ # CI · Worker 部署 · DXT 发布
```
## 有用的链接
- [比利特 API 文档](https://docs.billit.be/) · [Swagger](https://api.billit.be/swagger/ui/index)
- [模型上下文协议](https://modelcontextprotocol.io)
- [Cloudflare 代理 SDK — MCP](https://developers.cloudflare.com/agents/model-context-protocol/)
## 支持该项目
如果此服务器为您节省了时间，请考虑
[**在 GitHub 上赞助**](https://github.com/sponsors/eltyBelgium) ❤ —
赞助资金用于维护、比利特 API 变更跟踪和新工具。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。与比利特 NV 无关；"比利特" 是其所有者的商标。自担风险 — 始终在触及生产环境之前在沙盒环境中验证。
