iso20022-bank-profile-mcp

iso20022-bank-profile-mcp：ISO 20022 銀行クリアリングプロファイルサーバー

完全ローカルな閉世界型のModel Context Protocolサーバーで、銀行固有のISO 20022クリアリングプロファイル／ルールパックを管理、検証、提供します。これは、構造的なXSD検証の 先に 位置する市場慣行ルールです。本サーバーは ISO 20022 MCP Suiteの基盤を担うメンバーであり、 iso20022-readiness-suite-mcpと連携します。このサーバーが提供するプロファイルは、同リポジトリのレディネスゲートウェイで利用できます。

2026年11月のマイルストーン。 主要スキーム（CBPR+、HVPS+、T2、 FedNow）がISO 20022の要件を厳格化するなか、特に構造化郵便住所の要件が強化され、 昨日まで問題のなかった支払いが、明日には拒否される可能性があります。 iso20022-bank-profile-mcpは、こうしたスキームのルールをバージョン管理されたエージェント呼び出し可能なクリアリングプロファイルに変換します。list_profilesと get_profileでプロファイルを提供し、lint_payloadでプロファイルに照らしてペイロードを評価し、 validate_profile_definitionで銀行が提供するルールパックを検証します。v0.0.6、 stdio（デフォルト）、ストリーミング可能なHTTP、SSE、認証付きOAuth 2.1 HTTPで利用できる読み取り専用ツール4つ、 プレミアムルールパックの利用権限ゲーティング、Python 3.10以降に対応しています。

目次

• 概要
• ISO 20022 MCP Suite
• インストール
• クイックスタート
• トランスポート — 1つのコマンドラインからstdio、ストリーミング可能なHTTP（2026-07-28および2025-11-25）、SSE、認証付きHTTPを利用できます
• ツール
• HTTPトランスポートと認証
• スイート内での位置づけ
• オープンコアとプレミアム
• iso20022-bank-profile-mcpを使用しない場合
• 開発
• セキュリティ
• ドキュメント
• ライセンス
• 貢献
• 謝辞

概要

Model Context Protocol（MCP）は、AIエージェントやアシスタントが外部ツールを一貫した方法で検出し、呼び出せるオープン標準です。 iso20022-bank-profile-mcpはISO 20022 MCP Suiteの 市場慣行プロファイル層 を担います。これは、支払いのクリアリングに必要なスキーム固有および銀行固有のルールで、XSDより 上位 に位置し、クリアリングシステムごとに異なります。

クリアリングプロファイルは純粋なデータであり、profile_id、そのmarket_practice、対応するメッセージ、宣言型のcustom_rules一覧で構成されます。本サーバーには、オープンなベースラインプロファイル（Generic、CBPR+、SEPA_Instant、FedNow）が含まれており、プロファイルの検出、全内容の取得、プロファイルに照らしたペイロードのリント、候補となるルールパックの検証を行う読み取り専用ツールを4つ提供します。

本サーバーは完全ローカルな閉世界型です。ネットワーク接続口、サブサーバー、メタクライアントはありません。各ツールはバンドルされたプロファイルデータから処理を行い、型付きのJSONシリアライズ可能な出力を返します。不正な入力、解析できないペイロード、不明なプロファイルなど、どのようなエラーの場合もクライアントのトランスポートに例外を送出せず、{"error": ...}ペイロードを返します。XMLペイロードの解析にはdefusedxmlのみを使用します（XXE／billion-laughs攻撃を防止）。

• Webサイト： https://sebastienrousseau.github.io/iso20022-bank-profile-mcp/
• ソースコード： https://github.com/sebastienrousseau/iso20022-bank-profile-mcp
• バグ報告： https://github.com/sebastienrousseau/iso20022-bank-profile-mcp/issues

flowchart TD
    A["MCP client<br/>(Claude Desktop, IDE, agent)"] -->|stdio, streamable HTTP, SSE| B["iso20022-bank-profile-mcp<br/>(clearing-profile server)"]
    B --> C["ProfileEngine<br/>(bundled JSON + register() seam)"]
    C --> D["Generic"]
    C --> E["CBPR+"]
    C --> F["SEPA_Instant"]
    C --> G["FedNow"]
    H["iso20022-readiness-suite-mcp<br/>(readiness gateway)"] -.consumes profiles.-> B

ISO 20022 MCP スイート

iso20022-bank-profile-mcp は、ISO 20022 移行向けに連携する、ベンダー中立の MCP サーバー群のひとつです。依存関係の範囲はスイート全体で統一されているため、同じ Python 環境に各サーバーをまとめてインストールできます。

基盤サーバーがそれぞれ特定のメッセージ処理を担い、レディネスゲートウェイがそれらを組み合わせるのに対し、このサーバーは清算プロファイルを担当します。スイート内の他のサーバーがリントの基準とする市場慣行のルールパックを管理、検証、提供します。

インストール

iso20022-bank-profile-mcp は macOS、Linux、Windows で動作し、Python 3.10+ と pip が必要です。MCP SDK、pydantic、defusedxml は自動的にインストールされます。いずれも PyPI で公開されています。

python -m pip install iso20022-bank-profile-mcp

または、uvx を使って PyPI から直接実行すれば、インストールは不要です。

uvx iso20022-bank-profile-mcp

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U iso20022-bank-profile-mcp

クイックスタート

インストールから MCP クライアントの設定、最初の会話までを10分で進めるチュートリアルは、docs/quickstart.md をご覧ください。

stdio（デフォルトのトランスポート）でサーバーを起動します。

iso20022-bank-profile-mcp

クライアントの設定に追加すると、Claude Desktop などの任意の MCP クライアントに登録できます。

{
  "mcpServers": {
    "iso20022-bank-profile": { "command": "iso20022-bank-profile-mcp" }
  }
}

このコマンドは標準入力／標準出力で MCP 通信を行います。対話形式で使用するのではなく、MCP クライアントから起動することを想定しています。これにより、エージェントは以下のツールを呼び出せるようになります。

トランスポートを介さず、FastMCP インスタンスから直接、プロセス内でツールを呼び出すこともできます。これはエージェントが stdio 経由で受け取る内容と同じです。すべてローカルで動作するため、他のサーバーは必要ありません。

import asyncio

from iso20022_bank_profile_mcp import server


async def main() -> None:
    async def call(name, args):
        result = await server.server.call_tool(name, args)
        # mcp 2.x returns a CallToolResult (use .content); 1.x returns
        # the content list, or a (content, meta) tuple.
        content = getattr(result, "content", None)
        if content is None:
            content = result[0] if isinstance(result, tuple) else result
        return content[0].text if content else ""

    # Which clearing profiles can I target?
    print(await call("list_profiles", {}))
    # -> {"profile_id": "...", "market_practice": "...", "rule_count": ...}, ...

    # Lint a payload against a profile: a CBPR+ address missing its town.
    payload = "<Document><PstlAdr><Ctry>DE</Ctry></PstlAdr></Document>"
    print(await call("lint_payload",
                     {"payload_content": payload, "profile_id": "CBPR+"}))
    # -> {"profile_id": "CBPR+", "is_compliant": false,
    #     "findings": [{"code": "CBPR_MISSING_TOWN", "locator": "TwnNm", ...}]}


asyncio.run(main())

トランスポート

1 つのコマンドラインで、4 種類のトランスポートを利用できます。

--host と --port は、streamable-http と sse のバインドアドレスを変更します（デフォルトは 127.0.0.1 と 8000 です）。この 2 つには認証機能がありません。ループバックにバインドするか、 ルーティング可能なアドレスにバインドする前に、信頼できるゲートウェイの背後に サーバーを配置してください。認証付きのオプションは --transport http です。すべてのリリースは、2 つのプロトコル世代の両方で scout を使用した Streamable HTTP 経由の検証と、MCP SDK クライアントを使用した SSE 経由の検証を受けています。 ADR 0001 を参照してください。

{
  "mcpServers": {
    "iso20022-bank-profile": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

ツール

すべてのツールは JSON にシリアライズ可能なデータを返します。ドメイン、検証、 または値のエラーが発生した場合は、例外を送出するのではなく、{"error": ...} ペイロードを返します。すべてのツールは、純粋でローカルな読み取り専用の 冪等な閉世界検索です。ネットワークもサブサーバーも使用しません。

• list_profiles — 利用可能な清算プロファイルの概要を軽量な形式で一覧表示します（profile_id、market_practice、tier、entitled、supported_messages、rule_count）。他のツールで使用できる profile_id の値を確認し、現在の呼び出し元がどのプロファイルを利用できるかを調べるために使用します。
• get_profile — ルール本文を含む、1 つの清算プロファイルの全内容を返します。プレミアムプロファイルでは、呼び出し元に利用権が必要です。利用権がない場合は、BP_NOT_ENTITLED エラーを返します（オープンコアとプレミアムの違いを参照）。
• lint_payload — 生の ISO 20022 ペイロードを清算プロファイルに照らして評価し、検出結果を返します（準拠しているペイロードの場合、検出結果はありません）。get_profile と同様に、プレミアムプロファイルには利用権が必要です。利用権がない場合は、BP_NOT_ENTITLED を返します。
• validate_profile_definition — 銀行から提供されたプロファイル／ルールパック定義を生の JSON として検証し、形式が正しいことと、すべてのルールが既知のアサーション動詞を使用していることを確認します。

HTTP トランスポートと認証

stdio はデフォルトであり、認証は不要です。オペレーターごとに 1 つのプロセスがクライアントによって起動され、ネットワークには公開されません。上記のスイートの streamable-http トランスポートと sse トランスポートも、認証なしで利用できます。複数テナントで共有するデプロイでは、サーバーは認証付きの streamable-HTTP トランスポートにも対応します。

iso20022-bank-profile-mcp --transport=http --bind=127.0.0.1:8080

--bind のデフォルトは 127.0.0.1:8080（ループバックのみ）であるため、ホスト外にサーバーを公開するには、明示的なオプトインが必要です（例：--bind=0.0.0.0:8080）。HTTP トランスポートは認証なしでは起動せず、認証されていないエンドポイントを提供することはありません。認証モードは、より強固なものから順に次の 2 つです。

• OAuth 2.1 リソースサーバー（RFC 9728） — ISO20022_BANK_PROFILE_OAUTH_ISSUER と ISO20022_BANK_PROFILE_OAUTH_AUDIENCE を設定します（どちらも必須）。省略可能な ISO20022_BANK_PROFILE_OAUTH_JWKS_URL（デフォルトは <issuer>/.well-known/jwks.json）と ISO20022_BANK_PROFILE_OAUTH_SCOPES も設定できます。すべてのリクエストに Authorization: Bearer <jwt> を含める必要があります。トークンは JWKS と照合され、iss／aud／exp／nbf／必須スコープが検証されます。検証に失敗すると、RFC 9728 の WWW-Authenticate チャレンジとともに 401／403 が返されます。また、保護対象リソースのメタデータは /.well-known/oauth-protected-resource で提供されます。このサーバーは、既存の認可サーバー（Okta、Auth0、Entra ID など）のトークンを検証します。認可サーバーの実行は対象範囲外です。

  ISO20022_BANK_PROFILE_OAUTH_ISSUER=https://auth.example.com \
  ISO20022_BANK_PROFILE_OAUTH_AUDIENCE=https://mcp.example.com/mcp \
    iso20022-bank-profile-mcp --transport=http --bind=0.0.0.0:8080
  

• 静的な開発モードトークン — ISO20022_BANK_PROFILE_TOKEN に共有シークレットを設定します。この場合、すべてのリクエストで Authorization: Bearer <secret> を送信する必要があります。これは、有効期限もスコープもない単一の共有シークレットであり、本番環境ではなくローカル開発向けです。

省略可能な X-MCP-Tenant リクエストヘッダーは、複数テナントのスコープ設定に使えるよう、ツールから参照できるリクエストコンテキストに引き継がれます。詳細なセットアップについては、docs/transport.md を参照してください。

スイート内での役割

このサーバーは、ISO 20022 MCP Suite のプロファイル管理元です。関連する iso20022-readiness-suite-mcp ゲートウェイは、決済をクリアリングプロファイルと照合してスコアリングし、是正します。これらのプロファイルは、まさにこのサーバーが管理、検証、提供するものです。プロファイルのソースを 1 つに統一することで、レディネスゲートウェイと各銀行独自のツールが、同じ市場慣行ルールに照らして決済を評価できます。

プロファイルカタログは、スイート全体で共有される接続点から拡張できます。ProfileEngine は ProfileEngine.from_bundled() を使って同梱 JSON からオープンなベースラインを読み込み、実行時にプロファイルを追加（または置換）するための ProfileEngine.register(profile) を提供します。プレミアムの銀行固有ルールパックも、同梱プロファイルと同じ形式です。つまり、profile_id、market_practice、supported_messages、custom_rules のリストを持つ ClearingProfile です。そのため、このサーバーを組み込むデプロイでは、ツールのインターフェースを変更することなく、ライセンスを受けたパックを登録し、オープンなベースラインとともに提供できます。ルールのミニ言語と register() の接続点については、docs/profiles.md を参照してください。

オープンコアとプレミアム

このサーバーはオープンコアです。ベースラインのスキームプロファイルとプロファイルエンジンはオープンソースで、常に利用できます。上位プラン向けの機関固有機能は、同じプロファイルエンジンの接続点に組み込む商用アドオンです（エンジンには、実行時に読み込むルールパック向けの register() フックがすでに用意されています）。

オープンソースプランの機能には、利用期限も機能制限もありません。

エンタイトルメントゲートの仕組み

各クリアリングプロファイルには tier が設定されています。「open」（ベースラインプロファイル。制限がなく、常にアクセス可能）または「premium」（ライセンスが必要なルールパック）です。ゲートを試せるように、バンドルされたプレミアムのサンプルプロファイル ACME_Premium が同梱されています。list_profiles は各プロファイルの tier と、呼び出し元ごとの entitled ブール値を報告します。premiumプロファイルに対する get_profile と lint_payload は、呼び出し元にエンタイトルメントがない場合、BP_NOT_ENTITLED エラーを返します。

エンタイトルメントは、独立した次の2つのソースのどちらか（OR条件）によって付与されます。

• OAuth スコープ（HTTP トランスポート） — profile:premium スコープを持つトークンはすべてのプレミアムプロファイルに対するエンタイトルメントを持ち、profile:<profile_id> を持つトークンはそのプロファイルだけに対するエンタイトルメントを持ちます。
• 環境変数の許可リスト（stdio／dev） — ISO20022_BANK_PROFILE_ENTITLEMENTS には、オペレーターがライセンスを持つプレミアム profile_id の値を指定します（カンマまたはスペース区切り）。* を指定すると、すべてのプレミアムプロファイルに対するエンタイトルメントが付与されます。

# stdio: license the ACME_Premium sample pack for this process
ISO20022_BANK_PROFILE_ENTITLEMENTS=ACME_Premium iso20022-bank-profile-mcp

ゲートはこのリリースに含まれますが、プレミアムのルールパック自体（および状態を保持するバージョン履歴／監査ログ）は引き続き有料で、ツリー外の機能です。エンタイトルメントモデルの詳細については、docs/profiles.md を参照してください。

iso20022-bank-profile-mcpを使用すべきでない場合

• MCP クライアントを持っていない場合。 このサーバーは、MCP 対応ホスト（Claude Desktop、IDE プラグイン、エージェントフレームワーク）と組み合わせて使う場合にのみ意味があります。
• 構造的な XSD 検証やメッセージ生成が必要な場合。 これらは基盤スイートのサーバー（iso20022-mcp、camt053-mcp、pain001-mcp）の機能です。このサーバーは XSD の上位にある市場慣行ルールを評価します。メッセージの解析、生成、構造的な検証は行いません。
• エンドツーエンドの準備状況スコアと修正案が必要な場合。 その役割を担うのは、これらのプロファイルを利用する iso20022-readiness-suite-mcp です。スコアリング、修正案、銀行の応答シミュレーションをまとめて利用したい場合は、こちらを使用してください。
• 認証なしで、ルーティング可能なアドレス上の長時間稼働ネットワークサービスが必要な場合。 デフォルトは stdio（オペレーターごとに1つのプロセス、ネットワークへの公開なし）です。--transport streamable-http と --transport sse はループバックにバインドされ、認証を行いません。そのため、ルーティング可能な環境にデプロイする場合は、信頼できるゲートウェイの背後に配置してください。共有のマルチテナントデプロイ向けには --transport http オプションがあり、常に認証（OAuth 2.1 または静的な dev モードのトークン）が必要です。認証されていないエンドポイントを提供することはありません。
• ストリーミング応答が必要な場合。 ツール呼び出しはストリームではなく、値全体を返します。

開発

iso20022-bank-profile-mcp は Poetry と mise を使用します。

git clone https://github.com/sebastienrousseau/iso20022-bank-profile-mcp.git && cd iso20022-bank-profile-mcp
mise install
poetry install
poetry shell

注記： サーバーは完全にローカルで閉じた世界で動作するため、テストスイートの実行に他のものをインストールする必要はありません。CONTRIBUTING.md を参照してください。

Makefile は品質チェック（CI と同期したもの）を統括します。

make check        # all gates (REQUIRED before commit): lint + type-check + test
make test         # pytest (100% line + branch coverage)
make lint         # ruff + black
make type-check   # mypy --strict
make security     # bandit

セキュリティ

iso20022-bank-profile-mcp はエラーをデータとして返します。すべてのツールは、文書化されたドメインエラー、検証エラー、値エラーを捕捉し、{"error": ...} エンベロープを返します。MCP クライアントに未加工の例外が伝播することはありません。クリアリングプロファイルエンジンを通じて受け取ったペイロードは defusedxml のみで解析されます（XXE／Billion Laughs 攻撃には脆弱ではありません）。また、サーバーはネットワークソケットを開きません。報告に関する慣行、サポート対象バージョン、攻撃対象領域、およびサプライチェーン対策の全容（SLSA L3 の来歴、PEP 740 の証明、SBOM、NIST SP 800-218 SSDF の実践項目との対応）については、SECURITY.md に記載されています。脆弱性の報告には GitHub Private Vulnerability Reporting を利用してください。公開 issue には報告しないでください。

ドキュメント

• README.md — このファイル
• CHANGELOG.md — リリースノート
• SECURITY.md — 脆弱性の開示とサポート対象バージョン
• SUPPORT.md — サポートの受け方
• ROADMAP.md — 提供済みの機能（HTTP トランスポート、プレミアム利用権限の制御）と今後の予定（より充実した銀行ルールパック）
• MAINTAINERS.md — マージ権限を持つメンテナー
• docs/quickstart.md — インストールから最初の会話までの 10 分ガイド
• docs/profiles.md — クリアリングプロファイル、ルールのミニ言語、プレミアムルールパック、利用権限ゲート
• docs/transport.md — オプションの HTTP トランスポートと OAuth 2.1 のセットアップ
• glama.json — Glama ディレクトリのマニフェスト

MCP Registry

mcp-name: io.github.sebastienrousseau/iso20022-bank-profile-mcp

ライセンス

Apache License, Version 2.0 の下でライセンスされています。収録のために 提出されたコントリビューションは、追加の条件なしに、上記と同じライセンスの下で ライセンスされます。

コントリビューション

コントリビューションを歓迎します。コントリビューションの手順をご覧ください。 すべてのコントリビューターに感謝します。

謝辞

ISO 20022 MCP Suite の基盤となるサーバー群および Model Context Protocol Python SDK とともに開発されました。