MainBook Bank Statement Converter
About
Turn PDF bank statements into checked Excel, CSV or JSON with balance validation.
Details
- Author
- human-beyond
- Categories
- Finance, Other
Jump to
Setup
Install MainBook Bank Statement Converter in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/human-beyond/mainbook-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
Turn PDF bank statements into checked Excel, CSV or JSON with balance validation.
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 after onemainbook-mcp auth login, or over MainBook's hosted endpoint athttps://mcp.mainbook.ai/mcp, where your client signs you in with your MainBook account. Existingmb_live_API keys keep working for scripts and older clients.
Point your assistant at a statement and ask for a spreadsheet. The PDF goes toMainBook, which extracts every transaction, normalises dates toYYYY-MM-DD, keeps money as exact amounts, and re-adds the statement so thatopening balance + credits − debitshas to match the closing balance. Rows that do not fit are flagged instead of being passed on quietly.
> Convert ~/Downloads/march-statement.pdf and save the Excel next to it. mainbook - convert_bank_statement (MCP) 63 transactions · 4 pages · 4 credits Totals reconciled against the statement Saved to ~/Downloads/march-statement.xlsx Done — 63 transactions. Opening 4,127.50 and closing 3,881.05 both match the statement, and nothing was flagged.
It doesnotconnect to bank accounts and isnotan Open Banking or bank-data API. It reads statement files you already have. Nothing is scraped and no banking credentials are involved.
A MainBook account and the folders holding your statements. Conversion is the only tool that spends page credits. Of the other four,get_balanceandlist_conversionsonly read,get_conversionmay write a result file, andoutput_folderchanges a local preference; none of them changes anything in your MainBook account.
The command opens MainBook in your browser, shows the same short code in both places, and waits for your approval. It stores the credential in the OS keyring when the optionalkeyringpackage is installed and working. Otherwise it uses~/.config/mainbook/credentials.jsonwith private directory and file permissions. Usemainbook-mcp auth statusto check the active credential server-side without spending page credits.mainbook-mcp auth logoutrevokes that stored key first, then removes the local copy; if MainBook cannot be reached, it says plainly that the key may still be active. Signing in again revokes the previously stored key before saving its replacement. The device token response does not include an email or account ID, so status says that account identity was not provided instead of guessing.
Then add one entry to your client's MCP configuration. This is the same block for Claude Desktop (Settings → Developer → Edit Config), Claude Code, and Cursor; no key is copied into it:
{ "mcpServers": { "mainbook": { "command": "uvx", "args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"] } } }
Codex reads TOML, so put the same thing in~/.codex/config.toml:
[mcp_servers.mainbook] command = "uvx" args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]
The folder arguments are the only places the server may read a statement from or write a result to; anything outside them is refused.MAINBOOK_ALLOWED_DIRSsets the same list through the environment instead, separated by the platform'sos.pathsep(:on macOS/Linux,;on Windows).
MAINBOOK_API_KEYtakes precedence over any stored login. Keep the manual method for automation where an interactive browser is not available.auth loginwarns when this variable will keep overriding the newly stored credential:
export MAINBOOK_API_KEY="mb_live_REPLACE_ME" mainbook-mcp
Create and revoke manual keys athttps://mainbook.ai/developer. Never commit them.
Claude Desktop, without touching a config file
Claude Desktop also accepts a one-file bundle:Extensions → Install Extension…and pickmainbook.mcpb. It asks for the API key and the folders in a dialog and manages its own Python runtime, so nothing needs installing first. The config block above does the same job and is the better fit if you already keep other servers there. Build the bundle from this directory with:
npx --yes @anthropic-ai/mcpb@2.1.2 validate manifest.json npx --yes @anthropic-ai/mcpb@2.1.2 pack . dist/mainbook.mcpb
- convert_bank_statement: creates a paid page-credit job, uploads one PDF, starts conversion, polls for up to 30-900 seconds, and returns the reviewed result. JSON stays inline. In local stdio mode, XLSX/CSV bytes are written to disk and only the full path enters model context.
- get_conversion: checks a job after a timeout and returns JSON inline or writes XLSX/CSV to a chosen local destination.
- list_conversions: returns one cursor page of account jobs plusnext_cursor.
- get_balance: returns total, reserved, and available credits, all measured in PDF pages.
- output_folder: reads or changes the default local result folder.
Local stdio mode lists all five tools. Hosted HTTP mode lists exactly the first four;output_folderis not advertised remotely because the server's disk does not belong to the client.
There are no tools for buying credits, payments, deleting jobs, or changing account data. Tools that can create a conversion, write a local result file, or change the output preference are marked non-read-only.get_conversionis read-only over hosted HTTP, where it writes no file, and non-read-only over local stdio, where it may write XLSX or CSV. None is marked destructive because existing result files are never replaced.
For local stdio clients (Claude Desktop, Claude Code, Cursor, and Codex), XLSX and CSV results are written to the first available destination in this order:
- output_pathsupplied toconvert_bank_statementorget_conversion(an absolute filename or an existing folder);
- the folder remembered byoutput_folder;
- next to the source PDF, with the same base name and the result extension.
get_conversioncannot infer the original PDF folder. Withoutoutput_pathor a valid remembered folder it returns a clear error instead of guessing a destination. Every successful file response contains the absolute path and explains which rule selected it. Existing files are never replaced:statement.xlsxis followed bystatement (2).xlsx, then(3), and so on.
Ask the client to calloutput_folderwith no argument to see the current setting and every allowed folder. Set it with an allowed absolute directory, or passnext_to_sourceto restore the default. The preference is shared by local clients on the same machine in~/.mainbook/preferences.json. A saved folder that is missing or no longer allowed is ignored, and that fallback is stated in the result.
JSON remains inline. It is also written to a.jsonfile only when an explicitoutput_pathis provided. In remote HTTP mode, local paths andoutput_folderare unavailable, because the server disk does not belong to the client. XLSX/CSV comes back as a one-time download link that expires in ten minutes when you signed in through OAuth, and as a REST download instruction when you authenticated with a legacymb_live_key.
python3 -m venv .venv .venv/bin/python -m pip install .
To prefer the OS keyring over the private JSON fallback, install the optional extra in every environment that runs the login command or the local server:
.venv/bin/python -m pip install '.[keyring]'
Use a plain install, notpip install -e .. In this checkout the editable install writes a.pthfile that the interpreter does not pick up, sopython -m mainbook_mcpfails with "No module named mainbook_mcp" while the package looks installed. An identical file under another name is honoured, so the content is fine and the cause is still unexplained — a plain install sidesteps it entirely.
If you use the manual method for automation, keepmb_live_...values in a secret environment or client configuration. Never commit them.
{ "mcpServers": { "mainbook": { "url": "https://mcp.mainbook.ai/mcp", "auth": { "CLIENT_ID": "mainbook-cursor", "scopes": ["mainbook:read", "mainbook:convert"] } } } }
Authorization: Bearer mb_live_REPLACE_ME
Either credential is read from each request, so every user of a client reaches their own MainBook account and spends their own page credits.initializeandtools/listanswer without a credential; every tool call requires one. Local file paths andoutput_folderdo not exist over HTTP — passfile_urlinstead offile_path, because the server's disk is not yours. XLSX or CSV results come back as a one-time download link (ten minutes, single use) for OAuth sessions, or as a REST download instruction for a legacymb_live_key.
You can also run the same remote mode yourself. It is stateless Streamable HTTP with JSON responses:
mainbook-mcp --transport http --host 127.0.0.1 --port 8000
The MCP endpoint is thenhttp://127.0.0.1:8000/mcp. Each client should send its own header:
Authorization: Bearer mb_live_REPLACE_ME
The header is read from each tool-call request and never stored in global state. Hosted HTTP mode does not inspectMAINBOOK_API_KEY, the OS keyring, or the local credential file. For Codex remote mode:
[mcp_servers.mainbook] url = "https://mcp.mainbook.ai/mcp" bearer_token_env_var = "MAINBOOK_API_KEY" tool_timeout_sec = 920 default_tools_approval_mode = "writes"
Replace the URL with your own host if you deploy this yourself; a self-hosted deployment still needs normal HTTPS termination and access controls.
Account sign-in is live onhttps://mcp.mainbook.ai/mcp(since 2026-08-20). The verifier stays disabled by default in this source tree, so a deployment you run yourself has to enable it deliberately. Wherever it is enabled,initializeandtools/listremain public, while each tool call accepts either an existingmb_live_key or a MainBook RS256 access token. OAuth tokens are verified locally against only the configured MainBook JWKS URL; they are never forwarded to the Developer API. The MCP server sends a fresh 60-secondX-MainBook-Servicecredential for every internal REST request instead.
The hosted tool scopes are fixed in one map:convert_bank_statementrequiresmainbook:convert;get_balance,get_conversion, andlist_conversionsrequiremainbook:read. Protected-resource metadata is published at/.well-known/oauth-protected-resource/mcponly while the flag is enabled.
- MAINBOOK_API_KEY: optional in stdio and takes precedence over a stored login; ignored in HTTP mode, where every tool call must carry its own Bearer header.
- MAINBOOK_API_BASE_URL: REST host, defaulthttps://api.mainbook.ai. The server appends/api/v1/developer.
- MAINBOOK_ALLOWED_DIRS: local folders allowed for source reads and result writes, separated by the platform'sos.pathsep(:on macOS/Linux and;on Windows). Positional directory arguments take priority. If neither is supplied, the defaults are~/Downloads,~/Desktop, and~/Documents.
- MAINBOOK_MCP_TRANSPORT:stdio(default) orhttp.
- MAINBOOK_MCP_HOST: HTTP bind host, default127.0.0.1.
- MAINBOOK_MCP_PORT: HTTP bind port, default8000.
- MAINBOOK_MCP_OAUTH_ENABLED: hosted OAuth verifier feature flag, defaultfalse. With the flag off, metadata is absent and hosted Bearer handling remains the legacymb_live_behavior.
- MAINBOOK_MCP_OAUTH_ISSUER: exact trusted issuer, defaulthttps://api.mainbook.ai.
- MAINBOOK_MCP_OAUTH_JWKS_URL: trusted JWKS URL, defaulthttps://api.mainbook.ai/.well-known/jwks.json. Token header URLs are ignored.
- MAINBOOK_MCP_OAUTH_RESOURCE: exact audience/resource, defaulthttps://mcp.mainbook.ai/mcp.
- MAINBOOK_MCP_OAUTH_CLOCK_SKEW_SECONDS: NumericDate clock allowance, default5.
- MAINBOOK_MCP_OAUTH_MAX_TOKEN_AGE_SECONDS: maximum accepted age fromiat, default600.
- MAINBOOK_MCP_OAUTH_JWKS_CACHE_TTL_SECONDS: JWKS cache lifetime, default300.
- MAINBOOK_MCP_OAUTH_JWKS_REFRESH_MIN_INTERVAL_SECONDS: minimum interval between unknown-kidrefresh attempts, default30.
- MCP_SERVICE_SIGNING_SECRETS: comma-separated service-door secrets. MCP signs with the first; Django may accept current and previous values during rotation. Required when OAuth is enabled; never commit it.
- file_pathandfile_urlare mutually exclusive.file_pathis accepted only over local stdio; HTTP mode rejects it before the filesystem loader runs and requiresfile_url.
- Localfile_pathaccess and result-file writes use the same configured folders. Positional CLI directories take priority overMAINBOOK_ALLOWED_DIRS; the environment takes priority over the defaults~/Downloads,~/Desktop, and~/Documents. Every root is expanded and resolved, missing roots are ignored, and the active roots are printed to stderr when the server starts. If no roots remain, local access fails closed while the server continues running.
- Output parents are resolved before writing and checked by directory identity, so a symlink cannot redirect a result outside the allowed folders. Result creation is exclusive and collision-safe; existing files are not overwritten.
- ~/.mainbook/preferences.jsonis replaced atomically. The.mainbookdirectory is mode0700and the preference file is mode0600; malformed or unreadable preferences are ignored safely.
- Terminal credentials use the OS keyring when the optional package is usable. The fallback~/.config/mainbook/credentials.jsonis replaced atomically inside a mode0700directory and is mode0600; its top-level entries are keyed by API base URL.
- Local paths are expanded and strictly resolved before the allowlist check, so..and symlinks cannot make an outside target appear to be inside an allowed folder. The resolved path must be strictly below a root, not equal to the root itself.
- The local file is opened once. The server usesfstaton that descriptor to require a regular file and enforce the 50 MiB limit, then performs the bounded read through the same descriptor. This closes the check-versus-read replacement window, but it does not fully eliminate the race between resolving the path and opening it; the path can still be replaced during that interval.
- A local file must contain%PDF-within its first 1024 bytes beforepypdfis invoked. Filename extensions are not used to decide whether a file is a PDF.
- Remote files must use HTTPS. Redirects are not followed.
- DNS answers are rejected if any address is private, loopback, link-local, metadata, reserved, or otherwise non-public, for IPv4 and IPv6.
- URL downloads connect to an already validated numeric IP while retaining the original hostname for TLS certificate verification and the HTTPHostheader, closing DNS-rebinding races.
- Content-Lengthand the actual streamed byte count are independently capped at 50 MiB.
- PDFs are parsed locally withpypdfand capped at 500 pages.
- Presigned upload headers from MainBook are forwarded unchanged; the MainBook Bearer key is never sent to storage.
.venv/bin/python -m pip install '.[dev]' .venv/bin/pytest .venv/bin/pytest --cov=mainbook_mcp --cov-report=term-missing --cov-report=annotate:cov_annotate .venv/bin/ruff check .
All REST tests use mocks or a local stub. No test requires or accepts a real MainBook API key.
Free crypto address labels. Identify known addresses on major networks with a free API.
Clean SEC EDGAR company financials, ratios, filings, and 10-K/10-Q sections as normalized JSON — a hosted MCP server with 5 tools and a free tier.
Check live market data and execute real trades — buy/sell tokens and stocks, open leveraged perp positions, trade prediction markets, move funds in and out of savings
international financial reporting engine for Agents and REST api users journal entries, statement generation, audit trail with workings, financial reporting automation
A paid MCP server for invoice processing. Three tools: extract structured data from any invoice (pasted text, URL, or PDF), validate the extracted invoice for completeness and mathematical accuracy, and classify the expense into an accounting category with a suggested nominal account code and tax deductibility flag. Priced from $0.005 to $0.01 per call, paid in USDC on Base via x402. No API key required.
English background checks on Korean (KRX) stocks from DART filings: dilution history, delisting-risk flags, every claim linked to the original filing.
Convert PDF bank statements to checked Excel, CSV, or JSON with balance validation.
Real-time tweet counters and market data for Polymarket's Elon Musk & Ted Cruz markets — hosted remote MCP server (streamable-http + SSE), free tier is keyless.
Official hosted MCP adapter for Quote.Trade market data and guarded account/order workflows; no withdrawal tools.
xpenser.cleverbrush.com is a ln open-source, self-hostable personal expense and income tracking app supporting different currencies, categories, vendors, automated invoice parsing, AI geberated reports and more.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
