MainBook Bank Statement Converter is an MCP server in the financial domain whose scope is limited to one task: converting PDF bank statements into validated JSON, Excel, or CSV files, rather than being a general-purpose accounting MCP.
[Purpose] This server is intended for financial data processing scenarios, reading statement files you already hold and converting them into a structured format convenient for subsequent analysis or archiving. It does not connect to bank accounts, is not Open Banking or a bank data API, does not scrape any content, and does not involve bank credentials.
[Main capabilities] After a PDF is sent to MainBook, the server extracts every transaction, normalizes dates uniformly to YYYY-MM-DD, keeps amounts as exact numeric values, and validates by re-adding the statement: opening balance + credits − debits must match the closing balance. Rows that do not satisfy this equation are flagged rather than silently passed through.
[How to use] It can be run locally: first execute mainbook-mcp auth login once, and the command will open MainBook in the browser and display the same short code in two places, waiting for you to approve. Credentials are preferably stored in the operating system keychain (requires the optional keyring package to be installed and available); otherwise ~/.config/mainbook/credentials.json is used, with private directory and file permissions set. You can also use mainbook-mcp auth status to check credential status without consuming page credits, and mainbook-mcp auth logout to revoke the stored key first and then delete the local copy. A hosted endpoint can also be used https://mcp.mainbook.ai/mcp，客户端通过你的 MainBook account login. Existing mb_live_ API keys remain valid for scripts and legacy clients.
Add the configuration in the client to connect. Claude Desktop, Claude Code, and Cursor use the same configuration block, with no need to copy keys. Codex reads TOML, and the configuration is written to ~/.codex/config.toml. uvx comes with uv, and you can install it once with brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh; you can also pip install mainbook-mcp and upgrade it yourself with pip install -U mainbook-mcp. The folder argument is the only directory the server is allowed to read statements from or write results to; anything outside it is rejected. MAINBOOK_ALLOWED_DIRS can be used to set the same list via an environment variable, separated by the platform-specific os.pathsep (: on macOS/Linux, ; on Windows).
Claude Desktop also supports a single-file package: Extensions → Install Extension…, select mainbook.mcpb, and it will ask for the API key and folder in a dialog and manage the Python runtime itself.
[Exposed tools] convert_bank_statement: creates a paid page-credit task, uploads one PDF, starts the conversion, polls for 30 to 900 seconds, and returns the reviewed result. JSON remains inline. In local stdio mode, XLSX/CSV bytes are written to disk, and only the full path enters the model context. get_conversion: checks the task after a timeout, returns JSON inline, or writes XLSX/CSV to the selected local destination. list_conversions: returns a page of account tasks and a next_cursor. get_balance: returns total, reserved, and available credits, all measured in PDF pages. output_folder: reads or changes the default local results folder. Local stdio mode lists all five tools. Hosted HTTP mode lists only the first four; output_folder is not exposed remotely because the server disk does not belong to the client. There are no tools for purchasing credits, making payments, deleting tasks, or changing account data.
[Result file location] For local stdio clients (Claude Desktop, Claude Code, Cursor, and Codex), XLSX and CSV results are written in the following order to the first available destination: the output_path passed to convert_bank_statement or get_conversion (an absolute filename or an existing folder); the remembered text of output_folderfolder; next to the source PDF, using the same base name and the result extension. get_conversion cannot infer the original PDF folder; if there is no output_path or valid remembered folder, it returns an explicit error instead of guessing the target. Existing files are not replaced; after statement.xlsx comes statement (2).xlsx, then (3), and so on. JSON stays inline and is only written to a .json file when an explicit output_path is provided. In remote HTTP mode, local paths and output_folder are unavailable.
[Applicable scenarios and limitations] Suitable for users who already have PDF bank statements and want an AI assistant to output spreadsheets or structured data, especially for workflows that do not need to connect to a bank account and do not want to provide bank credentials. Requires a MainBook account and Python 3.11 or higher. Conversion is the only tool that consumes page credits. The manual API key method is suitable for automation or scenarios where an interactive browser is unavailable; MAINBOOK_API_KEY takes precedence over stored login credentials, and the key should be kept in a secret environment or client configuration and never committed. Regarding authentication, OAuth login for the hosted service is already available; self-hosted deployments need to enable the OAuth authenticator themselves. Tool scopes are fixed: convert_bank_statement requires mainbook:convert; get_balance, get_conversion, and list_conversions require mainbook:read.
Regarding file and network security, file_path and file_url are mutually exclusive; file_path is only accepted under local stdio, while HTTP mode rejects it and requires file_url. Local file access and result writing use the same set of configured folders, handled by priority in the order of the location CLI directory, MAINBOOK_ALLOWED_DIRS, and the default ~/Downloads, ~/Desktop, ~/Documents. The output parent directory is resolved before writing and checked by directory identity; symbolic links cannot redirect results outside the allowed folders; results are created exclusively and conflict-proof, without overwriting existing files. Preference files are atomically replaced, the .mainbook directory mode is 0700, and the preference file mode is 0600. Local pathis strictly resolved before the allowlist check; .. and symbolic links cannot make an external target appear to be inside an allowed folder, and the resolved path must be strictly below the root directory and cannot equal the root itself. Local files are opened once, fstat is used to require a regular file and enforce the 50 MiB limit, and then bounded reading is performed through the same descriptor; this closes the replacement window between checking and reading, but does not completely eliminate the race between resolving the path and opening it. Local files must contain %PDF- within the first 1024 bytes before pypdf is invoked; file extensions are not used for this determination.
[Environment variables] MAINBOOK_API_KEY: optional in stdio and takes precedence over stored login; ignored in HTTP mode. MAINBOOK_API_BASE_URL: REST host, default https://api.mainbook.ai，服务器追加 /api/v1/developer. MAINBOOK_ALLOWED_DIRS: folders allowed for local reading and writing, separated by the platform's os.pathsep. MAINBOOK_MCP_TRANSPORT: stdio (default) or http. MAINBOOK_MCP_HOST: HTTP bind host, default 127.0.0.1. MAINBOOK_MCP_PORT: HTTP bind port, default 8000. MAINBOOK_MCP_OAUTH_ENABLED: feature flag for the hosted OAuth validator, default false. There are also variables for the OAuth issuer, JWKS URL, resource, clock skew, maximum token age, JWKS cache TTL, minimum interval for refreshing an unknown kid, and MCP_SERVICE_SIGNING_SECRETS (required when OAuth is enabled; never commit it).
[Installation notes] Python 3.11 or later is required, as well as a MainBook account. A regular installation should be used rather than pip install -e ., because in this checkout the .pth file written by an editable install will not be picked up by the interpreter, causing python -m mainbook_mcp to report "No module named mainbook_mcp"; a regular installation completely bypasses this problem. If you want to prefer the operating system keychain over the private JSON fallback, you need to install the optional extra in every environment where you run the login command or the local server.
