MainBook Bank Statement Converter

What MainBook Bank Statement Converter MCP server does

MainBook Bank Statement Converter MCP server processes PDF statements that are already available on the user’s computer. It sends the selected file to MainBook for transaction extraction and returns a reviewed result in JSON, XLSX, or CSV form. Dates are normalized to YYYY-MM-DD, monetary values remain exact amounts, and the extracted rows are checked against the statement’s balances.

The balance check recomputes the closing balance from the opening balance, credits, and debits. Transactions or rows that do not fit the statement are flagged rather than silently accepted. This is a file-conversion tool, not an Open Banking connector: it does not access bank accounts, scrape websites, or require banking credentials.

How it works

The local server runs through MCP over stdio. A client can provide one or more permitted folders as command-line arguments, or use MAINBOOK_ALLOWED_DIRS to define them. The server may read source statements and write generated files only within those directories.

convert_bank_statement creates a page-credit conversion job, uploads one PDF, starts processing, waits for the result, and returns the reviewed output. Processing can take from 30 to 900 seconds. JSON is returned inline. In local mode, XLSX and CSV results are written to disk, with the absolute path included in the response.

The hosted endpoint at https://mcp.mainbook.ai/mcp provides remote MCP access. In that mode, local folders and the output_folder tool are unavailable. XLSX and CSV results are provided through a temporary download mechanism: OAuth-authenticated users receive a link that expires after ten minutes, while legacy mb_live_ key users receive REST download instructions.

Setup and configuration

MainBook Bank Statement Converter MCP server requires Python 3.11 or newer and a MainBook account. The simplest local setup uses uvx, after installing uv:

uvx mainbook-mcp auth login

The login flow opens MainBook in a browser and stores the credential in the operating system keyring when the optional keyring package is available. Otherwise, it uses ~/.config/mainbook/credentials.json with restricted permissions. auth status checks the active credential, and auth logout revokes and removes the stored key when MainBook is reachable.

Clients can launch the local server with uvx mainbook-mcp and permitted folder arguments. Claude Desktop, Claude Code, Cursor, and Codex are documented as supported configurations. For scripts or CI without an interactive browser, set MAINBOOK_API_KEY to an mb_live_ key. That variable takes precedence over a stored login and should not be committed to source control.

A standard Python installation is also supported with pip install mainbook-mcp, followed by the mainbook-mcp command. The optional keyring extra can be installed when OS keyring storage is preferred.

Tools and capabilities

The MCP server exposes five tools locally and four through hosted HTTP:

• convert_bank_statement uploads and converts one PDF, then returns the checked result.
• get_conversion checks an existing job and can return JSON or write XLSX/CSV locally.
• list_conversions returns one cursor-based page of account conversion jobs and a next cursor.
• get_balance reports total, reserved, and available page credits.
• output_folder reads or changes the local default result directory; it is local-only.

Local file destinations follow this order: an explicit output_path, the saved output_folder, or the source PDF’s directory. get_conversion cannot infer the original PDF directory, so it needs an explicit destination or valid saved folder. Existing files are not replaced; a numbered filename is chosen instead. JSON is written to disk only when an explicit JSON output path is supplied.

Limitations and notes

MainBook Bank Statement Converter MCP server consumes page credits only when creating a conversion. Balance checks, conversion listing, and output-folder operations do not alter the MainBook account. The tool set does not include credit purchases, payments, job deletion, or account-data changes.

The server does not replace files that already exist. A saved output folder that is missing or no longer allowed is ignored, and the response explains the fallback. Hosted mode cannot write to the client’s disk because its server filesystem is remote. The README also recommends a plain package installation rather than an editable install for this project checkout.