openfinance-br-mcp

English · Português

openfinance-br-mcp

Open Finance Brasil向けの実験的なMCPサーバーです。完全なモック環境と、開発が進行中のFAPI-BR連携を備えています。認定を受けておらず、実際の金融機関に対する検証も行われていません。environment=mock以外で使用する前に、VALIDATION.mdをご覧ください。

---

概要

Open Finance Brasil（FAPI 1.0 Advanced、OAuth2、同意、mTLS）の複雑さを抽象化し、Claude にシンプルなツールを提供するMCP サーバーです。

Claude → "how much did I spend on food in March?"
Claude uses list_transactions(bank=nubank, categorize=true, date_from=2024-03-01)
Claude → "You spent R$ 847.30 on food in March..."

対応銀行

モック環境では、メモリ内データを使用して、Nubank、Sicoob、Caixa、Banco do Brasil、 Bradesco、Itaú、Santander、XP、PicPay、BTG Pactualをシミュレートします。ネットワークへのアクセスはありません。これらはシミュレーションであり、認定済みの連携ではありません。

実際のアダプターとPayments APIの一連の処理は実験段階であり、検証されていません。 Paymentsでは、v5のpayments-consents／payments-pix Directoryファミリー、 同意ごとの専用トークン、検証済みのレスポンスJWS、PAR/JAR、同意ペイロードとの バインド、永続的な冪等性を使用します。 list_pix_keysはデモ用の拡張機能であり、標準化された Open Finance Brasilのエンドポイントではありません。正確な対象範囲については、 VALIDATION.mdをご覧ください。

利用可能なMCPツール

サーバーは、ワークフロー別に分類された18個のツールを提供します。

• 口座： list_accounts、get_balance、list_transactions
• カード： list_credit_cards、get_credit_card_bills
• 投資： list_investments、list_funds、 list_variable_incomes、list_treasure_titles
• PIX： list_pix_keys、initiate_pix
• データ同意： start_consent、complete_consent、 check_consent_status、revoke_consent
• 支払い同意： start_payment_consent、complete_payment_consent、 check_payment_consent_status

また、openfinance://banks/リソース、analyze_monthly_spendingプロンプト、 および認可フロー開始時の任意のURLエリシテーションも提供します。

クイックスタート

前提条件

• Python 3.12または3.13
• uvのインストール

# Run the published release in credential-free mock mode
uvx --from openfinance-br-mcp==0.2.0 openfinance-mcp

ソースから

git clone https://github.com/brunovicco/openfinance-br-mcp.git
cd openfinance-br-mcp

# Optional: needed only for sandbox/production or DSPy categorization
cp .env.example .env

# Install dependencies
uv sync

# Run the server
uv run openfinance-mcp

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.jsonに追加します。

{
  "mcpServers": {
    "openfinance-br": {
      "command": "uvx",
      "args": ["--from", "openfinance-br-mcp==0.2.0", "openfinance-mcp"]
    }
  }
}

開発

# Install with dev-dependencies
uv sync

# Run the tests
uv run pytest tests/ -v

# Lint and formatting
uv run ruff check src/ tests/
uv run black src/ tests/

# Type check
uv run mypy src/

コンテナとKubernetes

docker compose up openfinance-mcp
docker compose --profile test up

k8s/ディレクトリには、Redisを利用した状態管理を備える、レプリカ2台構成のStreamable HTTPサンプルが含まれています。適用する前に、すべての認証情報、署名キー、OAuth発行者、リソースサーバー、ドメインのプレースホルダーを置き換えてください。ループバック以外にHTTPを公開する場合、MCPクライアントのOAuthが設定されていないと、サーバーはフェイルクローズします。

アーキテクチャ

Claude (MCP Client)
        │ stdio or streamable-http
        ▼
openfinance-br-mcp (MCP Server)
  ├── Auth + Consent  (FAPI-BR 2.2.0: private_key_jwt, PAR/JAR, PKCE, mTLS)
  ├── MCP Primitives  (18 tools + 1 resource + 1 prompt)
  │   ├── Pydantic v2 input/output schemas
  │   ├── Optional URL elicitation for bank authorization
  │   └── Categorizer (DSPy + Claude for transaction classification)
  ├── Bank Adapters   (10 banks - extensible)
  └── Directory Client (resolves real bank endpoints from the BCB
                         Directory of Participants)
        │ HTTPS/mTLS
        ▼
Open Finance BR (BCB) - Directory of Participants
        │
        ▼
  Nubank · Sicoob · Caixa · + 100 participating institutions

環境変数

変数	必須	説明
ENVIRONMENT	❌	mock（デフォルト。認証情報は不要）、sandbox、または production
CLIENT_ID	⚠️ non-mock	金融機関に登録されたクライアント ID
PRIVATE_KEY_PATH	⚠️ non-mock	private_key_jwt／JAR 署名用の RSA 秘密鍵
PRIVATE_KEY_KID	⚠️ non-mock	登録済みクライアントの JWKS と一致する kid
MTLS_CERT_PATH	⚠️ prod	mTLS 証明書へのパス
MTLS_KEY_PATH	⚠️ prod	mTLS 秘密鍵
ANTHROPIC_API_KEY	⚠️ DSPy	categorize=true に必要
REDIS_URL	❌	レプリカ間で TokenStore／ConsentManager の状態を共有します
MCP_TRANSPORT	❌	stdio（デフォルト）または streamable-http
MCP_HTTP_ALLOWED_ORIGINS	⚠️ remote HTTP	ループバック以外にバインドする場合に必要な許可リスト
LANGFUSE_OTLP_ENDPOINT	❌	Langfuse へのトレースを有効にします（LANGFUSE_PUBLIC_KEY／LANGFUSE_SECRET_KEY と併用）
LOG_LEVEL	❌	INFO、DEBUG、WARNING（デフォルト：INFO）
LOG_FORMAT	❌	json または console（デフォルト：json）

全一覧は .env.example をご覧ください。

ドキュメント

• 認可 - 2つのトークン領域と、それらを相互に利用できない理由
• コントリビューション - 開発環境のセットアップ、CI チェック、アダプターの追加方法
• セキュリティ - 適用範囲、免責事項、脆弱性の報告
• ソース - 実装が準拠する仕様と RFC
• 検証 - 検証済みの内容と未検証の内容
• 変更履歴 - リリース履歴
• リリース - メンテナー向けリリース手順

ライセンス

MIT