finary-mcp

A deliberately read-only Model Context Protocol server for Finary, built on top of the unofficial finary-uapi client.

Safety model

finary-mcp is intentionally a narrow, read-only adapter:

• It exposes only profile, organization, institution, portfolio and transaction queries.

• It has no login, account import, create, update, delete, transfer, trade or generic CLI tool.

• It constructs finary-uapi commands from a fixed allowlist, without a shell.

• Filter values are validated before execution.

• It returns no upstream stdout/stderr when a request fails, because an upstream login flow may print session material.

• Its state directory is explicit (FINARY_MCP_STATE_DIR); it does not look for tokens in arbitrary working directories.

This reduces accidental writes through MCP. It does not make a machine safe if another process can read your session files. Run the server only for an account and profile you trust.

Important authentication caveat

“Read-only” refers to Finary portfolio data. finary-uapi refreshes its Clerk session before requests and can rewrite jwt.json; therefore the private state directory must remain writable by the local service account even though no MCP tool changes Finary data. The server never returns that file, cookies, or child-process diagnostics.

finary-uapi also brings fuzzywuzzy as a transitive GPL-2.0 dependency. Review the upstream dependency graph and licensing implications for your intended distribution or deployment.

Related MCP server: C6 Bank MCP

Prerequisites

• Python 3.10+.

• A local Finary session already created by finary-uapi.

• A private directory containing both jwt.json and localCookiesMozilla.txt, mode 0700 for the directory and 0600 for files.

The server does not support Google OAuth itself. Follow the authentication process supported by finary-uapi to create or renew the local session. Never send a password, TOTP code, JWT, cookie export, or session file to an agent, repository, issue tracker, or chat.

Install

python -m venv .venv
. .venv/bin/activate
pip install finary-mcp

For development from a checkout:

pip install -e '.[dev]'
pytest -q

Configure an MCP host

Set FINARY_MCP_STATE_DIR to the directory that holds your Finary session. If finary-uapi is installed in a separate virtual environment, set FINARY_UAPI_PYTHON to that environment's Python executable.

Example generic stdio configuration:

{
  "mcpServers": {
    "finary": {
      "command": "/path/to/finary-mcp/.venv/bin/finary-mcp",
      "env": {
        "FINARY_MCP_STATE_DIR": "/private/path/to/finary-state",
        "FINARY_UAPI_PYTHON": "/path/to/finary-uapi/.venv/bin/python"
      }
    }
  }
}

Use absolute paths. The state directory is private data and must never be committed. The supplied .gitignore excludes the known session files.

Hermes Agent example

mcp_servers:
  finary:
    command: /path/to/finary-mcp/.venv/bin/finary-mcp
    env:
      FINARY_MCP_STATE_DIR: /private/path/to/finary-state
      FINARY_UAPI_PYTHON: /path/to/finary-uapi/.venv/bin/python
    tools:
      include:
        - finary_me
        - finary_organizations
        - finary_institution_connections
        - finary_portfolio
        - finary_transactions

Add this through Hermes' MCP/configuration workflow rather than copying credentials into a public configuration file. Restart the Hermes process after adding a server so tool discovery runs again.

Tools

Dependency: finary-uapi

This project is an adapter, not a reimplementation of Finary's API. It calls the finary-uapi CLI from the lasconic/finary_uapi project, whose package is currently declared in pyproject.toml as finary-uapi>=0.2.3,<0.3.

That dependency uses undocumented Finary endpoints and persists a local session. Review its source and license before using this server. When an upstream upgrade is needed, test it in a separate environment first and pin a compatible version here.

Development

pytest -q
python -m build

Tests use no live Finary account and must not create session files. Before publishing, scan the staged files for jwt.json, localCookiesMozilla.txt, credentials, emails, cookies, and tokens.

License

MIT. See LICENSE.