poke-bank

An MCP server that exposes Enable Banking (EU/Nordic) and Teller (US) as MCP tools for Poke. Provides AI agents with tools to connect bank accounts, list accounts, fetch transactions, and check balances.

Features

• Dual provider support: Enable Banking for EU/Nordic banks, Teller for US banks

• 5 MCP tools: authorize bank connections, list accounts, get transactions, get balances, create sessions

• Automatic callback: Bank redirects back to /callback which auto-completes the session — no manual code copying

• Teller Connect widget: Embedded JS widget at /connect/teller for US bank enrollment (100 free enrollments)

• Encrypted session store: AES-256-GCM encrypted SQLite database for session metadata

• Bearer token auth: Secure the server with MCP_API_KEY so only you can use it

• Poke webhook: Automatically notifies Poke when a bank account is connected

Quick Start

Prerequisites: Python 3.10+ and Node.js 18+ (which includes npx and npm).

git clone https://github.com/kacperkwapisz/poke-bank.git
cd poke-bank

If you haven't logged into Poke yet, do that first — start.sh will pick up your token automatically:

npx poke login

Then just run:

./start.sh

On the first run, start.sh automatically handles the full setup:

1. Creates a Python virtualenv and installs dependencies

2. Copies .env.example → .env

3. Reads your Poke API key from poke login credentials and injects it into .env

4. Generates a random MCP_API_KEY and SESSION_ENCRYPTION_KEY and saves them to .env

5. Prompts you for your ENABLE_BANKING_APP_ID (or you can set it manually in .env later)

6. Immediately starts the server and tunnel

After the first run, open .env and fill in your provider credentials — Enable Banking (ENABLE_BANKING_APP_ID, ENABLE_BANKING_PRIVATE_KEY, ENABLE_BANKING_REDIRECT_URI) for EU/Nordic banks and/or Teller (TELLER_APP_ID, TELLER_CERT, TELLER_KEY) for US banks — then run ./start.sh again.

On subsequent runs, start.sh skips setup and goes straight to starting the server and tunnel.

AI coding agent setup

Copy this prompt into your AI coding agent (Claude Code, Cursor, etc.):

Set up poke-bank (https://github.com/kacperkwapisz/poke-bank) for me — clone the repo, run 'npx poke login' so I can authenticate with Poke (wait for me to confirm), then run './start.sh' which will automatically wire up my Poke API key, generate an MCP_API_KEY and SESSION_ENCRYPTION_KEY, set up the virtualenv, and start the server and tunnel. Before configuring bank providers, ask me: "Do you want to connect US banks, EU/Nordic banks, or both?" Then only set up what I choose. For EU/Nordic banks (Enable Banking): guide me to https://enablebanking.com to create an application, generate an RSA key pair (openssl genrsa -out private.pem 2048 && openssl rsa -in private.pem -pubout -out public.pem), upload the public key to the dashboard, copy the Application ID into ENABLE_BANKING_APP_ID, and set ENABLE_BANKING_REDIRECT_URI to https://<my-domain>/callback. For US banks (Teller): guide me to https://teller.io to create an application, copy the Application ID into TELLER_APP_ID, and download the mTLS certificate (teller.zip) — extract certificate.pem and private_key.pem and set TELLER_CERT and TELLER_KEY to their paths (not needed for sandbox mode). Do NOT type passwords or secrets, tell me to enter those myself and confirm when done; if the server fails due to missing credentials, have me update .env and run './start.sh' again.

Enable Banking Setup

To use poke-bank, you need credentials from Enable Banking:

1. Create an account at enablebanking.com and create a new application

2. Generate an RSA key pair for JWT signing:

   openssl genrsa -out private.pem 2048
   openssl rsa -in private.pem -pubout -out public.pem

3. Upload public.pem to the Enable Banking dashboard under your application

4. Copy the Application ID (a UUID) — this is your ENABLE_BANKING_APP_ID

5. Set the redirect URI in the dashboard to https://<your-domain>/callback — this must match ENABLE_BANKING_REDIRECT_URI in .env

6. Add credentials to .env:

   ENABLE_BANKING_APP_ID=<your-application-uuid>
   ENABLE_BANKING_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----
   ENABLE_BANKING_REDIRECT_URI=https://your-domain.com/callback

Note: You can also point ENABLE_BANKING_PRIVATE_KEY to the PEM file path instead of inlining the key.

Teller Setup (US Banks)

To connect US bank accounts, you need a Teller application:

1. Create an account at teller.io and create a new application

2. Copy your Application ID — this is your TELLER_APP_ID

3. Download your mTLS certificate — teller.zip was downloaded when you signed up (contains certificate.pem and private_key.pem). If lost, regenerate from the Certificates section of the Teller Dashboard.

4. Add credentials to .env:

   TELLER_APP_ID=app_xxxxx
   TELLER_ENV=sandbox          # sandbox | development | production
   TELLER_CERT=/path/to/certificate.pem   # required for development/production
   TELLER_KEY=/path/to/private_key.pem    # required for development/production

Note: Sandbox mode works without mTLS certificates and provides test data. You get 100 free enrollments on the developer plan.

Note: You can also inline the PEM strings directly in TELLER_CERT and TELLER_KEY instead of pointing to file paths (use \n for newlines).

Manual Setup

1. Configure .env

cp .env.example .env

Edit .env with your Enable Banking credentials, then generate the required keys:

# MCP_API_KEY
openssl rand -hex 32

# SESSION_ENCRYPTION_KEY (64 hex chars)
python3 -c "import secrets; print(secrets.token_hex(32))"

2. Install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Run

source .venv/bin/activate
python3 src/server.py

4. Test

npx @modelcontextprotocol/inspector

Open http://localhost:6274 and connect to http://localhost:3000/mcp using "Streamable HTTP" transport. Pass Authorization: Bearer <your-MCP_API_KEY> header.

Authentication

Set MCP_API_KEY to secure the server. All requests must include Authorization: Bearer <MCP_API_KEY>.

When running via start.sh (which uses poke tunnel), set POKE_TUNNEL=1 to make MCP_API_KEY optional — the tunnel handles authentication. start.sh sets this automatically.

If MCP_API_KEY is not set and POKE_TUNNEL is not 1, the server runs unauthenticated (with a warning). Always set it in non-tunnel deployments.

Enable Banking uses JWT-based authentication (not OAuth2 client credentials). Your application signs short-lived JWTs with the RSA private key registered in the Enable Banking dashboard. These JWTs are sent as Bearer tokens on every API request.

Docker

docker compose up -d

Or use the pre-built image from GitHub Container Registry:

docker run -d \
  -p 3000:3000 \
  --env-file .env \
  -v poke-bank-data:/data \
  ghcr.io/kacperkwapisz/poke-bank:main

Resource Limits

The server is mostly idle (lightweight HTTP + on-demand banking API calls). Recommended limits for container orchestrators:

Routes

All other paths return 404.

MCP Tools

Environment Variables

Authorization Flow

Enable Banking (EU/Nordic)

1. Call get_auth_url with the bank name and country code

2. Open the returned auth_url in a browser and authorize

3. The bank redirects to /callback which auto-completes the session — no manual code copying needed

4. Use list_accounts, get_transactions, get_balances with the session_id

Fallback: If the callback redirect doesn't work, you can also manually copy the code from the redirect URL and call create_session with the code and session_id.

Teller (US)

1. Call get_auth_url with provider='teller'

2. Open the returned auth_url — the Teller Connect widget loads in the browser

3. User authenticates with their bank through the widget

4. On success, the page POSTs enrollment data to /callback/teller and shows "Connected"

5. Use list_accounts, get_transactions, get_balances with the session_id

If POKE_WEBHOOK_URL and POKE_API_KEY are set, a webhook is sent to Poke when a bank account is successfully connected (for both providers).

Session Store

Session metadata (authorization IDs, account lists) is stored in an encrypted SQLite database at /data/sessions.db inside the container (or ./sessions.db when running locally via start.sh). The poke-bank-data Docker volume persists this across restarts.

All session data is encrypted with AES-256-GCM using the SESSION_ENCRYPTION_KEY. The key never leaves your server.

Poke Setup

Connect your MCP server to Poke at poke.com/settings/connections. Add the bearer token (MCP_API_KEY) in the connection auth settings.

When a bank account is connected, poke-bank can automatically notify Poke via webhook. Set POKE_WEBHOOK_URL and POKE_API_KEY in .env to enable this.

License

MIT