BeeL

BeeL MCP 服务 — 面向 AI Agent 的 VeriFactu 电子发票

西班牙MCP 电子发票服务，支持 VeriFactu（AEAT）：可直接从 Claude、ChatGPT、Cursor 或 VS Code 创建、开具和更正发票。
符合 VeriFactu 要求的西班牙电子发票 MCP 服务 — 直接从 AI Agent 向 AEAT 开具、更正和登记发票。
beel.es · API 文档 · MCP 指南 · npm

---

这是一个 MCP（Model Context Protocol）服务，可让 AI Agent 开具符合法律规定的西班牙电子发票 — 在 AEAT 登记 VeriFactu 发票， 支持 F1/F2 发票类型、R1–R5 更正发票、依据登记册验证 NIF，以及法规要求的制度代码。 将其连接到 Claude、ChatGPT、Cursor 或 VS Code，你的 Agent 就能端到端处理西班牙开票 — facturación electrónica 和 factura electrónica VeriFactu — 无需你编写任何 API 调用。

它并非围绕 API 自动生成的封装。以下三点让模型能够有效使用它：

• 工具源自公开的 OpenAPI 契约，因此每个工具的输入架构都是真实操作架构 — 包括枚举、 行项目、制度代码等。工具接口不会偏离 API。
• 工具纳入策略决定实际应向 Agent 提供哪些工具。二进制下载、多部分上传、Webhook 配置、只有浏览器会话才能认证的操作，以及已弃用的操作，都会依据规则排除，而非手动处理。
• 工具附带财务合规防护措施：生成式封装容易遗漏的约束条件，既以模型可读取的文档形式提供， 也通过预检阻止不合规请求变成财务单据。

同一套代码库支持两种传输方式：托管的远程服务位于 https://mcp.beel.es/mcp（Streamable HTTP + OAuth — 每位用户只需登录一次，无需安装），以及 基于此代码库构建的本地 stdio 服务，供无头环境使用；在这种环境中，API 密钥可用，而基于浏览器的登录不可用。

快速开始

在 Claude、ChatGPT、Cursor 或 VS Code 中添加 https://mcp.beel.es/mcp 作为连接器， 然后使用你的 BeeL 账户登录。无需安装或管理 API 密钥：服务会使用你自己的凭据运行， OAuth 流程会根据 URL 自动发现。

# Claude Code
claude mcp add --transport http beel https://mcp.beel.es/mcp

交互式使用只需完成这些设置。只有需要本地服务时才继续阅读。

在本地运行

当 OAuth 无法使用时，请使用本地服务：例如开具发票的定时任务、CI 流水线，或任何没有人在场完成浏览器登录的无头进程。 它使用 API 密钥进行身份验证。

需要 Node ≥ 20。

// Claude Desktop / Claude Code MCP config
{
  "mcpServers": {
    "beel": {
      "command": "npx",
      "args": ["-y", "@beel_es/mcp"],
      "env": { "BEEL_API_KEY": "beel_sk_test_xxx" }
    }
  }
}

# Claude Code
claude mcp add beel --env BEEL_API_KEY=beel_sk_test_xxx -- npx -y @beel_es/mcp

以 beel_sk_test_ 为前缀的密钥可安全用于试验；以 beel_sk_live_ 为前缀的密钥会签发真实的 税务单据。

各版本由 CI 通过 npm 可信发布发布，因此带有来源证明：npm 会记录每次构建所对应的确切提交和工作流。使用 npm audit signatures 验证。

每个版本也会在 MCP Registry 中以 es.beel/mcp 发布，列出两种 传输方式，因此浏览注册表的客户端无需被告知地址也能找到该服务。其名称通过 beel.es 上的 DNS 记录进行验证，表明该服务来自我们，而不仅仅是来自某个代码仓库。

此前以 io.github.beel-es/beel-mcp（v0.2.2）发布的条目已在名称迁移时停用。 注册表名称是身份标识，而非标签，因此重命名会创建新条目，而不是重定向；两个条目都指向同一个 npm 包和同一个托管服务。

提供的功能

• 125 个 API 工具，源自 openapi/public-api.yaml，涵盖发票、客户、产品、定期发票、 系列和税务配置、NIF 验证、公司。
• 7 个合成工具，用于 API 没有单一端点的功能：beel_docs_search、 beel_docs_get、beel_docs_list 可查询文档（使用文档站点的搜索 端点；每次获取一个页面的 Markdown，或一次调用获取页面的部分章节；对于 长页面会返回其大纲）；beel_rules_list 和 beel_rules_get 可查询税务规则目录（按 ID、一次查询多个 ID、领域、关键词或错误代码）； beel_schema_get 可从打包的契约中以精简的类 TypeScript 声明形式获取请求和响应模式的字段（按模式名称查询，或按工具名称获取其查询参数、 请求体和返回类型）；以及 beel_get_setup_status，它会按 NIF 报告签发所缺少的所有内容、需要执行的下一步操作，以及集成所需的 ID（公司、 各单据类型的默认系列、VeriFactu 状态和税务默认值）。
• 护栏资源，位于 beel://guardrails/* 下，包括税务规则（每个领域一个资源）、API 使用指南，以及 beel://guardrails/errors，其中列出所有 错误代码及其对应操作。每个工具的说明中都会列出适用于该工具的领域和指南。
• 7 个工作流提示词，为操作顺序决定安全性的流程规定安全顺序：issue-invoice（验证 NIF → 选择 F1/F2 → 检查 VeriFactu 条件 → 签发）、fix-invoice（作废还是更正）、onboard-nif、 setup-representation、invite-member、connect-payments 和 upgrade-integration。
• 内嵌发票 PDF 查看器（MCP Apps）： 生成发票 PDF 后，会在支持此功能的宿主应用中打开侧边面板进行查看。

每个工具及其所需权限范围的完整目录可在 docs.beel.es/mcp/tools 查看（npm run tools:catalog）。

明确不作为工具提供的功能

二进制文件下载（PDF 预览、批量 ZIP、Excel/CSV 导出）、多部分上传（CSV/Holded 导入、已签名 PDF 提交）、Webhook 基础设施、只能通过浏览器会话进行身份验证的操作，以及所有 deprecated 操作。Agent 无法驱动这些功能，而每个功能都会占用可用于实用工具的上下文。相关规则位于 src/policy/tool-policy.ts。

税务护栏

西班牙电子发票有一些仅凭架构无法让 LLM 正确理解的不变量——例如，对本应更正的发票进行作废、在简化发票上使用 R1，或修改 AEAT 已登记的发票。该服务通过三个层面解决这些问题，而它们之间的差异很重要：

1. 建议——有两个来源，特意分开：

• 税务规则是文档网站发布的规则目录，位于 docs.beel.es/api/rules.json：每条规则都包含一个 id（COR-002）、说明、存在原因、法律依据、用于强制执行该规则的错误代码以及示例。该服务在运行时读取这些规则（与其他文档文件一样进行缓存），并通过 beel_rules_list / beel_rules_get 以及每个领域各自的资源（beel://guardrails/corrective，……）提供这些规则。这里不会重新录入任何税务内容。软件包中附带一份规则目录快照，作为文档主机无法访问时的后备；npm run sync:rules 是唯一可写入该快照的命令，如果有人手动编辑，测试就会失败。以前的 beel://guardrails/cancel-vs-rectify、invoice-types 和 regime-keys URI 仍然可用，并会指向取代它们的领域。
• API 使用指南——src/guardrails/rules/*.md——介绍并非税务规则、但仍可能让 Agent 出错的内容：行项目如何填写价格、如何配置系列、操作针对哪家公司、如何解读 NIF 验证和开票就绪状态，以及每项发票操作由哪个工具执行。指南会链接到规则 id，而不会重述规则内容。

每个工具的描述都会列出适用的领域和指南，因此约束会随调用一起传递。

2. 强制校验——src/guardrails/validate.ts，在发送请求前进行检查，因此错误负载甚至不会消耗幂等键：

检查项	代码
每个行项目必须且只能填写一种定价字段	LINE_UNIT_PRICE_XOR_DECLARED_TOTAL
已声明总额不得设置折扣	LINE_DECLARED_TOTAL_FORBIDS_DISCOUNT
简化发票（F2）不得扣缴 IRPF	SIMPLIFICADA_FORBIDS_IRPF
简化发票（F2）的收件人不得填写 nif 或 alternative_id	SIMPLIFIED_INVOICE_FORBIDS_IDENTIFIED_RECIPIENT
只有在制度 18 下才能使用等价附加税，且制度 18 必须使用该税	SURCHARGE_REQUIRES_REGIME / REGIME_REQUIRES_SURCHARGE
系列格式必须能区分其重置周期	SERIES_ANNUAL_REQUIRES_YEAR / SERIES_MONTHLY_REQUIRES_MONTH_AND_YEAR
只能在激活公司时的调用中设置编号初始值	NUMBERING_REQUIRES_ACTIVATION
SUPLIDO 行必须包含其来源引用	在本地检查
只有在原因 OTRO 下才能填写豁免文本	在本地检查
更正发票必须通过专用操作处理，而不是使用 type: CORRECTIVE	在本地检查

3. 说明——BeeL API 已能很好地提供响应：其 message 使用调用方的语言面向人类编写，error.details 包含具体信息，而 RFC 7807 的 type 字段会链接到针对该代码的文档页面。该服务会原样转发所有这些内容，只补充响应无法携带的两项信息：以工具调用形式给出的补救方式——文档面向打开了仪表板的人（“在设置中创建系列”），而 Agent 需要的是 beel_set_default_series——以及重试是否可能奏效，这可以阻止 Agent 在需要管理员处理的 403 错误上反复重试。对于已发布规则中引用的代码，错误还会注明对应规则（id、标题、链接）。src/guardrails/catalog.ts 只收录适用其中一项补充信息的代码；其他代码均直接传递，因为改述不如原文准确，也可能与原文不一致。EMISSION_NOT_READY 中嵌套的 blockers[] 是最明显的例子：它们以不带消息和链接的纯字符串形式返回，而服务返回时会为每项指出可解除它的工具。 BeeL API 是这一切的权威依据。 每条强制规则都对应着契约中记录的一项拒绝，因此预检是 API 拒绝范围的严格子集：它只能让失败更快发生、解释得更清楚，绝不会放行 API 会拒绝的内容。依赖服务端状态的规则——AEAT 名册匹配、3,000 欧元的 F2 上限、某个系列是否存在——会刻意保留为建议规则，因为在本地对此进行猜测可能会错误拒绝有效发票。设置 BEEL_DISABLE_PREFLIGHT=1 即可完全绕过本地检查。

经过人工整理的列表均由测试约束：每个收录的代码都必须仍出现在契约中，每个经过检查的 operationId 都必须仍能解析到真实工具，每个防护措施引用都必须指向现存的防护措施。API 重命名会导致 CI 失败，而不是悄无声息地关闭一项税务检查。

配置

仅限本地服务

变量	用途
BEEL_API_KEY	API 密钥。前缀用于选择环境：beel_sk_test_ → 测试环境，beel_sk_live_ → 正式环境。
BEEL_ENV / BEEL_CONFIG_DIR	可选。未设置 BEEL_API_KEY 时，会回退到 CLI 的 ~/.config/beel/config.json（beel login）；BEEL_ENV（test/live，默认为 test）用于选择已存储的密钥。

通用

变量	用途
BEEL_BASE_URL	API 基础 URL。默认为 https://app.beel.es/api。
BEEL_DOCS_URL	文档和规则工具使用的文档源。默认为 https://docs.beel.es。
BEEL_REQUEST_TIMEOUT_MS	单次 API 调用的硬性超时上限。默认为 30000。
BEEL_DISABLE_PREFLIGHT	设置为 1 可跳过强制防护措施。

所有默认值都位于 src/shared/defaults.ts 中；不会在多个地方重复硬编码。远程部署变量见 DEPLOY.md。

即使没有任何凭据，服务也会启动并列出工具——只有在实际调用 API 工具时才会报错。POST 请求会根据请求本身生成稳定的 Idempotency-Key，因此 Agent 重试“创建发票”时绝不会重复生成发票。

自托管

远程服务运行在 Cloudflare Workers 上。KV 命名空间、BeeL 必须注册的 OAuth 客户端以及相关密钥，请参阅 DEPLOY.md。

开发

npm ci
npm run dev          # stdio server from source
npm test             # vitest
npm run typecheck    # both the Node and the Worker configs
npm run build        # single-file bundle to dist/index.js
npm run inspect      # MCP Inspector against the local build
npm run spec:verify  # the vendored contract still matches its lock
npm run sync:rules   # refresh the bundled rules snapshot from docs.beel.es

openapi/public-api.yaml 是 API 契约的生成副本，openapi/spec.lock.json 则记录其版本、操作数量和哈希值。如果两者不一致，CI 就会失败，从而确保随项目提供的契约始终可信。请参阅 CONTRIBUTING.md。

BeeL 开发者生态的其他部分

以下所有内容均源自同一份 OpenAPI 契约，因此无论在哪里使用，术语——发票类型、制度键、系列、VeriFactu 状态——都保持一致。

REST API	契约本身。其他所有内容都是它的投影
CLI	在终端中使用同样的功能，默认采用沙盒环境
n8n node	在无代码工作流中处理发票
Claude Code plugin	实现、审计和维护 BeeL 集成
Machine-readable docs	面向更愿意阅读而非猜测的 Agent 的 llms.txt

常见问题

BeeL MCP 服务是什么？ 一个 MCP 服务，可将西班牙 VeriFactu 电子发票功能作为 AI Agent 可调用的工具公开出来，让 Claude、ChatGPT、Cursor 或 VS Code 能够代表你创建客户、开具 F1/F2 发票、向 AEAT 登记发票，以及提交 R1–R5 更正发票。

如何将 VeriFactu 开票功能连接到 Claude / ChatGPT / Cursor？ 将 https://mcp.beel.es/mcp 添加为连接器，并使用 BeeL 账号登录——请参阅快速开始。交互式使用无需安装任何内容，也无需粘贴 API 密钥。

它真的符合 VeriFactu 规范吗？ 是的。发票会根据 VeriFactu 规范向 AEAT 登记，编号和系列符合规定，而且财务保护措施会在不合规请求成为财务单据之前予以拦截。

VeriFactu 还是 TicketBAI？ 此服务面向VeriFactu，即 AEAT 的全国性系统。TicketBAI（巴斯克地区制度）不在支持范围内。

不使用 AI Agent 也能用吗？ 可以——这是标准的 MCP 服务，因此任何支持 MCP 的客户端都能使用，同样的开票功能也可通过 REST API、CLI 和 n8n 节点使用。

参与贡献

欢迎提交 Bug 报告和拉取请求——请参阅 CONTRIBUTING.md，了解项目结构以及哪些约定至关重要；有问题请访问讨论区。标记为 good first issue 的问题是不错的入门选择。所有参与者都应遵守行为准则。安全问题请发送至 [email protected]，不要公开提交问题；请参阅 SECURITY.md。

许可证

MIT © BeeL.