Skip to main content
Glama
Open Finance US MCP

Open Finance US MCP

by orancummins

Open Finance US MCP

A standalone Model Context Protocol server that wraps the Mastercard Open Finance US (Finicity) hosted APIs (https://api.finicity.com). It is a separate codebase from Vima and vendors its own Finicity client — no dependency on Vima's apis/, execute() wrapper, or simulator.

Open Finance MCP Console

Layout

openfinance-mcp/
  src/openfinance_mcp/
    finicity_client.py   # vendored Finicity client (only depends on requests)
    server.py            # FastMCP server + tools
    models.py            # ToolResult envelope
    spec_defaults.py     # resolved spec decisions + open questions
    config/settings.py   # credential loader (env / dotenv / sibling vima config/.env)
    __main__.py          # stdio + streamable-http entry point
  tests/                 # unit, protocol (offline) + sandbox (live) suites
  console/               # separate, independently deployable demo UI
  run.sh / run.bat       # one-shot start scripts for the MCP server
  console/run.sh / .bat  # one-shot start scripts for the Test Console

Related MCP server: Local Financial MCP Mock Server

1 — Get Credentials

Credentials are issued through the Mastercard Developers portal.

  1. Sign up or log in at developer.mastercard.com.

  2. Click Create New Project, enter a project name, and select Open Finance from the Select your API service dropdown.

  3. Select the commercial country for your end users, then click Proceed.

  4. Enter a description, click Create Project.

  5. In the left-hand Credentials panel click Sandbox — your three credential values are shown:

    Variable

    Portal label

    OPEN_FINANCE_PARTNER_ID

    Partner ID

    OPEN_FINANCE_PARTNER_SECRET

    Secret

    OPEN_FINANCE_APP_KEY

    App Key

Full quick-start guide: https://developer.mastercard.com/open-banking-us/documentation/quick-start-guide/

API base URL defaults to https://api.finicity.com. Override with OPEN_FINANCE_API_BASE_URL if needed.


2 — Configure Credentials

Start the console (see below), then click the ⚙ Credentials button in the top-right corner. Paste your values and click Save to .env. The file is written to .env in the repo root.

Option B — Edit .env directly

Create .env in the repo root:

OPEN_FINANCE_PARTNER_ID=your_partner_id
OPEN_FINANCE_PARTNER_SECRET=your_partner_secret
OPEN_FINANCE_APP_KEY=your_app_key
OPEN_FINANCE_API_BASE_URL=https://api.finicity.com

Resolution order

  1. Process environment variables.

  2. OPENFINANCE_MCP_ENV_FILE (explicit dotenv path).

  3. .env in this repo root.

  4. Sibling ../vima/config/.env (auto-discovered).


3 — Start the MCP Server

The run scripts create a .venv, install dependencies, kill any previous instance, and start the server — no manual pip install required.

macOS / Linux

./run.sh
# Defaults: transport=http, host=0.0.0.0, port=9030

Windows

run.bat

Override defaults via environment variables:

PORT=9030 TRANSPORT=http ./run.sh

Manual (without the script)

python -m venv .venv && source .venv/bin/activate
pip install -e ".[test,console]"
python -m openfinance_mcp --transport http --port 9030

4 — Start the Test Console

macOS / Linux

./console/run.sh
# open http://localhost:8080

Windows

console\run.bat

Override defaults:

PORT=8080 MCP_URL=http://localhost:9030/mcp ./console/run.sh

Manual

cd console
pip install -r requirements.txt
MCP_URL=http://localhost:9030/mcp uvicorn app:app --port 8080

Or start both MCP server and console together with Docker:

docker compose up --build

5 — Run Tests

# Offline unit + protocol tests (no credentials needed)
pytest -m "not sandbox"

# Live sandbox tests (requires valid credentials in .env)
pytest -m sandbox

Project layout (detail)

openfinance-mcp/
  src/openfinance_mcp/
    finicity_client.py
    server.py
    models.py
    spec_defaults.py
    config/settings.py
    __main__.py
  tests/
  console/
    app.py              # FastAPI bridge (MCP client → browser)
    static/             # index.html, console.js, console.css
    run.sh / run.bat
  docs/
    console-screenshot.png
  run.sh / run.bat
  docker-compose.yml
  pyproject.toml

Resolved spec decisions

Question

Answer

Status

PSI path/body

POST /payments/customers/{id}/accounts/{aid}/payment-success-indicators, {"transaction":{"settleByDate","amount"}}

confirmed

VOAI slug

voaHistory

confirmed

TxPUSH body

{"callbackUrl": <url>}

confirmed

The console's Spec Decisions tab renders these live from the running server.

Available Tools

62 tools
account_owner_matchC

Match provided identity details against account owner records.

Inputs: account_id (required), customer_id (required), email, phone, +2 more. Returns: ok, data, error, status_code

create_access_tokenA

Force-create a Finicity App-Token; use this to verify credentials work.

Inputs: no named parameters. Returns: ok, data, error, status_code

create_active_customerB

Create an active (billable) customer for production use.

Inputs: username (required), last_name, first_name. Returns: ok, data, error, status_code

create_businessC

Create a business record for a customer.

Inputs: customer_id (required), business_name (required), business_type. Returns: ok, data, error, status_code

create_consumerB

Create a consumer record (prerequisite for VOA/VOI/VOAI reports).

Inputs: last_name (required), first_name (required), customer_id (required), ssn, +1 more. Returns: ok, data, error, status_code

create_testing_customerA

Create a Finicity testing customer (sandbox, non-billable).

Inputs: username (required). Returns: ok, data, error, status_code

delete_customerB

Delete a customer and all associated data. Destructive.

Inputs: customer_id (required). Returns: ok, data, error, status_code

delete_customer_accountC

Remove access to a single account. Destructive.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

disable_txpushC

Disable TxPUSH notifications for an account.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

enrich_transactionsC

Enrich a list of raw transactions with categorization/merchant data.

Inputs: transactions (required). Returns: ok, data, error, status_code

generate_balance_analytics_reportD

Generate a Balance Analytics report.

Inputs: customer_id (required), user_type, account_ids. Returns: ok, data, error, status_code

generate_cashflow_analytics_reportD

Generate a Cash Flow Analytics report.

Inputs: customer_id (required), user_type, account_ids. Returns: ok, data, error, status_code

generate_cash_flow_business_reportC

Generate a business Cash Flow report.

Inputs: customer_id (required), account_ids. Returns: ok, data, error, status_code

generate_cash_flow_personal_reportC

Generate a personal Cash Flow report.

Inputs: customer_id (required), account_ids. Returns: ok, data, error, status_code

generate_connect_urlC

Generate a hosted Data Connect URL for the customer to link accounts.

Inputs: customer_id (required), experience. Returns: ok, data, error, status_code

generate_fcra_payment_success_indicatorsC

Generate FCRA-permissible Payment Success Indicators.

Inputs: amount (required), account_id (required), customer_id (required), purpose, +1 more. Returns: ok, data, error, status_code

generate_fix_connect_urlB

Generate a Fix Data Connect URL to repair a broken connection.

Inputs: customer_id (required), institution_login_id (required). Returns: ok, data, error, status_code

generate_lite_connect_urlC

Generate a Lite Data Connect URL scoped to one institution.

Inputs: customer_id (required), institution_id (required). Returns: ok, data, error, status_code

generate_payment_success_indicatorsC

Generate Non-FCRA Payment Success Indicators for a proposed payment.

Inputs: amount (required), account_id (required), customer_id (required). Returns: ok, data, error, status_code

generate_transactions_reportC

Generate a Transactions report over an epoch-second date range.

Inputs: to_date (required), from_date (required), customer_id (required), account_ids. Returns: ok, data, error, status_code

generate_voai_reportC

Generate a VOA-with-Income (voaHistory) report.

Inputs: customer_id (required), from_date, account_ids. Returns: ok, data, error, status_code

generate_voa_reportC

Generate a Verification of Assets (VOA) report.

Inputs: customer_id (required), from_date, account_ids. Returns: ok, data, error, status_code

generate_voi_reportC

Generate a Verification of Income (VOI) report.

Inputs: customer_id (required), account_ids. Returns: ok, data, error, status_code

get_account_ach_detailsC

Get ACH routing/account number details for an account.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

get_account_ownerC

Get account owner (name/address) information.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

get_account_owner_detailsC

Get detailed (v3) account owner information.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

get_account_payment_detailsC

Get ACH details incl. RTP/FedNow support (v3).

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

get_account_statementC

Get an account statement PDF (returned base64-encoded).

Inputs: account_id (required), customer_id (required), index. Returns: ok, data, error, status_code

get_account_transactionsC

Get transactions for a single account. Dates are epoch seconds.

Inputs: to_date (required), from_date (required), account_id (required), customer_id (required), +2 more. Returns: ok, data, error, status_code

get_available_balanceC

Get the real-time available balance for an account.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

get_bill_pay_switchesC

List bill-pay switches for a customer.

Inputs: customer_id (required). Returns: ok, data, error, status_code

get_business_for_customerC

Get the business record for a customer.

Inputs: customer_id (required). Returns: ok, data, error, status_code

get_certified_institutionsC

List certified institutions.

Inputs: limit, start, search. Returns: ok, data, error, status_code

get_consumerB

Get a consumer record by consumer id.

Inputs: consumer_id (required). Returns: ok, data, error, status_code

get_consumer_for_customerB

Get the consumer record associated with a customer.

Inputs: customer_id (required). Returns: ok, data, error, status_code

get_customerB

Fetch a single customer by id.

Inputs: customer_id (required). Returns: ok, data, error, status_code

get_customer_accountC

Fetch one account for a customer.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

get_customer_accountsB

List all linked accounts for a customer.

Inputs: customer_id (required). Returns: ok, data, error, status_code

get_customer_transactionsB

Get transactions across all of a customer's accounts. Dates are epoch seconds.

Inputs: to_date (required), from_date (required), customer_id (required), limit, +1 more. Returns: ok, data, error, status_code

get_deposit_switchesB

List direct-deposit switches for a customer.

Inputs: customer_id (required). Returns: ok, data, error, status_code

get_fcra_payment_success_indicatorsD

Retrieve an FCRA PSI result by payRequestId.

Inputs: account_id (required), customer_id (required), pay_request_id (required). Returns: ok, data, error, status_code

get_institutionC

Get details for one institution.

Inputs: institution_id (required). Returns: ok, data, error, status_code

get_institution_brandingC

Get an institution's branding assets.

Inputs: institution_id (required). Returns: ok, data, error, status_code

get_institutions_by_routing_numberB

Look up institutions by ABA routing number.

Inputs: routing_number (required). Returns: ok, data, error, status_code

get_loan_payment_detailsC

Get loan payment details for a loan-type account.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

get_micro_deposit_detailsC

Get the status/details of a micro-deposit verification.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

get_payment_success_indicatorsC

Retrieve a previously generated PSI result by payRequestId.

Inputs: account_id (required), customer_id (required), pay_request_id (required). Returns: ok, data, error, status_code

get_recurring_transactionsC

Detect recurring transactions (subscriptions, salary, etc.).

Inputs: customer_id (required), account_ids. Returns: ok, data, error, status_code

get_reportC

Fetch a generated decisioning report by id.

Inputs: report_id (required), purpose_code. Returns: ok, data, error, status_code

get_report_by_customerC

Fetch a report scoped to a specific customer.

Inputs: report_id (required), customer_id (required), purpose_code. Returns: ok, data, error, status_code

get_reports_by_customerC

List all reports generated for a customer.

Inputs: customer_id (required). Returns: ok, data, error, status_code

initiate_micro_depositsC

Initiate micro-deposit account verification.

Inputs: receiver (required), customer_id (required), callback_url. Returns: ok, data, error, status_code

list_customersC

List customers, optionally filtered by username search.

Inputs: limit, start, search. Returns: ok, data, error, status_code

list_finbank_profilesA

List the verified FinBank sandbox test profiles for headless linking.

Inputs: no named parameters. Returns: ok, data, error, status_code

load_historic_transactionsC

Load up to 24 months of historic transactions for an account.

Inputs: account_id (required), customer_id (required). Returns: ok, data, error, status_code

refresh_customer_accountsC

Trigger an aggregation refresh for all of a customer's accounts.

Inputs: customer_id (required). Returns: ok, data, error, status_code

run_happy_pathA

Run a full sandbox happy path end-to-end and return every step.

Steps: create testing customer -> link FinBank accounts -> list accounts -> fetch transactions. Sandbox only; uses headless linking (no browser).

Inputs: profile_key. Returns: ok, data, error, status_code

search_institutionsC

Search supported financial institutions.

Inputs: limit, start, search. Returns: ok, data, error, status_code

subscribe_txpushC

Subscribe an account to TxPUSH webhook notifications.

Inputs: account_id (required), customer_id (required), callback_url (required). Returns: ok, data, error, status_code

update_customerC

Update a customer's profile fields.

Inputs: customer_id (required), email, last_name, first_name. Returns: ok, data, error, status_code

verify_micro_depositsC

Verify the two micro-deposit amounts.

Inputs: amounts (required), account_id (required), customer_id (required). Returns: ok, data, error, status_code

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 62 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, with clear differentiation even among similar operations (e.g., generate_voi_report vs generate_voa_report). Overlapping concepts like payment indicators are separated by FCRA vs non-FCRA. No two tools have ambiguous boundaries.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, with verbs like create, get, list, delete, generate, refresh, etc. There are no mixed conventions or inconsistent verb styles. A clear, predictable naming scheme throughout.

    Tool Count2/5

    With 62 tools, this server far exceeds the typical well-scoped range of 3-15. While the domain is broad, the quantity is overwhelming for a single MCP server and could hinder agent navigation. A more modular split would improve coherence.

    Completeness5/5

    The tool surface covers the full lifecycle of customers, accounts, transactions, reports, institutions, consumers, payment indicators, micro-deposits, businesses, and testing utilities. There are no obvious gaps; every core open banking operation is represented.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that exposes Enable Banking API tools for interacting with bank accounts through Open Banking. It enables users to authenticate sessions, list accounts, and fetch transaction history or balances via a secure self-hosted server.
      2
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A lightweight MCP server that simulates financial data interactions with dummy authentication and static JSON datasets for testing financial applications.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for personal finance via Open Finance, consolidating accounts and cards and answering spending questions with aggregated numbers. Provides tools for category spending, recurring subscriptions, budgets, card bills, and installment forecasts, with data stored locally in an encrypted SQLite database.
      2
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for read-only access to bank accounts via Open Banking (DSP2/AIS). It retrieves balances, transactions, and forecasts upcoming debits to prevent overdrafts, with optional daily Todoist briefs.
      6
      1
      MIT