Open Banking (open-banking.io)
Read-only MCP server for the open-banking.io PSD2 bank API — accounts, balances, transactions.
Open source Open in the app JSON README (API)
About
Read-only MCP server for the open-banking.io PSD2 bank API — accounts, balances, transactions.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- open-banking-io
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Last push
- 2026-08-20T07:14:02Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:58
- Updated
- 2026-08-29 04:00:58
- Origin id
io.github.open-banking-io/mcp-server
README
# open-banking.io MCP server
A thin, **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server for the
[open-banking.io](https://open-banking.io) PSD2 API. It lets AI agents (Claude Desktop, Cursor,
any MCP client) answer questions like *“What's my balance?”* and *“Summarise last month's
transactions”* over your own bank accounts.
It wraps the official [`open-banking-io`](https://github.com/open-banking-io/clients) Python SDK
and inherits its **zero-knowledge** property: the service only ever returns ciphertext, and every
sensitive field (IBAN, owner name, amounts, counterparties) is decrypted **in-process** with your
exported private key. No plaintext ever touches a third party — including the LLM only sees what
your MCP client sends it.
## Tools
| Tool | Arguments | Description |
|---|---|---|
| `list_accounts` | — | Bank accounts: bank, country, IBAN, owner, display name, currency, balances, `needs_reconnect` flag |
| `get_balances` | `account_id` | ISO 20022 balances for one account (`ITBD` = booked, `ITAV` = available) |
| `get_transactions` | `account_id`, `date_from?`, `date_to?`, `limit?` (default 50, max 500), `offset?` | Statement lines, newest first, with counterparty and remittance details |
| `list_connections` | — | Bank connections/consents: status, `valid_until`, `last_synced_at`, account count |
All tools are **read-only**. There are intentionally no sync, payment-initiation or consent-management
tools — see [Limitations](#limitations).
## Configuration
| Env var | Required | Meaning |
|---|---|---|
| `OBI_CREDENTIALS` | preferred | Path to (or inline JSON of) the credentials bundle exported from the open-banking.io app — contains `apiBaseUrl`, `apiKey` and the encryption private key |
| `OBI_API_KEY` | alternative | API key, if you don't use the bundle |
| `OBI_PRIVATE_KEY` | alternative | Base64 PKCS#8 EC (SECP256R1) private key matching `OBI_API_KEY` |
| `OBI_BASE_URL` | with alternative | API base URL (the bundle's `apiBaseUrl`), required when using the split env vars |
Export credentials in the app → *Settings → Credentials* to get the bundle file.
### Claude Desktop
`claude_desktop_config.json` (Claude → Settings → Developer → Edit Config):
```json
{
"mcpServers": {
"open-banking-io": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/open-banking-io/mcp-server.git",
"obi-mcp"
],
"env": {
"OBI_CREDENTIALS": "/absolute/path/to/credentials.json"
}
}
}
}
```
### Cursor
`.cursor/mcp.json`:
```json
{
"mcpServers": {
"open-banking-io": {
"command": "uvx",
"args": [
"--from", "git+https://github.com/open-banking-io/mcp-server.git",
"obi-mcp"
],
"env": {
"OBI_CREDENTIALS": "/absolute/path/to/credentials.json"
}
}
}
}
```
Requires [`uv`](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`).
Once published to PyPI the `--from git+…` argument can be dropped.
### Run locally / from source
```bash
git clone https://github.com/open-banking-io/mcp-server.git
cd mcp-server
uv venv && uv pip install -e '.[dev]' --python .venv/bin/python
OBI_CREDENTIALS=/path/to/credentials.json .venv/bin/obi-mcp # speaks MCP over stdio
.venv/bin/python tests/smoke.py # network-free smoke test
uv run --python .venv/bin/python pytest -q # full test suite
```
## Example questions for your agent
- “Show the booked balance of every account.”
- “How much did I spend on groceries in July?” (`get_transactions` + grouping)
- “Which of my bank connections expire soon?” (`list_connections`)
## Design notes
- **Read-only by construction.** Only the SDK's `get_*` methods are exposed. `sync`/`sync_all`
exist in the SDK but are deliberately not offered; agents cannot move money or alter consents
through this server.
- **Exact money.** Amounts are returned as exact decimal strings (`"1234.56"`), never floats.
- **Clean errors.** Missing credentials, bad dates, unknown account ids and upstream HTTP errors
are surfaced as actionable tool errors (e.g. listing valid account ids on a miss).
- **Context-friendly.** `get_transactions` defaults to 50 items and clamps at 500 to protect
agent context windows; use `offset` to paginate.
## Limitations (honest list)
- No write tools: no sync, no payment initiation, no consent creation/renewal. Consent renewal
always happens in the open-banking.io app (PSD2 SCA).
- No bank/institution directory tool: the upstream API (SDK v1.0.0) does not expose a public
ASPSP-search endpoint — TODO if/when the API adds one.
- Not yet on PyPI — install via `uvx --from git+…` (above) or from source. Publishing to PyPI as
`open-banking-io-mcp` is planned.
- Data minimisation is your responsibility: transactions include counterparties and remittance
text; only point this server at MCP clients you trust, and prefer local MCP clients
(Claude Desktop / Cursor) over hosted ones for privacy.
## API surface wrapped
| SDK call | HTTP (behind the SDK) |
|---|---|
| `get_accounts()` | `GET {apiBaseUrl}/api/accounts` |
| `get_transactions(id, from, to, limit, offset)` | `GET {apiBaseUrl}/api/accounts/{id}/transactions` |
| `get_connections()` | `GET {apiBaseUrl}/api/connections` |
Auth: `X-Api-Key` header. Responses carry zero-knowledge envelopes
(ECDH P-256 → HKDF-SHA256 → AES-256-GCM) decrypted locally by the SDK.
Full wire format: [`clients` repo](https://github.com/open-banking-io/clients) ·
[`THREAT_MODEL.md`](https://github.com/open-banking-io/clients/blob/main/THREAT_MODEL.md).
## License
MIT — same as the [`clients`](https://github.com/open-banking-io/clients) SDK repos.