io.github.brunovicco/openfinance-br-mcp

Checks the current status of a user's consent at a bank. Args: subject_id: User's CPF or internal ID. bank: Identifier of the participating bank. ctx: MCP request context, providing access to shared dependencies. Returns: The consent's current status.

Checks the current status of an exact payment consent journey. Args: subject_id: Payer's CPF or internal ID. bank: Identifier of the participating bank. consent_id: Exact payment consent journey to query. ctx: MCP request context, providing access to shared dependencies. Returns: The payment consent's current status.

Completes a consent flow using the URL the bank redirected the user to after they finished logging in and authorizing. Because FAPI-BR mandates response_mode=fragment, that URL's parameters live after a '#', not a '?' - copy the complete address bar contents after being redirected, not just the query string. Args: callback_url: The full URL the user's browser landed on after authorizing (or denying) consent at the bank. ctx: MCP request context, providing access to shared dependencies. Returns: The final consent status after completing the exchange.

Completes a payment consent flow using the URL the bank redirected the user to after authorizing (or denying) the payment. Args: callback_url: The full URL the user's browser landed on after authorizing (or denying) the payment consent at the bank. ctx: MCP request context, providing access to shared dependencies. Returns: The final payment consent status after completing the exchange.

Returns the available, blocked, and automatically invested balance of a specific bank account on Open Finance Brasil. Args: subject_id: User's CPF. bank: Identifier of the participating bank. account_id: Account ID returned by list_accounts. ctx: MCP request context, providing access to shared adapters. Returns: The account's current balance.

Returns the bills (open and past) of a credit card via Open Finance Brasil, including total amount, minimum payment, and due date. Args: subject_id: User's CPF. bank: Identifier of the participating bank. credit_card_account_id: ID returned by list_credit_cards. ctx: MCP request context, providing access to shared adapters. Returns: The bills of the given credit card account.

Initiates a PIX payment via Open Finance Brasil. Requires an active payment consent. The idempotency_key field prevents duplicate charges on retries. Outside ``environment='mock'``, requires an ``AUTHORISED`` payment consent for this subject/bank, obtained beforehand via ``start_payment_consent`` + ``complete_payment_consent`` (tools/payments.py) - a data-sharing consent alone is not sufficient. In mock mode this check is skipped entirely, since the mock adapter has no payment-consent resource to check against. Args: subject_id: Payer's CPF. bank: Identifier of the participating bank. amount: Canonical amount in BRL (e.g. ``"150.00"``). creditor_key: PIX key of the recipient. creditor_key_type: Type of the recipient's key. debtor_account_id: ID of the account to debit, returned by list_accounts. idempotency_key: Client-generated UUID to prevent duplicates. ctx: MCP request context, providing access to shared adapters and the persistent idempotency store. description: Payment description/reason (max 140 chars). consent_id: Payment consent returned by ``start_payment_consent``. Required outside mock mode. Returns: Status of the initiated (or previously cached) payment.

Lists all bank accounts (checking, savings, prepaid) of a user at an institution participating in Open Finance Brasil. Args: subject_id: User's CPF (digits only) or internal ID. bank: Identifier of the participating bank. ctx: MCP request context, providing access to shared adapters. Returns: The user's accounts at the given bank.

Lists all credit card accounts of a user at an institution participating in Open Finance Brasil, including available and total credit limit. Args: subject_id: User's CPF. bank: Identifier of the participating bank. ctx: MCP request context, providing access to shared adapters. Returns: The user's credit card accounts at the given bank.

Lists a user's investment fund positions via Open Finance Brasil Fase 4 (P1.3), including quota quantity/price and gross/net amount. Args: subject_id: User's CPF. bank: Participating bank. ctx: MCP request context, providing access to shared adapters. Returns: The user's investment funds and aggregate totals.

Lists a user's bank fixed-income investments (CDB, LCI, LCA, RDB) via Open Finance Brasil Fase 4, including gross amount, net amount, contracted rate, and indexer. Args: subject_id: User's CPF. bank: Participating bank. ctx: MCP request context, providing access to shared adapters. Returns: The user's fixed-income investments and aggregate totals.

Lists the PIX keys (CPF, email, phone, EVP) registered to a bank account via Open Finance Brasil. Only available in environment='mock' - see module docstring. Args: subject_id: User's CPF. bank: Identifier of the participating bank. account_id: Account ID. ctx: MCP request context, providing access to shared adapters. Returns: The PIX keys registered to the given account.

Returns the bank statement of an account on Open Finance Brasil with date and type filters. Supports automatic transaction categorization via AI (categorize=true, requires ANTHROPIC_API_KEY). Args: subject_id: User's CPF. bank: Identifier of the participating bank. account_id: Account ID returned by list_accounts. ctx: MCP request context, providing access to shared adapters and the categorizer. date_from: Start date of the period. date_to: End date of the period. credit_debit_type: Restrict to credits or debits only. page: Page number (1-based). page_size: Records per page (1-1000). categorize: If true, categorizes each transaction via AI. Returns: The account's transactions for the requested period.

Lists a user's treasury bond (Tesouro Direto) positions via Open Finance Brasil Fase 4 (P1.3), including quantity, updated unit price, and gross/net amount. Args: subject_id: User's CPF. bank: Participating bank. ctx: MCP request context, providing access to shared adapters. Returns: The user's treasury bonds and aggregate totals.

Lists a user's variable income asset positions (stocks, ETFs, and other exchange-traded assets) via Open Finance Brasil Fase 4 (P1.3), including quantity, closing price, and gross amount. No net_amount is returned here (unlike list_investments/list_funds/ list_treasure_titles): the real Variable Incomes spec's balance data only publishes a gross amount - taxes/fees on these assets are reported per-transaction (broker notes), not as a running net position. Args: subject_id: User's CPF. bank: Participating bank. ctx: MCP request context, providing access to shared adapters. Returns: The user's variable income assets and an aggregate gross total.

Revokes a user's consent at a bank and forgets the local token. Args: subject_id: User's CPF or internal ID. bank: Identifier of the participating bank. ctx: MCP request context, providing access to shared dependencies. Returns: Confirmation that the consent was revoked.

Starts the Open Finance Brasil consent flow for a user at a bank. Creates a consent resource at the bank, then builds a FAPI-BR compliant (PAR + JAR) authorization URL. The user must open this URL in a browser, log in, and authorize the requested scopes at the bank. Once redirected back, call ``complete_consent`` with the resulting URL to finish the flow. Args: subject_id: User's CPF (digits only) or internal ID. bank: Identifier of the participating bank. scopes: Desired data-sharing scopes, e.g. ['accounts', 'balances', 'transactions', 'overdraft_limits', 'credit_card_accounts', 'credit_card_limits', 'credit_card_bills', 'credit_card_transactions', 'bank_fixed_incomes', 'funds', 'variable_incomes', 'treasure_titles']. Does NOT include 'pix'/payments - payment initiation uses a separate, dedicated payment consent (Payments API), not this data-sharing consent; see tools/pix.py. ctx: MCP request context, providing access to shared dependencies. request_url_elicitation: Ask a compatible MCP client to open the bank authorization URL using URL-mode elicitation. The URL is always returned as well, so clients without elicitation support can continue with the existing copy-and-open flow. Returns: The consent ID and the URL the user must open to authorize it.

Starts the Open Finance Brasil Payments API consent flow for one specific PIX payment. Creates a payment consent describing exactly this payment, then builds a FAPI-BR compliant (PAR + JAR) authorization URL. The user must open this URL, log in, and authorize this specific payment at the bank. Once redirected back, call ``complete_payment_consent`` with the resulting URL, then ``initiate_pix`` to actually create the payment. Args: subject_id: Payer's CPF (digits only) or internal ID. bank: Identifier of the participating bank. amount: Payment amount in BRL (e.g. '150.00'). creditor_key: PIX key of the recipient. creditor_key_type: Type of the recipient's key. debtor_account_id: ID of the account to debit. ctx: MCP request context, providing access to shared dependencies. description: Payment description/reason (max 140 chars). request_url_elicitation: Ask a compatible MCP client to open the bank authorization URL using URL-mode elicitation. The URL is still returned for clients that use the manual flow. Returns: The payment consent ID and the URL the user must open to authorize it.