# Open Finance

Open Finance is a local MCP complement for asking Codex or Claude Code about your bank balances, movements, and spending. Each person runs the MCP server on their own computer. The Enable Banking signing key and encrypted SQLite database remain local; financial results requested in a conversation are sent to that AI client and may reach its model.

**Status:** early open-source prototype. The MCP protocol, demo cards, local onboarding, and one real bank consent and balance retrieval have been verified. Broader bank coverage remains untested.

## Install

Install only the plugin. It needs Node.js 18 or newer on your `PATH` to launch its local MCP server. On the first run, the plugin downloads the native binary for your operating system from the pinned [v0.1.2 release](https://github.com/j0nl1/open-finance/releases/tag/v0.1.2), checks both archive and binary against SHA-256 hashes included in the plugin, and caches it for later runs. Supported targets are macOS and Linux on ARM64 or x64, and Windows on x64. No separate install script or `open-finance-mcp` command on your `PATH` is needed. Restart the AI client after adding the plugin.

### Codex

```sh
codex plugin marketplace add j0nl1/open-finance
codex plugin add open-finance@open-finance
```

### Claude Code

```sh
claude plugin marketplace add j0nl1/open-finance
claude plugin install open-finance@open-finance
```

The plugin package lives in [`plugin/`](plugin/). Its portable `plugin.json` and `mcp.json` serve Codex; its `.claude-plugin/plugin.json` and `.mcp.json` serve Claude Code. Both launch the same verified binary through [`runtime/launch.mjs`](plugin/runtime/launch.mjs) and use [`skills/open-finance/SKILL.md`](plugin/skills/open-finance/SKILL.md). The binary cache is separate from the financial data in `~/.open-finance/`. A client that does not render MCP App cards can still use the text tool responses.

## Connect a bank

Ask your assistant to use Open Finance's `setup_status` tool. A new installation can generate an RSA signing key and public certificate locally with `prepare_enable_banking`. Register your own Enable Banking application using the public certificate and `https://127.0.0.1:3000/callback` as a redirect URL, then supply its application ID to `configure_enable_banking`. The private key never belongs in chat or the repository. If you already have a registered application, the setup flow can reuse its existing key.

A restricted Enable Banking application can access only accounts linked to that application. Linking an account in Enable Banking does not grant API consent to Open Finance. Run `list_banks`, choose the exact bank name with `connect_bank`, open the short-lived authorization URL, and approve access at the bank. The local MCP process handles the HTTPS callback on `127.0.0.1:3000`. Its self-signed loopback certificate may require a browser trust exception. Verify the result with `list_accounts` and `get_balances` before relying on any answer.

Ask for `spending_summary` for a calendar month (`YYYY-MM`); set `refresh` to fetch booked movements first. For an initial multi-month report, use `sync_history` with the earliest requested month. Enable Banking's `longest` strategy discovers the history the bank actually provides; older missing months must not be reported as zero. The server stores provider references and movement details encrypted. It separates currencies, treats unknown debits as provisional unclassified expenses, and supports explicit category corrections and saved counterparty rules. There is no AI classifier yet. An empty unsynced month does not prove zero spending.

Local data is stored under `~/.open-finance/` by default. The demo MCP server uses synthetic data in a separate directory and never connects to a bank.

## Development

Requirements for building from source: Rust 1.94 or newer, Bun 1.3.8, and a C toolchain. On macOS, [`scripts/run-mcp.sh`](scripts/run-mcp.sh) selects the installed Command Line Tools for local builds.

```sh
bun install --frozen-lockfile
bun run build:mcp-app
bun run typecheck
bun run lint
bun run format:check
cargo fmt --all --check
cargo test --locked --workspace
sh scripts/run-mcp.sh
```

The MCP App card source is in [`src/mcp-app/`](src/mcp-app/); its single-file build is committed at [`crates/mcp/assets/index.html`](crates/mcp/assets/index.html) for binary builds. Ports and domain types are in [`crates/core/`](crates/core/), with SQLite and Enable Banking adapters in [`crates/adapters/`](crates/adapters/). [`crates/mcp/`](crates/mcp/) owns the local runtime and MCP tools.

Do not commit real account data, application keys, local databases, or authorization URLs. Read [CONTRIBUTING.md](CONTRIBUTING.md) before sending a change.

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).