io.github.sebastienrousseau/bankstatementparser-mcp

Official

by sebastienrousseau · Python

MCP server for parsing bank statements (BAI2, MT940/MT942, CAMT.053, OFX) via stdio.

The MCP server exposes the bankstatementparser library as a first-class set of agent tools for reading bank statements, supporting standard formats via stdio. It functions as a Model Context Protocol server, enabling integration with AI agents and automated workflows in fintech environments.

🛠️ Key Features

MCP server interface for bank statement parsing
Supports BAI2, MT940/MT942, CAMT.053, and OFX formats
Exposes bankstatementparser capabilities as agent tools
Python-based implementation with stdio communication
Topics include financial services, ISO 20022, and fintech

🚀 Use Cases

Auto-extraction of transactions from bank statements
Feeding parsed data into accounting or reconciliation pipelines
Integration with AI agents for financial workflow automation

⚡ Developer Benefits

Clear MCP endpoint to leverage bankstatementparser capabilities
Extendable for additional formats and parsing rules
Lightweight stdio-based communication for scripting and automation
Rich readme excerpt and repository context for quick onboarding

⚠️ Limitations

Specific format support limited to listed standards (BAI2, MT940/MT942, CAMT.053, OFX)
Performance and accuracy depend on input quality and statement variations
Requires environment capable of running Python MCP server and stdio I/O

Topics

ai-agentsbank-statementbankingcamt053claudefinancial-servicesfintechiso20022mcpmcp-servermodel-context-protocolmt940ofxpythonbankstatementparser

README.md22 KBView on GitHub

bankstatementparser-mcp logo

bankstatementparser-mcp

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

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.

Concern	How bankstatementparser-mcp handles it
Transport	stdio (FastMCP default); zero config beyond the client manifest
Input model	Inline content + filename hint; no shared filesystem required
Format fidelity	Tools delegate to `bankstatementparser`'s `create_parser` pipeline
Format detection	`detect_format` mirrors the library's `detect_statement_format`
Validation	`validate_statement` is a dry run that returns structured results
Isolation	Each call writes to a private temp file that is deleted on exit

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.

Server	Scope	Surface	Install	Use it when
`camt053-mcp`	ISO 20022 `camt.053`/`camt.052` bank statements: parse, validate, filter, reverse; MT940/MT942 migration; CBPR+ readiness; journal export	22 MCP tools · 4 prompts · 3 resources	`pip install camt053-mcp`	You work with bank-to-customer statements end to end — the suite's flagship
`iso20022-mcp`	Unified gateway: `search` / `describe` / `validate` / `generate` / `parse` meta-tools routed across the `pain` · `pacs` · `camt` · `acmt` families	7 meta-tools	`pip install "iso20022-mcp[all]"`	You want one entry point to every message family
`reconcile-mcp`	Matches expected `pain.001` payments against observed `camt.053` entries — exact, partial, one-to-many, many-to-one, every match scored and explained	7 MCP tools	`pip install reconcile-mcp`	You need explainable statement/payment reconciliation
`bankstatementparser-mcp`	Multi-format statement ingestion: ISO 20022 CAMT.053 and pain.001, SWIFT MT940, OFX/QFX, CSV	5 MCP tools · 1 prompt · 1 resource	`pip install bankstatementparser-mcp`	Your statements arrive in mixed or legacy formats — this package
`structured-address-fix-mcp`	ISO 20022 postal-address classification, assessment & remediation for the November 2026 structured-address cutover, plus a high-level orchestration layer — readiness scoring, clearing-profile linting, and audit evidence (`pacs.008` / `pain.001` debtor & creditor addresses)	9 MCP tools	`pip install structured-address-fix-mcp`	You need debtor/creditor addresses cliff-ready ahead of 14 Nov 2026
`iso20022-readiness-suite-mcp`	Orchestration gateway: detect → structurally validate → clearing-profile lint → readiness score, plus automated remediation and `pacs.002` bank-response simulation — a meta-client over the foundational servers	4 MCP tools	`pip install iso20022-readiness-suite-mcp`	You want one high-level readiness / orchestration entry point over the suite
`iso20022-bank-profile-mcp`	Manages, validates and serves bank-specific clearing profiles / rule packs (CBPR+, SEPA_Instant, FedNow, Generic); premium rule-pack entitlement gating	4 MCP tools	`pip install iso20022-bank-profile-mcp`	You lint payments against your own institution's market practice
`iso20022-evidence-pack-mcp`	Compiles readiness findings, remediation diffs and simulated responses into a sealed, Ed25519-signable audit evidence pack	6 MCP tools	`pip install iso20022-evidence-pack-mcp`	You need tamper-evident audit / certification artifacts

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

Channel	Command	Notes
PyPI	`pip install bankstatementparser-mcp`	Pulls in `bankstatementparser >= 0.0.18` + MCP SDK
Source	`git clone https://github.com/sebastienrousseau/bankstatementparser-mcp && cd bankstatementparser-mcp && poetry install`	For development
Docker (GHCR)	`docker pull ghcr.io/sebastienrousseau/bankstatementparser-mcp:latest`	Multi-arch (linux/amd64, linux/arm64); runs `bankstatementparser-mcp` over stdio

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

json

{
  "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.

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:

python

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.

python

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.

bash

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

Target	What it runs
`make check`	All gates (REQUIRED before commit)
`make test`	`pytest --cov=bankstatementparser_mcp --cov-branch --cov-fail-under=100`
`make lint`	`ruff check` + `black --check`
`make type-check`	`mypy --strict`
`make docs`	`interrogate --fail-under=100` (docstring coverage)

Current state (v0.0.19): 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.

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:

Server	Purpose
`pain001-mcp`	Generate & validate ISO 20022 pain.001 payment files (v03–v12, pain.008, SEPA) with rulebook checks
`pacs008-mcp`	Generate, validate, parse & scheme-check ISO 20022 pacs.008 FI-to-FI credit transfers + Nov-2026 address linting
`acmt001-mcp`	Generate & validate ISO 20022 acmt account-management messages
`noyalib-mcp`	Lossless YAML 1.2 parsing, formatting & validation (Rust, 100% spec compliance)

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:

Package	GitHub Repository	Role	Description
`bankstatementparser`	`sebastienrousseau/bankstatementparser`	Core Engine	Unified parser for CAMT (052/053), PAIN.001, CSV, OFX, QFX, MT940, and PDF statements
`bankstatementparser-mcp`	`sebastienrousseau/bankstatementparser-mcp`	AI Protocol	Model Context Protocol (MCP) server exposing statement tools to LLMs & AI agents
`bankstatementparser-lsp`	`sebastienrousseau/bankstatementparser-lsp`	Developer Tooling	Language Server Protocol (LSP) with live SWIFT MT940 statement validation & diagnostics
`bankstatementparser-transport-ebics`	`sebastienrousseau/bankstatementparser-transport-ebics`	Transport	Automated bank statement retrieval over EBICS 3.0 (`H005`) and 2.5 (`H004`) protocols
`bankstatementparser-writer-xlsx`	`sebastienrousseau/bankstatementparser-writer-xlsx`	Output Writer	Formats and exports parsed banking transactions into styled Microsoft Excel (`.xlsx`) workbooks
`bankstatementparser-writer-qif`	`sebastienrousseau/bankstatementparser-writer-qif`	Output Writer	Serializes transactions into standard Quicken Interchange Format (`.qif`) exchange files
`bankstatementparser-writer-ofx`	`sebastienrousseau/bankstatementparser-writer-ofx`	Output Writer	Serializes transactions into standard Open Financial Exchange (`.ofx`) XML/SGML files
`bankstatementparser-writer-swift`	`sebastienrousseau/bankstatementparser-writer-swift`	Output Writer	Exports transactions to SWIFT MT940 customer statements and MT942 interim reports
`bankstatementparser-loader-bai2`	`sebastienrousseau/bankstatementparser-loader-bai2`	Input Loader	Parses BAI2 cash-management and account balance statements
`bankstatementparser-loader-mt942`	`sebastienrousseau/bankstatementparser-loader-mt942`	Input Loader	Parses SWIFT MT942 interim transaction reports with credit/debit summary reconciliation
`bankstatementparser-loader-cfonb`	`sebastienrousseau/bankstatementparser-loader-cfonb`	Input Loader	Parses French CFONB 120 / AFB120 120-byte fixed-width banking statement files
`bankstatementparser-loader-camt054`	`sebastienrousseau/bankstatementparser-loader-camt054`	Input Loader	Ingests ISO 20022 CAMT.054 real-time debit/credit notification stream XML
`bankstatementparser-loader-sepa`	`sebastienrousseau/bankstatementparser-loader-sepa`	Input Loader	Ingests ISO 20022 SEPA PAIN.002 payment status reports and PAIN.008 direct debit mandates
`bankstatementparser-loader-bacs`	`sebastienrousseau/bankstatementparser-loader-bacs`	Input Loader	Parses UK BACS Standard 18 / Faster Payments 106-byte fixed-width transmission files

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

Install

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "bankstatementparser-mcp": {
      "command": "uvx",
      "args": [
        "bankstatementparser-mcp"
      ]
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

bankstatementparser-mcp

Contents

What is bankstatementparser-mcp?

The ISO 20022 MCP Suite

Install

Quick start

Tools

Using the tools

When not to use bankstatementparser-mcp

Development

Security

Documentation

Contributing

Related MCP Servers

MCP Registry

Ecosystem

License

Install