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
• The ISO 20022 MCP Suite — the four coordinated servers and when to use each
• 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.

The ISO 20022 MCP Suite

bankstatementparser-mcp is the ingestion layer of four coordinated, vendor-neutral MCP servers that together cover the ISO 20022 bank-statement workflow — statement depth, whole-catalogue routing, reconciliation, and multi-format ingestion. Dependency ranges are kept aligned across the suite, so the servers co-install cleanly in a single Python environment: start with one, add the rest as your workflow grows.

In one line each: camt053-mcp is the bank-statement flagship (deepest camt.05x surface, stdio + authenticated streamable HTTP); iso20022-mcp is the generic message toolkit (a handful of verbs over the whole catalogue); reconcile-mcp is the reconciliation workflow (did the money we expected actually arrive?); and bankstatementparser-mcp is the ingestion layer (many formats in, one transaction shape out).

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

The four core servers of the ISO 20022 MCP Suite are compared in The ISO 20022 MCP Suite above. The wider family — open-source, Apache-2.0 licensed MCP servers for banking and financial-services AI agents — also includes:

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