# MainBook Bank Statement Converter [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/human-beyond/mainbook-mcp  
**GitHub Stars:** 0  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mainbook-bank-statement-converter

## Description
Convert PDF bank statements to checked Excel, CSV or JSON with balance validation.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "mainbook-bank-statement-converter": {
    "command": "uvx",
    "args": ["mainbook-mcp"],
    "env": {
      "MAINBOOK_ALLOWED_DIRS": "",
      "MAINBOOK_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `MAINBOOK_ALLOWED_DIRS`, `MAINBOOK_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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`:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/mainbook-bank-statement-converter/readme_