bank-statement-sheet-mcp

bank-statement-sheet-mcp

An MCP server that turns a PDF bank statement into transaction data that arrives with a pass/fail reconciliation verdict, so an agent knows whether the numbers are safe to write into a ledger.

Your PDF is uploaded over HTTPS to the Bank Statement Sheet API (bankstatementsheet.com), where it is parsed and checked. It is processed in memory; upload records are deleted within 24 hours and transactions are not permanently stored. If that is not acceptable for a given file, don't pass it — or point BSS_API_URL at your own deployment.

Why the verdict matters

Any tool can pull numbers out of a PDF. The problem is that a wrong number looks exactly like a right one: a bookkeeper imports it, the books don't balance, and nobody knows which row lied.

So every extracted row is checked against the statement's own printed running balance:

balance[i] + amount[i-1] === balance[i-1]

The result travels with the data. When it fails, verdict.ledger_safe is false and the transactions are withheld — an agent that pipes result.transactions into a voucher tool gets nothing to post. Retrieving them takes a second, explicit call, which is visible in the transcript for a human to see.

Install

{
  "mcpServers": {
    "bank-statement-sheet": {
      "command": "npx",
      "args": ["-y", "bank-statement-sheet-mcp"],
      "env": { "BSS_API_KEY": "bss_live_..." }
    }
  }
}

BSS_API_KEY is optional. Without it the server works on the free anonymous tier: 5 conversions per month, Excel and CSV export. Mint a key at bankstatementsheet.com/dashboard — a key uses the same plan and daily page limit as the account it belongs to.

Try it with no account and no file of your own:

Convert the demo bank statement and show me the reconciliation verdict.

Tools

convert_bank_statement

Input	Notes
file_path	Absolute path to a PDF on this machine.
bank	Defaults to auto-detect, which also handles banks with no dedicated parser.
order	chronological (default, oldest first — what ledger imports expect) or statement.
include_unverified_rows	Only after a failed verdict, and only after telling the user.
save_as	xlsx, csv free; fortnox, ofx, json need Pro.
use_demo_statement	Converts a hosted synthetic sample. No quota, no real data.

Returns verdict (status, ledger_safe, checks passed/total, method), transactions (each row flagged verified), totals, source (including the SHA-256 of the file, as an audit anchor), and any files written.

export_conversion

Writes a conversion to xlsx / csv / fortnox / ofx / json. Files whose data failed the check get an -UNVERIFIED filename suffix and an in-file warning — both come from the server and neither should be stripped.

Conversions are held server-side for 10 minutes. Past that, this tool re-converts the same file automatically (which costs one conversion from your quota) — but only after confirming the file still hashes to what was originally converted, and it reports loudly if the second verdict differs from the first.

check_account_status

Plan, quota remaining, and whether your API key was actually recognised. Worth calling if conversions are being refused: an unrecognised key silently falls back to the anonymous tier.

Configuration

Variable	Default	Purpose
BSS_API_KEY	—	Your key. Unset → anonymous tier.
BSS_API_URL	the hosted API	Point at your own deployment.
BSS_ALLOWED_DIRS	cwd + ~/Downloads	Colon-separated directories PDFs may be read from.
BSS_ALLOW_ANY_PATH	0	Set 1 to disable the allowlist.
BSS_MAX_FILE_MB	50
BSS_TIMEOUT_MS	180000
BSS_OUTPUT_DIR	alongside the input PDF	Where save_as writes.

The directory allowlist exists because this server reads local files and uploads them. The realistic threat is not a careless user, it's a prompt-injected agent asking for ~/Documents/tax-return.pdf. Paths are resolved through realpath first, so a symlink inside an allowed directory cannot point outside it, and a file is rejected unless its bytes actually begin with %PDF-.

There is no URL input, deliberately: it would turn this into a fetcher running with your network position, aimable at cloud metadata endpoints or intranet hosts, for a capability the agent already has.

What this server will not do

• Return extracted rows without a verdict attached.
• Hand over rows that failed the balance check without an explicit, separate request.
• Rename a file to remove the server's -UNVERIFIED marker.
• Silently re-upload a file whose bytes changed since it was converted.

Licence

MIT. The extraction engine and the accuracy gate run server-side and are not part of this package.