BeeL MCP server

AIエージェントが法的に準拠したスペインの電子請求書を発行できるようにするMCP（Model Context Protocol）サーバーです。AEATへのVeriFactu登録、F1/F2請求書タイプ、R1〜R5訂正、センサスに対するNIF検証、規制で要求される制度キーに対応しています。Claude、ChatGPT、Cursor、VS Codeに接続すれば、エージェントがスペインの請求業務（facturación electrónicaおよびfactura electrónica VeriFactu）をAPI呼び出しを一切書かずにエンドツーエンドで処理できます。

これはAPIを生成したラッパーではありません。モデルが使えるようにしているのは次の3点です：

• ツールは公開OpenAPIコントラクトから導出されているため、各ツールの入力スキーマは実際のオペレーションのスキーマそのものです（列挙型、明細行、制度キーもすべて含む）。サーフェスがAPIから乖離することはありません。

• ツール包含ポリシーが、エージェントに実際に与えるべきものを決定します。バイナリダウンロード、マルチパートアップロード、webhook配線、非推奨オペレーションは、手作業ではなくルールによって除外されます。

• 税務ガードレールがツールに付随します。生成ラッパーが見落とす不変条件を、モデルが読むドキュメントとして、また非準拠リクエストが税務文書になる前に止める事前チェックとして提供します。

1つのコードベースで2つのトランスポートを提供：ホスト型リモートサーバー（https://mcp.beel.es/mcp、Streamable HTTP + OAuth — ユーザーごとに1回のログインで、インストール不要）、およびこのリポジトリから構築したローカルstdioサーバー（ヘッドレス利用向け。APIキーが機能し、ブラウザベースのログインが機能しない環境向け）。

クイックスタート

https://mcp.beel.es/mcp をClaude、ChatGPT、Cursor、VS Codeのコネクタとして追加し、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 ≥ 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のトラステッドパブリッシングを通じて公開されるため、来歴（provenance）が付与されます：npmは各ビルドの正確なコミットとワークフローを記録します。npm audit signaturesで検証できます。

各リリースはMCPレジストリにも**es.beel/mcp**として登録され、両方のトランスポートが掲載されます。レジストリを閲覧するクライアントは、指定されなくてもサーバーを見つけられます。この名前はbeel.es上のDNSレコードで認証されているため、単なるリポジトリ由来ではなく、当社からのサーバーであることが示されます。

以前のio.github.beel-es/beel-mcp（v0.2.2）での登録は、名前が移動した際に廃止されました。レジストリ名はラベルではなくアイデンティティであるため、リネームはリダイレクトではなく新しいエントリになります。両方とも同じnpmパッケージと同じホスト型サーバーを指しています。

提供内容

• 118のAPIツール — openapi/public-api.yamlから導出。請求書、顧客、製品、定期請求書、シリーズと税設定、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（無効化 vs 訂正）、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オペレーション。エージェントはこれらを操作できず、それぞれが使用可能なツールに必要なコンテキストを消費します。ルールはsrc/policy/tool-policy.tsにあります。

税務ガードレール

スペインの電子請求書には、LLMがスキーマだけでは誤る不変条件があります — 訂正すべき請求書の無効化、簡易請求書へのR1の使用、AEATがすでに登録した請求書の編集などです。サーバーはこれを3層で対処しており、その違いが重要です：

1. 助言（Advisory） — src/guardrails/rules/*.md、トピックごとに1つのMarkdownファイル：請求書ライフサイクル、無効化 vs 訂正、請求書タイプ、請求書明細行、制度キー、シリーズ番号、NIF検証、VeriFactuゲート、複数NIFアカウント。各ファイルはbeel://guardrails/*のMCPリソースとして公開され、その1行要約が制約するすべてのツールの説明に追加されるため、制約は呼び出しとともに移動します。

2. 強制（Enforced） — src/guardrails/validate.ts、リクエスト送信前にチェックされるため、不正なペイロードが冪等性キーを消費することすらありません：

3. 説明（Explained） — BeeL APIはすでに適切に応答します：messageは呼び出し元の言語で人間向けに書かれ、error.detailsは詳細を保持し、RFC 7807のtypeフィールドはその正確なコード（約357件）のドキュメントページにリンクします。サーバーはこれらすべてをそのまま中継し、レスポンスが運べない2つのことだけを追加します：ツール呼び出しとしての救済策 — ドキュメントはダッシュボードを開いている人向け（「設定でシリーズを作成」）ですが、エージェントにはbeel_set_default_seriesが必要です — および再試行が役立つ可能性があるかどうか。これは、管理者が必要な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 を保持するため、エージェントが「請求書の作成」を再試行しても、2枚目の請求書が作成されることはありません。

セルフホスティング

リモートサーバーは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 はそのバージョン、操作数、ハッシュを記録しています。この2つが一致しない場合、CIは失敗します。これにより、ベンダー提供の契約が誠実に保たれます。CONTRIBUTING.md を参照してください。

BeeL開発者エコシステムのその他

以下はすべて同じOpenAPI契約から派生しているため、語彙（請求書タイプ、レジームキー、シリーズ、VeriFactu状態）はどこで出会っても同一です。

FAQ

BeeL MCPサーバーとは何ですか？ AIエージェントが呼び出せるツールとしてスペインのVeriFactu電子請求を公開するMCPサーバーです。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か？ このサーバーは国営AEATシステムであるVeriFactuを対象としています。TicketBAI（バスク州のレジーム）は対象外です。

AIエージェントなしで使用できますか？ はい。標準のMCPサーバーであるため、MCP対応クライアントならどれでも動作し、同じ請求サーフェスがREST API、CLI、n8nノードとして利用可能です。

コントリビューション

バグ報告とプルリクエストを歓迎します。プロジェクトの構成と重要な規約については、CONTRIBUTING.md を参照してください。セキュリティの問題は公開イシューではなく security@beel.es に送ってください。SECURITY.md を参照してください。

ライセンス

MIT © BeeL.