bankstatementparser-mcp

bankstatementparser-mcp

Model Context Protocol server exposing the bankstatementparser library as first-class agent tools for reading bank statements.

Contents

Getting started

• What is bankstatementparser-mcp? — the problem it solves
• Install — PyPI, virtualenv, Docker
• Quick start — register with Claude Desktop in 30 seconds

Library reference

• Tools — the five tools, one resource, one prompt
• Using the tools — call them in-process from Python

Operational

• When not to use bankstatementparser-mcp — honest boundaries
• Development — gates, make targets
• Security — sandboxing posture
• Documentation — examples, guides
• Contributing — how to get changes in
• License — Apache-2.0

What is bankstatementparser-mcp?

The Model Context Protocol (MCP) isan open standard that lets AI agents discover and call external tools ina uniform way. bankstatementparser-mcp is the MCP server that turns thebankstatementparserlibrary into first-class agent tools — so an assistant can read,validate, and summarise bank statements in formats such as ISO 20022CAMT.053, SWIFT MT940, OFX/QFX, and CSV directly from a conversation.

Every tool is a thin wrapper over the bankstatementparser parser core(create_parser, detect_statement_format), so the results behaveidentically to the CLI. Because an MCP client does not share theserver's filesystem, the tools take inline statement content (plus afilename hint) and materialise it in a private temporary file for theduration of a single call. Tools return JSON-serialisable data.

Install

Requires Python 3.10 or later. Works on macOS, Linux, and Windows.

python -m venv venv
source venv/bin/activate        # macOS/Linux
venv\Scripts\activate           # Windows
python -m pip install -U bankstatementparser-mcp

Quick start

Register the server with any MCP client (Claude Desktop shown):

{
  "mcpServers": {
    "bankstatementparser": { "command": "bankstatementparser-mcp" }
  }
}

That's it. Restart the client and the tools are available to the agent.

The server speaks JSON-RPC over stdin/stdout — it is meant to belaunched by an MCP client, not used interactively.

Tools

All tools delegate to the bankstatementparser parser core, so theybehave identically to the library.

Plus one resource and one prompt:

Supported formats: camt (ISO 20022 CAMT.053, .xml), pain001(ISO 20022 pain.001, .xml), csv (.csv), ofx (.ofx), qfx(.qfx), and mt940 (SWIFT MT940, .mt940 / .sta).

Using the tools

The tools are plain functions on the bankstatementparser_mcp.servermodule, so you can call them in-process:

from bankstatementparser_mcp.server import (
    detect_format,
    parse_statement,
    summarize_statement,
)

csv = (
    "date,description,amount,currency,balance\n"
    "2023-01-02,Salary,500.00,EUR,1500.00\n"
    "2023-01-03,Groceries,-40.50,EUR,1459.50\n"
)

# 1. Detect the format from the filename hint + content.
print(detect_format(csv, "statement.csv"))
# -> csv

# 2. Parse the statement into structured rows + a summary.
parsed = parse_statement(csv, "statement.csv")
print(parsed["transaction_count"], parsed["columns"])

# 3. Read just the opening/closing balances.
print(summarize_statement(csv, "statement.csv"))

The resource and prompt are plain functions too: formats_resourcebacks bankstatementparser://formats, and analyze_statement returnsthe guided multi-step prompt.

from bankstatementparser_mcp.server import (
    analyze_statement,
    formats_resource,
)

print(formats_resource())          # the supported-formats catalogue
print(analyze_statement("statement.csv"))  # the guided analysis prompt

See the examples/ folder for runnable walkthroughs,including 04_resource_and_prompt.py.

When not to use bankstatementparser-mcp

• You're not driving an MCP-aware agent. Use thebankstatementparserCLI or library directly — it exposes the same surface with lessindirection.
• You need to parse files already on disk in bulk. The library'sCLI reads paths directly and avoids the inline-content round-trip theMCP tools use.

Development

bankstatementparser-mcp uses Poetry andmise.

git clone https://github.com/sebastienrousseau/bankstatementparser-mcp.git
cd bankstatementparser-mcp
mise install
poetry install

A Makefile orchestrates the quality gates (kept in lockstep with CI):

Current state (v0.0.12): 100% line + branch coverage against a 100%enforced floor, mypy --strict clean, interrogate 100%.

Security

• No persistent filesystem writes from tools. Each call writes theinline content to a private temporary file that is deleted as soon asthe call returns.
• Validation failures from validate_statement are returned asstructured {"is_valid": false, "error": ...} payloads — never asstack traces.
• Dependencies are pinned via poetry.lock and audited bypip-audit and Bandit in CI.

To report a vulnerability, please useGitHub private vulnerability reportingrather than a public issue.

Documentation

• Runnable examples: examples/
• Release history: CHANGELOG.md
• MCP specification: modelcontextprotocol.io

Contributing

Contributions are welcome — see thecontributing instructions.Thanks to all thecontributorswho have helped build bankstatementparser-mcp.

License

Licensed under the Apache License, Version 2.0.Any contribution submitted for inclusion shall be licensed as above,without additional terms.

bankstatementparser.com · PyPI · GitHub