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) is an open standard that lets AI agents discover and call external tools in a uniform way. bankstatementparser-mcp is the MCP server that turns the bankstatementparser library into first-class agent tools — so an assistant can read, validate, and summarise bank statements in formats such as ISO 20022 CAMT.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 behave identically to the CLI. Because an MCP client does not share the server's filesystem, the tools take inline statement content (plus a filename hint) and materialise it in a private temporary file for the duration 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 be launched by an MCP client, not used interactively.

Tools

All tools delegate to the bankstatementparser parser core, so they behave 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.server module, 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_resource backs bankstatementparser://formats, and analyze_statement returns the 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 the bankstatementparser CLI or library directly — it exposes the same surface with less indirection.
• You need to parse files already on disk in bulk. The library's CLI reads paths directly and avoids the inline-content round-trip the MCP tools use.

Development

bankstatementparser-mcp uses Poetry and mise.

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.13): 100% line + branch coverage against a 100% enforced floor, mypy --strict clean, interrogate 100%.

Security

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

To report a vulnerability, please use GitHub private vulnerability reporting rather than a public issue.

Documentation

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

Contributing

Contributions are welcome — see the contributing instructions. Thanks to all the contributors who have helped build bankstatementparser-mcp.

Related MCP Servers

Part of the ISO 20022 MCP Suite — open-source, Apache-2.0 licensed MCP servers for banking and financial-services AI agents:

MCP Registry

mcp-name: io.github.sebastienrousseau/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