io.github.sebastienrousseau/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
• 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
• Transports — stdio, streamable HTTP (2026-07-28 and 2025-11-25) and SSE from one command line

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 eight coordinated, vendor-neutral MCP servers that together cover the ISO 20022 bank-statement workflow and the November 2026 structured-address cutover — statement depth, whole-catalogue routing, reconciliation, multi-format ingestion, and address remediation. 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?); bankstatementparser-mcp is the ingestion layer (many formats in, one transaction shape out); and structured-address-fix-mcp is the postal-address specialist (debtor/creditor addresses cliff-ready for the Nov 2026 cutover).

Install

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

Using an isolated virtual environment (recommended)

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.

By default the server speaks JSON-RPC over stdin/stdout — it is meant to be launched by an MCP client, not used interactively. For a shared deployment, see Transports.

Transports

One command line, three transports:

--host and --port change the bind address (defaults 127.0.0.1 and 8000). The HTTP transports carry no authentication of their own: bind loopback, or put the server behind a gateway you trust before binding a routable address. Every release is verified over streamable HTTP with passmcp in both protocol eras and over SSE with the MCP SDK client; see ADR 0001.

{
  "mcpServers": {
    "bankstatementparser": { "url": "http://127.0.0.1:8000/mcp" }
  }
}

Tools

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

• list_supported_formats — List every bank statement format the parser can read
• detect_format — Detect which statement format an inline payload is
• parse_statement — Parse a statement into structured transactions plus a summary
• validate_statement — Dry-run check whether a statement parses cleanly
• summarize_statement — Return only the statement summary (no per-transaction rows)

Plus one resource and one prompt:

• Resource bankstatementparser://formats — Read-only catalogue of supported formats and their file extensions
• Prompt analyze_statement — Guided multi-step prompt that walks an agent through reading and reconciling a statement

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.28): 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

Ecosystem

bankstatementparser is part of a modular financial ecosystem. Optional companion packages provide specialized loaders, writers, AI agents, language servers, and transport protocol adapters:

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