MainBook Bank Statement Converter

MainBook Bank Statement Converter

A finance MCP server scoped to one job: turning PDF bank statements into checked JSON, Excel or CSV — not a general accounting MCP. It runs locally after one mainbook-mcp auth login, or over MainBook's hosted endpoint at https://mcp.mainbook.ai/mcp, where your client signs you in with your MainBook account. Existing mb_live_ API keys keep working for scripts and older clients.

Point your assistant at a statement and ask for a spreadsheet. The PDF goes to MainBook, which extracts every transaction, normalises dates to YYYY-MM-DD, keeps money as exact amounts, and re-adds the statement so that opening balance + credits − debits has to match the closing balance. Rows that do not fit are flagged instead of being passed on quietly.

> Convert ~/Downloads/march-statement.pdf and save the Excel next to it.

mainbook - convert_bank_statement (MCP) 63 transactions · 4 pages · 4 credits Totals reconciled against the statement Saved to ~/Downloads/march-statement.xlsx

Done — 63 transactions. Opening 4,127.50 and closing 3,881.05 both match the statement, and nothing was flagged.

What it is not

It does not connect to bank accounts and is not an Open Banking or bank-data API. It reads statement files you already have. Nothing is scraped and no banking credentials are involved.

What you need

A MainBook account and the folders holding your statements. Conversion is the only tool that spends page credits. Of the other four, get_balance and list_conversions only read, get_conversion may write a result file, and output_folder changes a local preference; none of them changes anything in your MainBook account.

Add it to your client

Sign in once from a terminal:

uvx mainbook-mcp auth login

The command opens MainBook in your browser, shows the same short code in both places, and waits for your approval. It stores the credential in the OS keyring when the optional keyring package is installed and working. Otherwise it uses ~/.config/mainbook/credentials.json with private directory and file permissions. Use mainbook-mcp auth status to check the active credential server-side without spending page credits. mainbook-mcp auth logout revokes that stored key first, then removes the local copy; if MainBook cannot be reached, it says plainly that the key may still be active. Signing in again revokes the previously stored key before saving its replacement. The device token response does not include an email or account ID, so status says that account identity was not provided instead of guessing.

Then add one entry to your client's MCP configuration. This is the same block for Claude Desktop (Settings → Developer → Edit Config), Claude Code, and Cursor; no key is copied into it:

{

"mcpServers": { "mainbook": { "command": "uvx", "args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"] } } }

Codex reads TOML, so put the same thing in ~/.codex/config.toml:

[mcp_servers.mainbook]

command = "uvx" args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]

uvx comes with uv; install it once with brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh. It fetches and runs the published package, so there is nothing to download by hand and nothing to update. If you would rather not add uv, run pip install mainbook-mcp and use "command": "mainbook-mcp" with the same arguments — you then upgrade it yourself with pip install -U mainbook-mcp.

The folder arguments are the only places the server may read a statement from or write a result to; anything outside them is refused. MAINBOOK_ALLOWED_DIRS sets the same list through the environment instead, separated by the platform's os.pathsep (: on macOS/Linux, ; on Windows).

Manual API key for scripts and CI

MAINBOOK_API_KEY takes precedence over any stored login. Keep the manual method for automation where an interactive browser is not available. auth login warns when this variable will keep overriding the newly stored credential:

export MAINBOOK_API_KEY="mb_live_REPLACE_ME"

mainbook-mcp

Create and revoke manual keys at https://mainbook.ai/developer. Never commit them.

Claude Desktop, without touching a config file

Claude Desktop also accepts a one-file bundle: Extensions → Install Extension… and pick mainbook.mcpb. It asks for the API key and the folders in a dialog and manages its own Python runtime, so nothing needs installing first. The config block above does the same job and is the better fit if you already keep other servers there. Build the bundle from this directory with:

npx --yes @anthropic-ai/mcpb@2.1.2 validate manifest.json

npx --yes @anthropic-ai/mcpb@2.1.2 pack . dist/mainbook.mcpb

What it exposes

• convert_bank_statement: creates a paid page-credit job, uploads one PDF, starts conversion, polls for up to 30-900 seconds, and returns the reviewed result. JSON stays inline. In local stdio mode, XLSX/CSV bytes are written to disk and only the full path enters model context.
• get_conversion: checks a job after a timeout and returns JSON inline or writes XLSX/CSV to a chosen local destination.
• list_conversions: returns one cursor page of account jobs plus next_cursor.
• get_balance: returns total, reserved, and available credits, all measured in PDF pages.
• output_folder: reads or changes the default local result folder.

Local stdio mode lists all five tools. Hosted HTTP mode lists exactly the first four; output_folder is not advertised remotely because the server's disk does not belong to the client.

There are no tools for buying credits, payments, deleting jobs, or changing account data. Tools that can create a conversion, write a local result file, or change the output preference are marked non-read-only. get_conversion is read-only over hosted HTTP, where it writes no file, and non-read-only over local stdio, where it may write XLSX or CSV. None is marked destructive because existing result files are never replaced.

Where result files go

For local stdio clients (Claude Desktop, Claude Code, Cursor, and Codex), XLSX and CSV results are written to the first available destination in this order:

1. output_path supplied to convert_bank_statement or get_conversion (an absolute filename or an existing folder);
2. the folder remembered by output_folder;
3. next to the source PDF, with the same base name and the result extension.

get_conversion cannot infer the original PDF folder. Without output_path or a valid remembered folder it returns a clear error instead of guessing a destination. Every successful file response contains the absolute path and explains which rule selected it. Existing files are never replaced: statement.xlsx is followed by statement (2).xlsx, then (3), and so on.

Ask the client to call output_folder with no argument to see the current setting and every allowed folder. Set it with an allowed absolute directory, or pass next_to_source to restore the default. The preference is shared by local clients on the same machine in ~/.mainbook/preferences.json. A saved folder that is missing or no longer allowed is ignored, and that fallback is stated in the result.

JSON remains inline. It is also written to a .json file only when an explicit output_path is provided. In remote HTTP mode, local paths and output_folder are unavailable, because the server disk does not belong to the client. XLSX/CSV comes back as a one-time download link that expires in ten minutes when you signed in through OAuth, and as a REST download instruction when you authenticated with a legacy mb_live_ key.

Manual requirements and installation

• Python 3.11 or newer
• A MainBook account

From this directory:

python3 -m venv .venv

.venv/bin/python -m pip install .

To prefer the OS keyring over the private JSON fallback, install the optional extra in every environment that runs the login command or the local server:

.venv/bin/python -m pip install '.[keyring]'

Use a plain install, not pip install -e .. In this checkout the editable install writes a .pth file that the interpreter does not pick up, so python -m mainbook_mcp fails with "No module named mainbook_mcp" while the package looks installed. An identical file under another name is honoured, so the content is fine and the cause is still unexplained — a plain install sidesteps it entirely.

If you use the manual method for automation, keep mb_live_... values in a secret environment or client configuration. Never commit them.

Streamable HTTP mode

MainBook runs this server for you at https://mcp.mainbook.ai/mcp, so a client that speaks remote MCP needs nothing installed. Paste that URL into claude.ai, Claude Desktop, ChatGPT or Cursor and sign in with your MainBook account when the client asks; no key is copied into the configuration. Cursor takes a fixed client id instead of registering itself, so give it this block:

{

"mcpServers": { "mainbook": { "url": "https://mcp.mainbook.ai/mcp", "auth": { "CLIENT_ID": "mainbook-cursor", "scopes": ["mainbook:read", "mainbook:convert"] } } } }

A client that cannot sign in can still send a legacy key from mainbook.ai/developer:

Authorization: Bearer mb_live_REPLACE_ME

Either credential is read from each request, so every user of a client reaches their own MainBook account and spends their own page credits. initialize and tools/list answer without a credential; every tool call requires one. Local file paths and output_folder do not exist over HTTP — pass file_url instead of file_path, because the server's disk is not yours. XLSX or CSV results come back as a one-time download link (ten minutes, single use) for OAuth sessions, or as a REST download instruction for a legacy mb_live_ key.

You can also run the same remote mode yourself. It is stateless Streamable HTTP with JSON responses:

mainbook-mcp --transport http --host 127.0.0.1 --port 8000

The MCP endpoint is then http://127.0.0.1:8000/mcp. Each client should send its own header:

Authorization: Bearer mb_live_REPLACE_ME

The header is read from each tool-call request and never stored in global state. Hosted HTTP mode does not inspect MAINBOOK_API_KEY, the OS keyring, or the local credential file. For Codex remote mode:

[mcp_servers.mainbook]

url = "https://mcp.mainbook.ai/mcp" bearer_token_env_var = "MAINBOOK_API_KEY" tool_timeout_sec = 920 default_tools_approval_mode = "writes"

Replace the URL with your own host if you deploy this yourself; a self-hosted deployment still needs normal HTTPS termination and access controls.

OAuth on the hosted service

Account sign-in is live on https://mcp.mainbook.ai/mcp (since 2026-08-20). The verifier stays disabled by default in this source tree, so a deployment you run yourself has to enable it deliberately. Wherever it is enabled, initialize and tools/list remain public, while each tool call accepts either an existing mb_live_ key or a MainBook RS256 access token. OAuth tokens are verified locally against only the configured MainBook JWKS URL; they are never forwarded to the Developer API. The MCP server sends a fresh 60-second X-MainBook-Service credential for every internal REST request instead.

The hosted tool scopes are fixed in one ma