openfinance-br-mcp

English · Português

openfinance-br-mcp

面向 Open Finance Brasil 的实验性 MCP 服务，包含完整的模拟环境和不断完善的 FAPI-BR 集成。该服务未经认证，也未通过真实机构验证；在 environment=mock 以外的环境中使用前，请参阅 VALIDATION.md。

---

项目简介

一个 MCP 服务，用于抽象 Open Finance Brasil（FAPI 1.0 Advanced、OAuth2、授权同意、mTLS）的复杂性，并向 Claude 提供简单的工具：

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 提供状态存储、运行两个副本的 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	⚠️ 非 mock	在机构注册的客户端 ID
PRIVATE_KEY_PATH	⚠️ 非 mock	用于 private_key_jwt/JAR 签名的 RSA 私钥
PRIVATE_KEY_KID	⚠️ 非 mock	与已注册客户端 JWKS 匹配的 kid
MTLS_CERT_PATH	⚠️ 生产环境	mTLS 证书路径
MTLS_KEY_PATH	⚠️ 生产环境	mTLS 私钥
ANTHROPIC_API_KEY	⚠️ DSPy	categorize=true 时必需
REDIS_URL	❌	在多个副本之间共享 TokenStore/ConsentManager 状态
MCP_TRANSPORT	❌	stdio（默认）或 streamable-http
MCP_HTTP_ALLOWED_ORIGINS	⚠️ 远程 HTTP	任何非环回绑定都必须设置允许列表
LANGFUSE_OTLP_ENDPOINT	❌	启用向 Langfuse 发送跟踪数据（需配合 LANGFUSE_PUBLIC_KEY/LANGFUSE_SECRET_KEY）
LOG_LEVEL	❌	INFO、DEBUG、WARNING（默认：INFO）
LOG_FORMAT	❌	json 或 console（默认：json）

完整列表请参阅 .env.example。

文档

• 授权 - 两种令牌体系，以及它们为何绝不能互通
• 贡献 - 开发环境设置、CI 检查和添加适配器
• 安全 - 范围、免责声明和漏洞报告
• 来源 - 实现所遵循的规范和 RFC
• 验证 - 已验证和未验证的内容
• 更新日志 - 发布历史
• 发布 - 维护者发布流程

许可证

MIT