{
  "markdown": "# MainBook Bank Statement Converter\n\n<!-- mcp-name: ai.mainbook/bank-statement-converter -->\n\n[![PyPI](https://img.shields.io/pypi/v/mainbook-mcp)](https://pypi.org/project/mainbook-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/mainbook-mcp)](https://pypi.org/project/mainbook-mcp/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n**A finance MCP server scoped to one job: turning PDF bank statements into checked JSON, Excel or\nCSV — not a general accounting MCP.** It runs locally after one `mainbook-mcp auth login`, or over\nMainBook's hosted endpoint at `https://mcp.mainbook.ai/mcp`, where your client signs you in with your\nMainBook account. Existing `mb_live_` API keys keep working for scripts and older clients.\n\nPoint your assistant at a statement and ask for a spreadsheet. The PDF goes to\n[MainBook](https://mainbook.ai/mcp), which extracts every transaction, normalises dates to\n`YYYY-MM-DD`, keeps money as exact amounts, and re-adds the statement so that\n`opening balance + credits − debits` has to match the closing balance. Rows that do not fit are\nflagged instead of being passed on quietly.\n\n```text\n> Convert ~/Downloads/march-statement.pdf and save the Excel next to it.\n\n  mainbook - convert_bank_statement (MCP)\n  63 transactions · 4 pages · 4 credits\n  Totals reconciled against the statement\n  Saved to ~/Downloads/march-statement.xlsx\n\nDone — 63 transactions. Opening 4,127.50 and closing 3,881.05 both match\nthe statement, and nothing was flagged.\n```\n\n### What it is not\n\nIt does **not** connect to bank accounts and is **not** an Open Banking or bank-data API. It reads\nstatement files you already have. Nothing is scraped and no banking credentials are involved.\n\n### What you need\n\nA MainBook account and the folders holding your statements. Conversion is the only tool that spends\npage credits. Of the other four, `get_balance` and `list_conversions` only read, `get_conversion`\nmay write a result file, and `output_folder` changes a local preference; none of them changes\nanything in your MainBook account.\n\n## Add it to your client\n\nSign in once from a terminal:\n\n```bash\nuvx mainbook-mcp auth login\n```\n\nThe command opens MainBook in your browser, shows the same short code in both places, and waits for\nyour approval. It stores the credential in the OS keyring when the optional `keyring` package is\ninstalled and working. Otherwise it uses `~/.config/mainbook/credentials.json` with private\ndirectory and file permissions. Use `mainbook-mcp auth status` to check the active credential\nserver-side without spending page credits. `mainbook-mcp auth logout` revokes that stored key first,\nthen removes the local copy; if MainBook cannot be reached, it says plainly that the key may still be\nactive. Signing in again revokes the previously stored key before saving its replacement. The device\ntoken response does not include an email or account ID, so status says that account identity was not\nprovided instead of guessing.\n\nThen add one entry to your client's MCP configuration. This is the same block for Claude Desktop\n(**Settings → Developer → Edit Config**), Claude Code, and Cursor; no key is copied into it:\n\n```json\n{\n  \"mcpServers\": {\n    \"mainbook\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mainbook-mcp\", \"~/Downloads\", \"~/Desktop\", \"~/Documents\"]\n    }\n  }\n}\n```\n\nCodex reads TOML, so put the same thing in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.mainbook]\ncommand = \"uvx\"\nargs = [\"mainbook-mcp\", \"~/Downloads\", \"~/Desktop\", \"~/Documents\"]\n```\n\n`uvx` comes with [uv](https://docs.astral.sh/uv/); install it once with `brew install uv` or\n`curl -LsSf https://astral.sh/uv/install.sh | sh`. It fetches and runs the published package, so\nthere is nothing to download by hand and nothing to update. If you would rather not add uv, run\n`pip install mainbook-mcp` and use `\"command\": \"mainbook-mcp\"` with the same arguments — you then\nupgrade it yourself with `pip install -U mainbook-mcp`.\n\nThe folder arguments are the only places the server may read a statement from or write a result to;\nanything outside them is refused. `MAINBOOK_ALLOWED_DIRS` sets the same list through the\nenvironment instead, separated by the platform's `os.pathsep` (`:` on macOS/Linux, `;` on Windows).\n\n### Manual API key for scripts and CI\n\n`MAINBOOK_API_KEY` takes precedence over any stored login. Keep the manual method for automation\nwhere an interactive browser is not available. `auth login` warns when this variable will keep\noverriding the newly stored credential:\n\n```bash\nexport MAINBOOK_API_KEY=\"mb_live_REPLACE_ME\"\nmainbook-mcp\n```\n\nCreate and revoke manual keys at <https://mainbook.ai/developer>. Never commit them.\n\n### Claude Desktop, without touching a config file\n\nClaude Desktop also accepts a one-file bundle: **Extensions → Install Extension…** and pick\n`mainbook.mcpb`. It asks for the API key and the folders in a dialog and manages its own Python\nruntime, so nothing needs installing first. The config block above does the same job and is the\nbetter fit if you already keep other servers there. Build the bundle from this directory with:\n\n```bash\nnpx --yes @anthropic-ai/mcpb@2.1.2 validate manifest.json\nnpx --yes @anthropic-ai/mcpb@2.1.2 pack . dist/mainbook.mcpb\n```\n\n## What it exposes\n\n- `convert_bank_statement`: creates a paid page-credit job, uploads one PDF, starts conversion,\n  polls for up to 30-900 seconds, and returns the reviewed result. JSON stays inline. In local\n  stdio mode, XLSX/CSV bytes are written to disk and only the full path enters model context.\n- `get_conversion`: checks a job after a timeout and returns JSON inline or writes XLSX/CSV to a\n  chosen local destination.\n- `list_conversions`: returns one cursor page of account jobs plus `next_cursor`.\n- `get_balance`: returns total, reserved, and available credits, all measured in PDF pages.\n- `output_folder`: reads or changes the default local result folder.\n\nLocal stdio mode lists all five tools. Hosted HTTP mode lists exactly the first four;\n`output_folder` is not advertised remotely because the server's disk does not belong to the client.\n\nThere are no tools for buying credits, payments, deleting jobs, or changing account data.\nTools that can create a conversion, write a local result file, or change the output preference are\nmarked non-read-only. `get_conversion` is read-only over hosted HTTP, where it writes no file, and\nnon-read-only over local stdio, where it may write XLSX or CSV. None is marked destructive because\nexisting result files are never replaced.\n\n## Where result files go\n\nFor local stdio clients (Claude Desktop, Claude Code, Cursor, and Codex), XLSX and CSV results are\nwritten to the first available destination in this order:\n\n1. `output_path` supplied to `convert_bank_statement` or `get_conversion` (an absolute filename or\n   an existing folder);\n2. the folder remembered by `output_folder`;\n3. next to the source PDF, with the same base name and the result extension.\n\n`get_conversion` cannot infer the original PDF folder. Without `output_path` or a valid remembered\nfolder it returns a clear error instead of guessing a destination. Every successful file response\ncontains the absolute path and explains which rule selected it. Existing files are never replaced:\n`statement.xlsx` is followed by `statement (2).xlsx`, then `(3)`, and so on.\n\nAsk the client to call `output_folder` with no argument to see the current setting and every allowed\nfolder. Set it with an allowed absolute directory, or pass `next_to_source` to restore the default.\nThe preference is shared by local clients on the same machine in `~/.mainbook/preferences.json`.\nA saved folder that is missing or no longer allowed is ignored, and that fallback is stated in the\nresult.\n\nJSON remains inline. It is also written to a `.json` file only when an explicit `output_path` is\nprovided. In remote HTTP mode, local paths and `output_folder` are unavailable, because the server disk\ndoes not belong to the client. XLSX/CSV comes back as a one-time download link that expires in\nten minutes when you signed in through OAuth, and as a REST download instruction when you\nauthenticated with a legacy `mb_live_` key.\n\n## Manual requirements and installation\n\n- Python 3.11 or newer\n- A MainBook account\n\nFrom this directory:\n\n```bash\npython3 -m venv .venv\n.venv/bin/python -m pip install .\n```\n\nTo prefer the OS keyring over the private JSON fallback, install the optional extra in every\nenvironment that runs the login command or the local server:\n\n```bash\n.venv/bin/python -m pip install '.[keyring]'\n```\n\nUse a plain install, not `pip install -e .`. In this checkout the editable install writes a `.pth`\nfile that the interpreter does not pick up, so `python -m mainbook_mcp` fails with \"No module named\nmainbook_mcp\" while the package looks installed. An identical file under another name is honoured,\nso the content is fine and the cause is still unexplained — a plain install sidesteps it entirely.\n\nIf you use the manual method for automation, keep `mb_live_...` values in a secret environment or\nclient configuration. Never commit them.\n\n## Streamable HTTP mode\n\nMainBook runs this server for you at `https://mcp.mainbook.ai/mcp`, so a client that speaks remote\nMCP needs nothing installed. Paste that URL into claude.ai, Claude Desktop, ChatGPT or Cursor and\nsign in with your MainBook account when the client asks; no key is copied into the configuration.\nCursor takes a fixed client id instead of registering itself, so give it this block:\n\n```json\n{\n  \"mcpServers\": {\n    \"mainbook\": {\n      \"url\": \"https://mcp.mainbook.ai/mcp\",\n      \"auth\": {\n        \"CLIENT_ID\": \"mainbook-cursor\",\n        \"scopes\": [\"mainbook:read\", \"mainbook:convert\"]\n      }\n    }\n  }\n}\n```\n\nA client that cannot sign in can still send a legacy key from\n[mainbook.ai/developer](https://mainbook.ai/developer):\n\n```text\nAuthorization: Bearer mb_live_REPLACE_ME\n```\n\nEither credential is read from each request, so every user of a client reaches their own MainBook\naccount and spends their own page credits. `initialize` and `tools/list` answer without a\ncredential; every tool call requires one. Local file paths and `output_folder` do not exist over HTTP — pass `file_url` instead\nof `file_path`, because the server's disk is not yours. XLSX or CSV results come back as a\none-time download link (ten minutes, single use) for OAuth sessions, or as a REST download\ninstruction for a legacy `mb_live_` key.\n\nYou can also run the same remote mode yourself. It is stateless Streamable HTTP with JSON responses:\n\n```bash\nmainbook-mcp --transport http --host 127.0.0.1 --port 8000\n```\n\nThe MCP endpoint is then `http://127.0.0.1:8000/mcp`. Each client should send its own header:\n\n```text\nAuthorization: Bearer mb_live_REPLACE_ME\n```\n\nThe header is read from each tool-call request and never stored in global state. Hosted HTTP mode\ndoes not inspect `MAINBOOK_API_KEY`, the OS keyring, or the local credential file. For Codex remote\nmode:\n\n```toml\n[mcp_servers.mainbook]\nurl = \"https://mcp.mainbook.ai/mcp\"\nbearer_token_env_var = \"MAINBOOK_API_KEY\"\ntool_timeout_sec = 920\ndefault_tools_approval_mode = \"writes\"\n```\n\nReplace the URL with your own host if you deploy this yourself; a self-hosted deployment still needs\nnormal HTTPS termination and access controls.\n\n### OAuth on the hosted service\n\nAccount sign-in is live on `https://mcp.mainbook.ai/mcp` (since 2026-08-20). The verifier stays\ndisabled by default in this source tree, so a deployment you run yourself has to enable it\ndeliberately. Wherever it is enabled, `initialize` and `tools/list` remain public, while each tool\ncall accepts either an existing `mb_live_` key or a MainBook RS256 access token. OAuth tokens are verified locally against only the\nconfigured MainBook JWKS URL; they are never forwarded to the Developer API. The MCP server sends a\nfresh 60-second `X-MainBook-Service` credential for every internal REST request instead.\n\nThe hosted tool scopes are fixed in one map: `convert_bank_statement` requires\n`mainbook:convert`; `get_balance`, `get_conversion`, and `list_conversions` require\n`mainbook:read`. Protected-resource metadata is published at\n`/.well-known/oauth-protected-resource/mcp` only while the flag is enabled.\n\n## Environment variables\n\n- `MAINBOOK_API_KEY`: optional in stdio and takes precedence over a stored login; ignored in HTTP\n  mode, where every tool call must carry its own Bearer header.\n- `MAINBOOK_API_BASE_URL`: REST host, default `https://api.mainbook.ai`. The server appends\n  `/api/v1/developer`.\n- `MAINBOOK_ALLOWED_DIRS`: local folders allowed for source reads and result writes, separated by the platform's\n  `os.pathsep` (`:` on macOS/Linux and `;` on Windows). Positional directory arguments take\n  priority. If neither is supplied, the defaults are `~/Downloads`, `~/Desktop`, and\n  `~/Documents`.\n- `MAINBOOK_MCP_TRANSPORT`: `stdio` (default) or `http`.\n- `MAINBOOK_MCP_HOST`: HTTP bind host, default `127.0.0.1`.\n- `MAINBOOK_MCP_PORT`: HTTP bind port, default `8000`.\n- `MAINBOOK_MCP_OAUTH_ENABLED`: hosted OAuth verifier feature flag, default `false`. With the flag\n  off, metadata is absent and hosted Bearer handling remains the legacy `mb_live_` behavior.\n- `MAINBOOK_MCP_OAUTH_ISSUER`: exact trusted issuer, default `https://api.mainbook.ai`.\n- `MAINBOOK_MCP_OAUTH_JWKS_URL`: trusted JWKS URL, default\n  `https://api.mainbook.ai/.well-known/jwks.json`. Token header URLs are ignored.\n- `MAINBOOK_MCP_OAUTH_RESOURCE`: exact audience/resource, default\n  `https://mcp.mainbook.ai/mcp`.\n- `MAINBOOK_MCP_OAUTH_CLOCK_SKEW_SECONDS`: NumericDate clock allowance, default `5`.\n- `MAINBOOK_MCP_OAUTH_MAX_TOKEN_AGE_SECONDS`: maximum accepted age from `iat`, default `600`.\n- `MAINBOOK_MCP_OAUTH_JWKS_CACHE_TTL_SECONDS`: JWKS cache lifetime, default `300`.\n- `MAINBOOK_MCP_OAUTH_JWKS_REFRESH_MIN_INTERVAL_SECONDS`: minimum interval between unknown-`kid`\n  refresh attempts, default `30`.\n- `MCP_SERVICE_SIGNING_SECRETS`: comma-separated service-door secrets. MCP signs with the first;\n  Django may accept current and previous values during rotation. Required when OAuth is enabled;\n  never commit it.\n\n## File and network safety\n\n- `file_path` and `file_url` are mutually exclusive. `file_path` is accepted only over local\n  stdio; HTTP mode rejects it before the filesystem loader runs and requires `file_url`.\n- Local `file_path` access and result-file writes use the same configured folders. Positional CLI directories take\n  priority over `MAINBOOK_ALLOWED_DIRS`; the environment takes priority over the defaults\n  `~/Downloads`, `~/Desktop`, and `~/Documents`. Every root is expanded and resolved, missing\n  roots are ignored, and the active roots are printed to stderr when the server starts. If no\n  roots remain, local access fails closed while the server continues running.\n- Output parents are resolved before writing and checked by directory identity, so a symlink cannot\n  redirect a result outside the allowed folders. Result creation is exclusive and collision-safe;\n  existing files are not overwritten.\n- `~/.mainbook/preferences.json` is replaced atomically. The `.mainbook` directory is mode `0700`\n  and the preference file is mode `0600`; malformed or unreadable preferences are ignored safely.\n- Terminal credentials use the OS keyring when the optional package is usable. The fallback\n  `~/.config/mainbook/credentials.json` is replaced atomically inside a mode `0700` directory and\n  is mode `0600`; its top-level entries are keyed by API base URL.\n- Local paths are expanded and strictly resolved before the allowlist check, so `..` and symlinks\n  cannot make an outside target appear to be inside an allowed folder. The resolved path must be\n  strictly below a root, not equal to the root itself.\n- The local file is opened once. The server uses `fstat` on that descriptor to require a regular\n  file and enforce the 50 MiB limit, then performs the bounded read through the same descriptor.\n  This closes the check-versus-read replacement window, but it does not fully eliminate the race\n  between resolving the path and opening it; the path can still be replaced during that interval.\n- A local file must contain `%PDF-` within its first 1024 bytes before `pypdf` is invoked. Filename\n  extensions are not used to decide whether a file is a PDF.\n- Remote files must use HTTPS. Redirects are not followed.\n- DNS answers are rejected if any address is private, loopback, link-local, metadata, reserved, or\n  otherwise non-public, for IPv4 and IPv6.\n- URL downloads connect to an already validated numeric IP while retaining the original hostname\n  for TLS certificate verification and the HTTP `Host` header, closing DNS-rebinding races.\n- `Content-Length` and the actual streamed byte count are independently capped at 50 MiB.\n- PDFs are parsed locally with `pypdf` and capped at 500 pages.\n- Presigned upload headers from MainBook are forwarded unchanged; the MainBook Bearer key is never\n  sent to storage.\n\n## Development checks\n\n```bash\n.venv/bin/python -m pip install '.[dev]'\n.venv/bin/pytest\n.venv/bin/pytest --cov=mainbook_mcp --cov-report=term-missing --cov-report=annotate:cov_annotate\n.venv/bin/ruff check .\n```\n\nAll REST tests use mocks or a local stub. No test requires or accepts a real MainBook API key.\n",
  "bytes": 17310,
  "sha": "acb3e9f8f7afc1c78d4488ec9458ba5fa19da2da80cfbb1b0721f1e9cbe9b51e",
  "repo_slug": "human-beyond/mainbook-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_mainbook_bank_statement_converter_74340fe5/readme"
}