BeeL

BeeL MCP サーバー — AI エージェント向け VeriFactu 電子請求書発行

VeriFactu（AEAT）に対応したスペインのMCP 電子請求書発行サーバーです。Claude、ChatGPT、Cursor、VS Codeから請求書の作成、発行、訂正ができます。
MCP server for Spanish e-invoicing with VeriFactu compliance — issue, correct and register invoices with AEAT straight from your AI agent.
beel.es · API docs · MCP guide · npm

---

M C P （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 の自動生成ラッパーではありません。モデルが利用できるようにする、次の 3 つの特長があります。

• ツールは公開 OpenAPI 契約から導出されます。そのため、各ツールの入力スキーマは、列挙値、明細項目、税制キーなど、実際の操作スキーマと一致します。API とのずれは生じません。
• ツールの選定ポリシーによって、エージェントに実際に提供するツールを決定します。バイナリのダウンロード、マルチパートのアップロード、Webhook の設定、ブラウザーセッションでしか認証できない操作、非推奨の操作は、手動ではなくルールに基づいて除外されます。
• 税務上のガードレールがツールに組み込まれています。自動生成ラッパーでは見落とされる不変条件を、モデルが読むドキュメントと、準拠しないリクエストが税務書類になる前に止める事前チェックの両方で提供します。

1 つのコードベースで、2 つのトランスポートに対応しています。ホスト型のリモートサーバーは https://mcp.beel.es/mcp（ストリーミング可能な 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

対話型で利用するための設定は以上です。ローカルサーバーが必要な場合にのみ、続きをお読みください。

ローカルで実行する

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_ で始まるキーは、実際の税務書類を発行します。

リリースは npm の信頼されたパブリッシングを通じて CI から公開されるため、来歴情報が付与されます。npm には、各ビルドの元となった正確なコミットとワークフローが記録されます。npm audit signatures で検証できます。

各リリースは、両方のトランスポートを掲載した es.beel/mcp として MCP Registry にも告知されます。そのため、レジストリを検索するクライアントは、サーバーの場所を指定されなくても見つけることができます。この名前は beel.es の DNS レコードで認証されているため、単にどこかのリポジトリにあるのではなく、当社のサーバーであることが示されます。

以前の io.github.beel-es/beel-mcp（v0.2.2）の掲載は、名前の移行時に終了しました。レジストリ名はラベルではなく ID であるため、名前の変更はリダイレクトではなく新しいエントリーになります。どちらも同じ npm パッケージと同じホスト型サーバーを指しています。

提供内容

• openapi/public-api.yaml から生成された 125 個の API ツール — 請求書、顧客、商品、定期請求書、シリーズと税務設定、NIF 検証、企業。
• API に単一のエンドポイントがない機能を補う 7 個の合成ツール：ドキュメント用の beel_docs_search、beel_docs_get、beel_docs_list（ドキュメントサイトの検索エンドポイントと、一度に 1 ページ分の Markdown、または 1 回の呼び出しで一部セクションを取得します。長いページでは概要が返されます）；税務ルールカタログ用の beel_rules_list と beel_rules_get（ID、複数の ID、ドメイン、キーワード、エラーコードで検索できます）；バンドルされたコントラクトからリクエストとレスポンスのスキーマのフィールドをコンパクトな TypeScript 風の宣言として返す beel_schema_get（スキーマ名、またはツール名を指定してクエリ、本文、戻り値の型を取得できます）；そして、発行に先立って不足している項目、次に行うべきアクション 1 つ、連携の起点となる ID（企業、書類種別ごとのデフォルトシリーズ、VeriFactu のステータス、税務のデフォルト設定）を NIF ごとに正確に報告する beel_get_setup_status。
• beel://guardrails/* 配下のガードレール用リソース — 税務ルール（ドメインごとに 1 つのリソース）、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 操作です。エージェントでは実行できず、それぞれが実用的なツールに必要なコンテキストを消費します。ルールは src/policy/tool-policy.ts にあります。

税務ガードレール

スペインの電子請求書には、スキーマだけでは LLM が誤る不変条件があります。修正すべき請求書を取り消す、簡易請求書に R1 を使う、AEAT がすでに登録した請求書を編集する、といった誤りです。サーバーはこれに 3 つのレイヤーで対処しており、それぞれの違いが重要です。

1. アドバイザリー — 意図的に分けている 2 つの情報源があります。

• 税務ルールは、ドキュメントサイトで公開されているカタログです。 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 — 税務ルールではないものの、 エージェントがつまずきやすい点を解説します。たとえば、明細行の価格の指定方法、 シリーズの設定方法、操作対象の会社、NIF の検証と発行準備状況の読み取り方、 各請求書操作に使用するツールなどです。ルールを再掲する代わりに、ルール ID への リンクを掲載しています。

適用されるドメインとガイドは、制約対象となる各ツールの説明に記載されているため、 制約は呼び出しとともに伝わります。

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

チェック	コード
各明細行で価格指定フィールドがちょうど 1 つであること	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 フィールドは 該当するコードのドキュメントページにリンクしています。サーバーはこれらを一切変更せずに 中継し、応答に含められない 2 つの情報だけを追加します。ツール呼び出しによる解決方法 — ドキュメントはダッシュボードを開いている利用者に向けて（「設定でシリーズを作成」）書かれて いますが、エージェントには beel_set_default_series が必要です — と、再試行しても 解決する可能性があるかどうかです。これにより、管理者の対応が必要な 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_ → Test、beel_sk_live_ → 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	1 回の API 呼び出しに対する厳密な上限です。デフォルトは 30000 です。
BEEL_DISABLE_PREFLIGHT	1 を設定すると、強制ガードレールをスキップします。

すべてのデフォルト値は 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
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	推測せずに内容を読みたいエージェント向けの llms.txt です

よくある質問

BeeL MCP サーバーとは何ですか？ スペインのVeriFactu電子請求を、AIエージェントが呼び出せるツールとして提供する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をご覧ください。質問はDiscussionsで受け付けています。good first issueラベルの付いたIssueは、最初に取り組むのに適しています。参加する方は全員、行動規範に従ってください。セキュリティ上の問題は公開Issueではなく、[email protected]にご連絡ください。詳しくはSECURITY.mdをご覧ください。

ライセンス

MIT © BeeL.