iso20022-mcp

iso20022-mcp

7つのメタツールを備えた1つの MCP サーバーが、すべての ISO 20022 メッセージファミリーに振り分けます。

---

目次

はじめに

• インストール — ファミリーごとの pip extras、uvx、MCP クライアントの設定
• 要件 — ツールチェーンの最低要件、プラットフォーム
• クイックスタート — 1つのサーバーから検索、説明、検証、生成、解析を実行

iso20022-mcp エコシステム

• iso20022-mcp エコシステム — ISO 20022 MCP Suite と、このゲートウェイが振り分けるファミリーサーバー

ライブラリリファレンス

• 機能の概要 — テーマ別の現在の機能
• エコシステムの比較 — 簡易マトリックス。完全な表は docs/COMPARISON.md を参照
• ベンチマーク — 主な数値。完全な表は docs/BENCHMARKS.md を参照
• 機能 — モジュールレベルの機能一覧
• 設定 — 主なオプション
• 例 — 実行可能な例の一覧

運用

• iso20022-mcp を使用すべきでない場合 — 制限事項
• 開発 — make ターゲット、ファジング、CI
• セキュリティ — 保証とコンプライアンス
• ドキュメント — すべてのリファレンスドキュメント
• 安定性の保証 — SemVer の適用範囲、出力の安定性、ツールチェーンの最低要件に関する方針
• ライセンス

---

インストール

Python ライブラリとして

pip install "iso20022-mcp[all]"

最新リリース：v0.0.18：stdio、ストリーム可能な HTTP、または SSE（HTTPS による提供も可能）で利用できる7つのルーティング用メタツール。軽量なコア（mcp のみ）、 オプションの extras としてファミリーサーバーを提供し、 validate／generate のすべての失敗に対して、次の対応につながる構造化エラーを返します。Python 3.10 以降に対応しています。

コアは軽量です。必要なファミリーを extras として追加してください。

pip install "iso20022-mcp[pacs,camt]" # just interbank + statements
pip install iso20022-mcp              # core only; families report as not installed
uvx --from "iso20022-mcp[all]" iso20022-mcp   # run without installing

MCP クライアントの設定（例：Claude Desktop）：

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

---

要件

• Python 3.10 以降。Linux 上の CI で 3.10、3.11、3.12、3.13、3.14 をテスト済みです （ツールチェーンポリシー）。
• 1.x 系では mcp 1.30 以降、または 2.x 系では 2.2 以降。 GHSA-84m7-p3x7-pcfv の影響を受けるリリースは解決できません。
• ファミリーサーバーはオプションの追加機能です：pain、pacs、camt、 acmt、または all。

---

クイックスタート

search(query="reconciliation")
  → [{ "message_type": "camt.053", "family": "camt", "package": "camt053-mcp" }]

describe(message_type="pacs.008")           # required fields + input schema
validate(message_type="pacs.008", records=[…])
generate(message_type="pain.001", records=[…])   # → { "xml": "<Document>…" }
  # bare "pain.001" resolves to pain.001.001.09; on failure the payload is
  # { "error": "Missing required fields for pain.001.001.09: …" } listing
  # every missing or invalid field at once — fix them all and retry once
parse(message_type="camt.053", xml="<Document>…")
  # parse covers pacs + camt only; pain and acmt are outbound-only

まず search または list_families でメッセージタイプを探し、describe で必須フィールドと入力スキーマを確認してから、validate、generate、または parse を実行してください。各呼び出しは、そのメッセージタイプのプレフィックスに対応するファミリーサーバーにルーティングされます。

---

iso20022-mcp エコシステム

iso20022-mcp は ISO 20022 MCP Suite の汎用メッセージツールキットです。ISO 20022 の銀行取引明細ワークフローと 2026 年 11 月の構造化住所への移行に対応する、連携したベンダー中立の 8 つの MCP サーバーに加え、準備状況のスコアリング、クリアリングプロファイルの検査、監査証跡を担うオーケストレーションレイヤーで構成されています。依存関係の範囲はスイート全体で揃えているため、1 つの Python 環境に各サーバーを問題なく併せてインストールできます。まず 1 つから始め、ワークフローの拡大に合わせて追加してください。

コンポーネント	目的	ユースケース
camt053-mcp	ISO 20022 の camt.053／camt.052 銀行取引明細：解析、検証、フィルタリング、反転。MT940／MT942 からの移行、CBPR+ 対応状況の確認、仕訳エクスポート（24 個のツール、4 個のプロンプト、3 個のリソース）	銀行から顧客への取引明細を一貫して扱う場合。スイートの主要パッケージです
iso20022-mcp	統合ゲートウェイ：pain・pacs・camt・acmt ファミリー全体にルーティングされる search／describe／validate／generate／parse メタツール（7 個のメタツール）	すべてのメッセージファミリーへの単一のエントリーポイントが必要な場合：このパッケージ
reconcile-mcp	予定された pain.001 の支払いと、実際に確認された camt.053 の明細項目を照合します。一致、部分一致、一対多、多対一に対応し、各照合結果をスコア化して説明します（7 個のツール）	説明可能な取引明細／支払い照合が必要な場合
bankstatementparser-mcp	複数形式の取引明細を取り込みます：ISO 20022 CAMT.053 および pain.001、SWIFT MT940、OFX/QFX、CSV（5 個のツール、1 個のプロンプト、1 個のリソース）	取引明細が複数の形式やレガシー形式で届く場合
structured-address-fix-mcp	2026 年 11 月の構造化住所への移行に向けた、ISO 20022 郵便住所の分類、評価、修正（9 個のツール）	2026 年 11 月 14 日までに債務者／債権者の住所を整備する必要がある場合
iso20022-readiness-suite-mcp	オーケストレーション：検出、検証、クリアリングプロファイルの検査、準備状況のスコアリングに加え、修正と pacs.002 応答のシミュレーション（4 個のツール）	スイート全体を対象とする、上位レベルの準備状況確認用エントリーポイントが必要な場合
iso20022-bank-profile-mcp	銀行のクリアリングプロファイルとルールパック（CBPR+、SEPA_Instant、FedNow、Generic）を管理、検証、提供します（4 個のツール）	自社の市場慣行に照らして支払いを検査する場合
iso20022-evidence-pack-mcp	検出事項、修正差分、シミュレーション済み応答をまとめ、封印済みの Ed25519 署名可能な監査証跡パックを作成します（6 個のツール）	改ざんを検知できる監査証跡や認証用の成果物が必要な場合
pain001-mcp、pacs008-mcp、acmt001-mcp、camt-exceptions	このゲートウェイがルーティングするファミリー別サーバー。追加機能としてインストールされます	iso20022-mcp[all] によりインストールされます。機能を参照してください

---

機能の概要

分野	機能	ステータス
検索	カタログ全体を対象とする search、list_families、list_servers	リリース済み。コアのインストールで利用可能
スキーマ	describe は必須フィールドと入力 JSON Schema を返します	リリース済み。各ファミリーの追加パッケージが必要
検証	validate はメッセージタイプのスキーマに照らしてレコードを検証します	リリース済み。すべてのファミリーに対応
生成	generate は pain、pacs、acmt、camt.056／camt.029 の検証済み XML を生成します	リリース済み
解析	parse は受信した pacs および camt の XML を読み取ります	リリース済み。pain と acmt は送信専用です
トランスポート	stdio、ストリーム可能な HTTP、SSE、オプションの HTTPS	リリース済み。HTTPS は 0.0.18 以降

---

エコシステムの比較

このゲートウェイの代替手段は、エージェントを各ファミリーのサーバーに個別に接続することです。2026-10-20 に stdio 経由で list_tools を実行して測定しました。

プロジェクト	設定するサーバー数	エージェントに表示されるツール数	推定カタログトークン数
iso20022-mcp	1	7	約2,200
4つのファミリーサーバーすべてに直接接続	4	73	約36,400

根拠と完全な比較表については、docs/COMPARISON.md を参照してください。

---

ベンチマーク

ルーティングにかかる時間はマイクロ秒単位です。各プロセスでファミリーを初めて呼び出す際には、遅延インポートが一度だけ実行されます。benches/bench_gateway.py --quick を使用して測定しました。

シナリオ	結果	環境
family_for のルーティング	0.54 µs	Apple A18 Pro、Python 3.12.15、mcp 2.3.0
search_catalog	7.29 µs	Apple A18 Pro、Python 3.12.15、mcp 2.3.0
初回の pain.001 呼び出し（コールドインポート）	528 ms	Apple A18 Pro、Python 3.12.15、新規インタープリター
2回目以降の pain.001 呼び出し（ウォーム）	5.04 µs	Apple A18 Pro、Python 3.12.15

測定方法と全結果については、docs/BENCHMARKS.md を参照してください。

---

機能

7つのルーティング用メタツール：

• search — ユースケース／キーワード（「照合」、「pacs.008」など）でメッセージタイプを検索します。(ファミリー：すべて — カタログ)
• list_families — ファミリー、その機能、インストール済みのバックエンドパッケージを一覧表示します。(ファミリー：すべて)
• list_servers — ファミリー、E&I メッセージ、専用サーバー（照合、エージェント決済ブリッジ）を含む全体構成を表示します。(ファミリー：すべて)
• describe — メッセージタイプの必須フィールドと入力 JSON Schema を表示します。(ファミリー：すべて)
• validate — メッセージタイプのスキーマに照らしてレコードを検証します。(ファミリー：すべて)
• generate — レコードから検証済みの ISO 20022 XML メッセージを生成します。(ファミリー：pain · pacs · acmt)
• parse — 受信した ISO 20022 XML メッセージを解析し、構造化データに変換します。(ファミリー：pacs · camt)

操作は機能に応じて実行されます。受信形式である camt.053 の明細書に対して generate を実行すると、不明瞭な失敗ではなく、明確で説明的なエラーが返されます。また、「パッケージがインストールされていない」場合はすべて、実行すべき pip install の内容が正確に示されます。

ルーティング対象のファミリー全体で、次の3つの使いやすさを保証します。

• 対処に役立つ構造化エラー。 バックエンドサーバーが発生させるエラーは、サーバーが返すエラーだけでなく、すべてエージェントに {"error": "<Type>: <message>"} ペイロードとして渡され、不透明なツール実行エラーにはなりません。pain の生成では、エラーに不足または無効なフィールドがすべて一度に列挙されるため、修正して再試行するだけで済みます。
• message_type のファミリーエイリアス。 ファミリー名だけを指定すると、バックエンドサーバーを通じて具体的なバージョンに解決されます。例：pain.001 → pain.001.001.09、pain.008 → pain.008.001.02。バージョンまで指定したタイプがわかっている場合は、引き続きそちらを推奨します。
• ファミリーごとの解析対応範囲を事前に明示。 parse が対応するのは受信ファミリーのみです。対象は pacs（例：pacs.008）と camt（例：camt.053）です。開始ファミリーの pain と acmt は送信専用で、このサーバーにはパーサーがありません。そのため、pain.001 または acmt.001 の生成→解析の往復処理は試みず、代わりに validate（またはバックエンドサーバーの XSD 検証）を使用してください。

ルーティング

プレフィックス	ファミリー	バックエンドサーバー	生成	解析
pain	顧客信用振替開始	pain001-mcp	✅	—
pacs	金融機関間の顧客信用振替	pacs008-mcp	✅	✅
camt	銀行から顧客への明細書	camt053-mcp	—	✅
acmt	口座開設指示	acmt001-mcp	✅	—
camt.056/camt.029	取消／解決（E&I）	camt-exceptions	✅	—

generate("camt.056.001.12", …) は camt-exceptions にルーティングされます。また、ゲートウェイは、検出用に search と list_servers を通じて、専用サーバーの reconcile-mcp と ap2-iso20022 も公開します（これらは各サーバー独自のツールから呼び出します）。

ゲートウェイは各バックエンドサーバーを遅延かつ任意でインポートします。コアが依存するのは mcp のみで、各ファミリーのサーバーは初回使用時に読み込まれます。メッセージ型はプレフィックスに基づいて判定されます（pacs.008.001.08 → pacs）。pain エクストラには pain001-mcp >= 0.0.56 が必要です。このリリースには、ゲートウェイの保証の基盤となる、LLM に使いやすい生成インターフェース（フィールドエイリアス、計算される nb_of_txs／ctrl_sum、すべてのフィールドエラーの一括報告）が含まれています。

---

設定

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

コマンド	トランスポート	エンドポイント	プロトコルのリビジョン
iso20022-mcp	stdio	クライアントがプロセスを起動します	2026-07-28、2025-11-25
iso20022-mcp --transport streamable-http	Streamable HTTP	http://127.0.0.1:8000/mcp	2026-07-28（ステートレス、server/discover）および 2025-11-25（同じエンドポイント上の initialize、Mcp-Session-Id）。レスポンスはサーバー送信イベントとしてストリーム配信され、GET はサーバーからクライアントへのストリームを開きます
iso20022-mcp --transport sse	HTTP+SSE（2024-11-05）	http://127.0.0.1:8000/sse および /messages/	古いトランスポートを引き続き想定するクライアント向けです

--host と --port でバインドアドレスを変更できます（デフォルトは 127.0.0.1 と 8000 です）。--ssl-certfile cert.pem --ssl-keyfile key.pem を指定すると、mcp 1.x と 2.x のどちらでも、HTTP トランスポートを HTTPS で提供できます。HTTP トランスポートには認証機能が組み込まれていません。ループバックにバインドするか、ルーティング可能なアドレスにバインドする前に、信頼できるゲートウェイの背後にサーバーを配置してください。各リリースは、両方のプロトコル世代で passmcp を使った Streamable HTTP、および MCP SDK クライアントを使った SSE で検証されています。詳しくはADR 0001をご覧ください。

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

すべてのオプションは iso20022-mcp --help で確認できます。

---

使用例

• examples/mcp_tools.py：コアのインストールでの検出と、それに続くルーティングされた describe、validate、generate、parse の呼び出し（pip install -e ".[all]" の後に python examples/mcp_tools.py を実行します）。
• benches/bench_gateway.py：ゲートウェイが各ファミリーサーバーに追加する機能を確認できます。
• camt.053 明細書と、対応する pain.001 支払いを照合する専用エンジンについては、reconcile-mcpをご覧ください。

---

iso20022-mcp を使用しない場合

• ファミリー固有の専用ツールが必要な場合。 ゲートウェイが公開するのは、すべてのファミリーに共通する操作です。たとえば camt053-mcp の MT940 移行や仕訳エクスポートは、そのサーバーでのみ利用できます。サーバーに直接接続してください。
• pain または acmt のラウンドトリップが必要な場合。 ここでは出力専用で、パーサーはありません。
• 銀行、決済エンジン、または支払い承認者が必要な場合。 このツールはメッセージをルーティングして検証しますが、メッセージをどこかに送信することはなく、銀行による認証でもありません。
• HTTP トランスポートでの認証が必要な場合。 認証機能は組み込まれていません。認証ゲートウェイを前段に配置してください。

---

開発

git clone https://github.com/sebastienrousseau/iso20022-mcp
cd iso20022-mcp
python -m venv .venv && . .venv/bin/activate
make dev
make check                         # lint, mypy strict, tests, version agreement
python benches/bench_gateway.py --quick

make check は、ruff、black、厳格モードの mypy、行カバレッジと分岐カバレッジが 100% の pytest（バックエンドはフェイクを使用）、およびバージョン一致チェックを実行します。CI では CodeQL、OpenSSF Scorecard、reuse lint、MCP Inspector、Hypothesis のプロパティテスト、すべてのツールを対象にした Atheris のファジングも実行します（変更ごとに 2 分、週次で 30 分）。DEVELOPMENT.md と CONTRIBUTING.md を参照してください。

---

セキュリティ

ツールは読み取り専用で、冪等かつ閉世界方式です。ツールがパス、URL、ソケットを開くことはなく、すべての呼び出しは単一のレジストリテーブルを経由するため、呼び出し元の入力がインポートに到達することはありません。デフォルトは Stdio です。HTTP トランスポートはループバックにバインドされ、HTTPS を提供できますが、独自の認証機能は備えていません。リリースは署名済みタグから再現可能な方法でビルドされ、SLSA 来歴情報と sigstore 署名が付与されており、検証できます。脅威モデルと証拠は、保証ケースとセキュリティレビューに記載されています。このプロジェクトはOpenSSF ベストプラクティスの合格バッジを取得しています。

脆弱性は SECURITY.md に従って報告してください。

---

ドキュメント

ユーザーマニュアル · API リファレンス：ツール · 開発者ガイド · アーキテクチャ · ファミリーマップ · 変更履歴 · ロードマップ

---

安定性の保証

このプロジェクトは 1.0 より前の段階であり、バージョンは 0.0.1 刻みで進みます。破壊的変更の対象となるのは、エージェントから見える MCP インターフェース、すなわちツール名、その引数、返されるデータの形式（{"error": ...} ペイロードを含む）です。Python のシグネチャに変更がなくても、これらのいずれかへの変更は破壊的変更となり、変更履歴で明記されます。生成される XML はファミリーサーバーに由来し、それぞれ独自の安定性ルールに従います。Python の最低バージョンは、ツールチェーンポリシーに記載された場合にのみ引き上げられます。

---

ライセンス

このプロジェクトは、以下のいずれかのライセンスを選択して利用できるデュアルライセンスです。

• Apache License, Version 2.0 (LICENSE-APACHE または https://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT または https://opensource.org/licenses/MIT)

依存関係には、それぞれ独自のライセンスが適用されます。

ロゴは、glyph.faisalovers による「Computer connected」で、Noun Project の作品です。CC BY 3.0 ライセンスの下で提供され、ライトテーマとダークテーマに合わせて色が変更されています。

---

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