MCP · Claude, Claude Code, Cursor, Codex

Bank Statement MCP Server

A finance MCP server scoped to one job: turning PDF bank statements into checked JSON, Excel or CSV — not a general accounting MCP. Run it locally after a terminal sign-in, or connect the hosted endpoint and sign in with your MainBook account.

Set up terminal sign-inmainbook-mcp on PyPI →
~/Downloads — claude

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

mainbook - convert_bank_statement (MCP)(path: "~/Downloads/march-statement.pdf", output: "xlsx")

63 transactions · 4 pages · 4 credits

Totals reconciled against the statement

Saved to ~/Downloads/march-statement.xlsx

+2 lines (ctrl+o to expand)

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

Local stdio setup

Sign in, then add it to your client

Start the browser-assisted terminal sign-in, then add a key-free client config and name only the folders the server may use.

Client setup verified 16 August 2026

MainBook MCP · client configuration

Sign in from the terminal

Run this command once before adding MainBook to a client.

Terminal sign-in
uvx mainbook-mcp auth login

The command opens MainBook in your browser, shows the same short code in the terminal and browser, and waits for your approval. The code is valid for ten minutes. It stores a revokable credential locally: in the OS keyring when the optional keyring extra is installed, otherwise in a private file. Signing in again revokes and replaces the previous credential.

  • mainbook-mcp auth status checks whether the stored credential is valid on the server without spending page credits.
  • mainbook-mcp auth logout revokes it on the server first, then deletes the local copy.

Add the client config

After signing in, add one of these blocks. No API key is copied into the client configuration.

Claude Desktop · Claude Code · Cursor · JSON
{
  "mcpServers": {
    "mainbook": {
      "command": "uvx",
      "args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]
    }
  }
}
Codex · TOML
[mcp_servers.mainbook]
command = "uvx"
args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]

Install the local package

Install uv, which includes uvx

brew install uv

or

curl -LsSf https://astral.sh/uv/install.sh | sh

Or install and update with pip

pip install mainbook-mcp

or

pip install -U mainbook-mcp

  • Client locations Claude Desktop: Settings → Developer → Edit Config. The same JSON works in Claude Code and Cursor.
  • Folder boundary Pass folders in args, or set MAINBOOK_ALLOWED_DIRS. In that environment variable, separate paths with a colon (:) on macOS/Linux and a semicolon (;) on Windows.
  • Runtime Python 3.11+; uvx fetches the package without widening the folder boundary.
  • Pip fallback Use mainbook-mcp as the command after installing with pip; upgrade the package with -U.

Manual API key for scripts and CI

Use a manual key for scripts, CI, and headless use. MAINBOOK_API_KEY takes precedence over a stored terminal sign-in. Create and revoke manual keys on the Developer API page.

Shell environment
export MAINBOOK_API_KEY="mb_live_REPLACE_ME"
Hosted server

Or connect the hosted server with your account

Chat clients take one URL and send you through a browser sign-in. Nothing is copied into the client configuration, and you can revoke the connection from your account.

Clients verified on production 20 August 2026

MainBook MCP · hosted endpoint

Server URL

Streamable HTTP endpoint
https://mcp.mainbook.ai/mcp

The server answers an anonymous tool list, then asks for a sign-in the moment a tool is called. You approve the request on a MainBook consent screen that names the client and the exact permissions it asked for, and you can revoke it later under Connected apps on the Developer page. Hosted and local use share one page-credit balance.

The hosted server publishes four of the five tools: output_folder is local-only, because a remote server has no folder on your machine to write into. Ask for JSON, or take the download link the conversion returns.

Claude · choose the authentication mode yourself

In Claude for web or desktop, open Settings, then Connectors, then Add custom connector, paste the URL, and on the next screen pick Required when the server asks. Claude pre-selects None (Detected)because our tool list stays open for catalogue crawlers; left on that setting the connector never signs in and every tool call comes back unauthorised. Leave the OAuth client on Anthropic's hosted client metadata.

ChatGPT and Codex CLI

Nothing to configure. Both register themselves from the server metadata, so adding the URL is enough; in Codex, sign in afterwards with codex mcp login followed by the name you gave the server.

Cursor · paste the client id

Cursor reads a fixed OAuth client id from mcp.json, so there is nothing to type by hand. There is no client secret: this is a public client.

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

MCP Inspector

Inspector defaults to registering itself on the fly, which MainBook does not offer. Enter the client id once in its authentication settings and leave the client secret empty: mainbook-mcp-inspector.

API keys keep working exactly as before. Scripts, CI and any headless client can still send mb_live_ keys to the same URL as a bearer token — signing in with an account is an addition, not a replacement.

Tools and requests

Five tools, four useful requests

The palette shows the exact capability; the transcript below shows how a person asks for it.

mainbook · five tools and example requests

Tool palette

5 explicit actions · no account mutation

  • convert_bank_statement

    Uploads one PDF, creates and starts a conversion job, polls for up to 30–900 seconds, and returns reviewed JSON inline or writes XLSX/CSV to disk.

    Spends page credits
  • get_conversion

    Checks a job after a timeout, returning JSON inline or writing XLSX/CSV to a chosen local destination.

    No credits · may write a file
  • list_conversions

    Returns one cursor page of account jobs together with its next_cursor value.

    Read-only account access
  • get_balance

    Returns total, reserved and available credits, all measured in PDF pages.

    Read-only account access
  • output_folder

    Reads or changes the default local folder where conversion results are written.

    No credits · local preference

convert_bank_statement alone creates a job and spends page credits. No tool buys credits, handles payments, deletes jobs or changes account data.

Ask in plain language

Each request below resolves to one tool

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

    usesconvert_bank_statement

  • How many pages of credit do I have left?

    usesget_balance

  • The last conversion timed out — check job 8f14e45f… and give me the CSV.

    usesget_conversion

  • List my recent conversions and tell me which came back with warnings.

    useslist_conversions

Local result routing

Where your files end up

The first available destination wins. The server never replaces a file that is already there.

MainBook · local result routing
Priority 1output_path

Absolute filename or existing folder

Priority 2output_folder

Remembered local folder

Priority 3source folder

Same base name + requested extension, next to PDF

~/Downloadsallowed folder

march-statement.pdf

source

march-statement.xlsx

saved next to PDF

march-statement (2).xlsx

never overwritten

then (3), and so on

JSON

inline unless output_path is set

get_conversion needs an explicit or remembered folder; it never guesses the original PDF location.

Remembered in ~/.mainbook/preferences.json and shared by local clients; a missing or disallowed folder is ignored and the fallback is reported.

Local boundary · shared credits · async work

Boundaries, credits, and timing

One operating view covers what the server can touch, what a conversion spends, how long the client waits, and the public contract underneath.

mainbook-mcp · local boundary and public API

Revokable account credential

Terminal sign-in stores it locally. Revoke it with auth logout or in the app; the server has no payment or deletion tool.

Named folders only

Listed folders are readable and writable. Anything outside them is refused by the local stdio server.

1 page = 1 credit

Reserved for each PDF page.

20 pages

New-account signup grant, not a separate MCP tier.

Shared wallet

Packages are bought in the web app. The MCP server cannot purchase credits.

Polling window

30s minimum900s ceiling

No average duration is published. If the client times out, the server job continues; call get_conversionwith the job ID or raise the client's tool timeout.

Operating limits

500 pages
maximum per PDF
50 MB
maximum per PDF
6 jobs
in flight per API key
90 days
document + result retention

Under the local server sits the public REST API. Use it directly when you are building your own integration instead of driving an assistant.

REST API guideOpenAPI JSONSwagger UI

Read the handling overview in Security. The account must accept the API Terms; otherwise calls fail with api_terms_not_accepted. The applicable data disclosures are in the Privacy Policy and AI Disclosure.

The common questions

Frequently asked questions

Which MCP clients does this work with?
It works with Claude Desktop, Claude Code, Cursor and Codex using the configuration blocks above.
Do I have to install anything?
uv/uvx fetches and runs the published mainbook-mcp package, or you can run pip install mainbook-mcp. Python 3.11 or newer is required.
Can the agent read my whole disk?
No. It can only read or write inside the folders passed as arguments or set through MAINBOOK_ALLOWED_DIRS; anything outside them is refused.
Can the agent spend my money?
convert_bank_statement spends page credits from your account; there is no tool for buying credits, payments or deleting anything.
What happens if my client gives up waiting?
The job keeps running server-side; call get_conversion with the job ID to pick it up.
Is there a hosted server I can point at instead?
Yes. Point your client at https://mcp.mainbook.ai/mcp over Streamable HTTP and sign in with your MainBook account when the client asks; no key goes into the config. Scripts can still send an API key as an Authorization Bearer header instead. Local paths and the output folder stay stdio-only, so remote clients pass a public HTTPS file_url instead.

Give your assistant one useful tool

Sign in from the terminal, name the folders, and let the local server handle the conversion flow.

Set up terminal sign-inmainbook-mcp on PyPI →Read the REST API guide →