BeeL MCP server

这是一个 MCP（Model Context Protocol）服务器，可让 AI 代理开具符合法律要求的西班牙电子发票——包括 AEAT 的 VeriFactu 注册、F1/F2 发票类型、R1–R5 更正发票、对照税务普查数据进行 NIF 校验，以及法规要求的税制键。将其接入 Claude、ChatGPT、Cursor 或 VS Code，你的代理就能端到端处理西班牙发票业务——facturación electrónica 与 factura electrónica VeriFactu——而无需你编写任何 API 调用。

它不是围绕 API 自动生成的包装器。有三点使其可被模型真正使用：

• 工具均派生自公开的 OpenAPI 契约，因此每个工具的输入 schema 就是该操作的的真实 schema——枚举、行项目、制度键等一应俱全。工具表面不会与 API 脱轨。

• 工具包含策略决定代理到底应该获得哪些工具。二进制下载、multipart 上传、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

以上就是交互式使用的全部配置。只有在你需要本地服务器时才继续往下看。

Related MCP server: chile-invoice-mcp

本地运行

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

需要 Node.js ≥ 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_ 则会签发真实的税务文件。

发布版本通过 npm 的 受信任发布 从 CI 进行，因此它们带有来源证明：npm 会记录每个构建所来自的确切提交和工作流。可通过 npm audit signatures 进行验证。

每次发布也会通告给 MCP Registry，名称为 es.beel/mcp，同时列出两种传输方式，这样浏览注册表的客户端无需被显式指定就能发现该服务器。该名称由 beel.es 上的 DNS 记录进行认证，因此它表明该服务器确实来自我们，而不仅仅来自某个存储库。

在 io.github.beel-es/beel-mcp（v0.2.2）下有一个旧条目，已在名称迁移时退役。注册表名称是身份而非标签，因此重命名意味着新增条目，而不是重定向；两个名称都指向同一个 npm 包和同一个托管服务器。

提供的功能

• 118 个 API 工具，派生自 openapi/public-api.yaml——发票、客户、产品、定期 invoice、序列和税务配置、NIF 校验、公司等。

• 4 个 API 没有单一端点的合成工具：对文档执行 beel_docs_search、beel_docs_get、beel_docs_list，以及 beel_get_setup_status——该工具按 NIF 精确报告签发前还缺少什么、以及下一步唯一该做的一件事。

• 护栏资源位于 beel://guardrails/* 下——包含财税不变量，以及 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:get）。

哪些内容刻意不作为工具

二进制下载（PDF 预览、批量 ZIP、Excel/CSV 导出）、multipart 上传（CSV/Holded 导入、签名 PDF 提交）、webhook 基础设施，以及所有 deprecated 操作。它们驱动不了 agent，而且每个操作都会消耗上下文，而这些上下文恰恰是可使用工具所需的。相关规则见 src/policy/tool-policy.ts。

财税护栏

西班牙电子发票存在一些即使只看 schema 也会被 LLM 弄错的不变量——例如把本应更正的发票作废、在简化发票上使用 R1、编辑 AEAT 已注册的发票等等。服务器通过三个层次来应对，并且它们之间的差别很重要：

1. 顾问层 —— src/guardrails/rules/*.md，每个主题一个 Markdown 文件：发票生命周期、作废 vs 发票更正、发票类型、发票行项目、制度键、序列号、NIF 校验、VeriFactu 检查门、多 NIF 账户。每个文件都以 MCP 资源的形式暴露在 beel://guardrails/* 下，且该文件的一句话摘要会被追加到每个其所约束的工具的描述中，这样约束就会随着工具一起传递。

2. 强制层 —— src/guardrails/validate.ts，在请求发出前进行检查，因此一个错误 payload 甚至在幂等键任务都不会消耗：

3. 解释层 —— BeeL API 本身已经提供了良好且可直接使用的响应：其 message 使用调用者语言、面向人类编写，error.details 包含具体细节，RFC 7807 的 type 字段链接到对应错误码（约 357 条）的文档页面。服务器会把这些信息都已不修改地转发，并只额外补充响应中的其他内容无法携带的两项信息：将补救措施作为工具调用来实现——因为文档面向的是已打开后台用户的用户（如在设置中创建序列），而 agent 需要的是 beel_set_default_series——以及重试是否可能有效，这一点可以防止 agent 在需要管理员干预的 403 错误上不断重试。src/guardrails/catalog.ts 只收录上述任何一种适用情形有代码；其他代码完全透传，因为改写只会比原始信息更糟，并与原始信息产生偏移，导致信息不一致。EMISSION_NOT_READY 嵌套的 blockers[] 是最明显的例子：它们以无消息、无链接的纯字符串形式达到，并且每个都会以能清除它的工具名称返回。

BeeL API 对以上所有规则都有最终权威。 每个强制执行的规则都与契约中已记录的拒绝原因对应，因此预检是 API 拒绝行为的严格子集：它只会让失败更快、解释更充分，绝不会允许 API 拒绝的某种操作。那些依赖服务器端状态的规则——AEAT 普查匹配、€3,000 F2 上限、序列是否存在等——刻意保持为能从软件层面解决，因为在本地猜测这类信息会把合法发票误拒绝。设置 BEEL_DISABLE_PREFLIGHT=1 可以完全绕过所有本地检查。

人工维护清单由测试来锚定：每条目录中的错误码都必须仍然出现在契约中，每个被检查的 operationId 都必须还原到一个真实工具上，每个护栏参考都必须指向一个存在的护栏。API 的某个重命名会在 CI 中引起失败，而不是默默关闭某项财务检查。

配置

仅本地服务器

共享

所有默认值都位于 src/shared/defaults.ts；没有任何值被硬编码两次。远程部署变量记录在 DEPLOY.md。

服务器在没有任何凭据的情况下启动并列出工具——它只会在某个 API 工具被实际调用时报错。POST 请求携带一个由请求本身派生的稳定 Idempotency-Key，因此代理重试“创建发票”时绝不会创建出第二张发票。

自托管

远程服务器运行在 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

openapi/public-api.yaml 是 API 契约的生成副本，openapi/spec.lock.json 记录其版本、操作数量和哈希值。CI 会在两者不一致时失败，这正是让这份随仓库维护的契约“不撒谎”的机制。请参阅 CONTRIBUTING.md。

BeeL 开发者生态系统的其余部分

下面的一切都来源于同一个 OpenAPI 契约，因此所遇见的术语——发票类型、制度键、系列、VeriFactu 状态——在每个地方都是一致的。

FAQ

什么是 BeeL MCP 服务器？ 一个 MCP 服务器，将西班牙 VeriFactu 电子发票能力以 API 的形式暴露出来，供 AI 代理调用——因此 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 代理也能使用吗？ 可以——它是一个标准的 MCP 服务器，因此任何支持 MCP 的客户端都能使用；同时，相同的开票能力也可以作为 REST API、CLI 和 n8n 节点 的替代方案。

贡献

欢迎提交 Bug 报告和 Pull Request——项目布局方式以及哪些约定是必须遵守的，请查看 CONTRIBUTING.md。安全问题请发送到 security@beel.es，而不是公开 issue；详见 https://github.com/BeeL-Spain/[SECURITY.md]？——不，原样为 SECURITY.md。

等等，我上面那行出错了。正确的原文链接是 SECURITY.md。修正：

安全问题请发送到 security@beel.es，而不是公开 issue；详见 SECURITY.md。

许可证

MIT © BeeL.