MainBook Bank Statement Converter

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. It runs locally with your MainBook API key.

Create an API keymainbook-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

Add it to your client

Pick the client config, replace the key placeholder, and name only the folders the server may use.

Client setup verified 14 August 2026

MainBook MCP · client configuration

Claude Desktop · Claude Code · Cursor · JSON

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

Codex · TOML

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

[mcp_servers.mainbook.env]
MAINBOOK_API_KEY = "mb_live_…"

Install the local package

Install uv, which includes uvx

brew install uv

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

Or install and update with pip

pip install mainbook-mcp

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.

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

Account-wide API key

Keep it private and revoke it in the app if exposed. The server can use the account, but it 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?

The server runs locally on your machine over stdio and talks to api.mainbook.ai from there.

Give your assistant one useful tool

Create the key, name the folders, and let the local server handle the conversion flow.

Create an API keymainbook-mcp on PyPI →Read the REST API guide →