<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->

<p align="center">
  <img
    src="https://cloudcdn.pro/bankstatementparser/v1/logos/bankstatementparser.svg"
    alt="bankstatementparser-mcp logo"
    width="120"
    height="120"
  />
</p>

<h1 align="center">bankstatementparser-mcp</h1>

<p align="center">
  <b>Model Context Protocol server exposing the bankstatementparser library as first-class agent tools for reading bank statements.</b>
</p>

<p align="center">
  <a href="https://pypi.org/project/bankstatementparser-mcp/"><img src="https://img.shields.io/pypi/v/bankstatementparser-mcp?style=for-the-badge" alt="PyPI version" /></a>
  <a href="https://pypi.org/project/bankstatementparser-mcp/"><img src="https://img.shields.io/pypi/pyversions/bankstatementparser-mcp.svg?style=for-the-badge" alt="Python versions" /></a>
  <a href="https://pypi.org/project/bankstatementparser-mcp/"><img src="https://img.shields.io/pypi/dm/bankstatementparser-mcp.svg?style=for-the-badge" alt="PyPI downloads" /></a>
  <a href="https://github.com/sebastienrousseau/bankstatementparser-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/bankstatementparser-mcp/ci.yml?branch=main&label=Tests&style=for-the-badge" alt="Tests" /></a>
  <a href="https://github.com/sebastienrousseau/bankstatementparser-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/sebastienrousseau/bankstatementparser-mcp/ci.yml?branch=main&label=Coverage&style=for-the-badge" alt="Coverage" /></a>
  <a href="#license"><img src="https://img.shields.io/pypi/l/bankstatementparser-mcp?style=for-the-badge" alt="License" /></a>
  <a href="https://glama.ai/mcp/servers/sebastienrousseau/bankstatementparser-mcp"><img src="https://glama.ai/mcp/servers/sebastienrousseau/bankstatementparser-mcp/badges/score.svg" alt="Glama MCP server score" /></a>
</p>

---

## Contents

**Getting started**

- [What is bankstatementparser-mcp?](#what-is-bankstatementparser-mcp) — the problem it solves
- [The ISO 20022 MCP Suite](#the-iso-20022-mcp-suite) — the four coordinated servers and when to use each
- [Install](#install) — PyPI, virtualenv, Docker
- [Quick start](#quick-start) — register with Claude Desktop in 30 seconds

**Library reference**

- [Tools](#tools) — the five tools, one resource, one prompt
- [Using the tools](#using-the-tools) — call them in-process from Python

**Operational**

- [When not to use bankstatementparser-mcp](#when-not-to-use-bankstatementparser-mcp) — honest boundaries
- [Development](#development) — gates, make targets
- [Security](#security) — sandboxing posture
- [Documentation](#documentation) — examples, guides
- [Contributing](#contributing) — how to get changes in
- [License](#license) — Apache-2.0

---

## What is bankstatementparser-mcp?

The [Model Context Protocol](https://modelcontextprotocol.io) (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`](https://github.com/sebastienrousseau/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`](https://github.com/sebastienrousseau/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`](https://github.com/sebastienrousseau/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`](https://github.com/sebastienrousseau/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`](#install) | 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`](https://github.com/sebastienrousseau/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`](https://github.com/sebastienrousseau/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`](https://github.com/sebastienrousseau/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`](https://github.com/sebastienrousseau/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.

<details>
<summary>Using an isolated virtual environment (recommended)</summary>

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

</details>

---

## Quick start

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

```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/`](examples/) folder for runnable walkthroughs,
including [`04_resource_and_prompt.py`](examples/04_resource_and_prompt.py).

---

## When not to use bankstatementparser-mcp

- **You're not driving an MCP-aware agent.** Use the
  [`bankstatementparser`](https://pypi.org/project/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](https://python-poetry.org/) and
[mise](https://mise.jdx.dev/).

```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](https://github.com/sebastienrousseau/bankstatementparser-mcp/security)
rather than a public issue.

---

## Documentation

- **Runnable examples:** [`examples/`](https://github.com/sebastienrousseau/bankstatementparser-mcp/tree/main/examples)
- **Release history:** [CHANGELOG.md](https://github.com/sebastienrousseau/bankstatementparser-mcp/blob/main/CHANGELOG.md)
- **MCP specification:** [modelcontextprotocol.io](https://modelcontextprotocol.io)

---

## Contributing

Contributions are welcome — see the
[contributing instructions](https://github.com/sebastienrousseau/bankstatementparser-mcp/blob/main/CONTRIBUTING.md).
Thanks to all the
[contributors](https://github.com/sebastienrousseau/bankstatementparser-mcp/graphs/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](#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`](https://github.com/sebastienrousseau/pain001-mcp) | Generate & validate ISO 20022 pain.001 payment files (v03–v12, pain.008, SEPA) with rulebook checks |
| [`pacs008-mcp`](https://github.com/sebastienrousseau/pacs008-mcp) | Generate, validate, parse & scheme-check ISO 20022 pacs.008 FI-to-FI credit transfers + Nov-2026 address linting |
| [`acmt001-mcp`](https://github.com/sebastienrousseau/acmt001-mcp) | Generate & validate ISO 20022 acmt account-management messages |
| [`noyalib-mcp`](https://github.com/sebastienrousseau/noyalib) | 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 | PyPI | Role | Description |
| :--- | :--- | :--- | :--- | :--- |
| **`bankstatementparser`** | [`sebastienrousseau/bankstatementparser`](https://github.com/sebastienrousseau/bankstatementparser) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser.svg)](https://pypi.org/project/bankstatementparser/) | Core Engine | Unified parser for CAMT (052/053), PAIN.001, CSV, OFX, QFX, MT940, and PDF statements |
| **`bankstatementparser-mcp`** | [`sebastienrousseau/bankstatementparser-mcp`](https://github.com/sebastienrousseau/bankstatementparser-mcp) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-mcp.svg)](https://pypi.org/project/bankstatementparser-mcp/) | AI Protocol | Model Context Protocol (MCP) server exposing statement tools to LLMs & AI agents |
| **`bankstatementparser-lsp`** | [`sebastienrousseau/bankstatementparser-lsp`](https://github.com/sebastienrousseau/bankstatementparser-lsp) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-lsp.svg)](https://pypi.org/project/bankstatementparser-lsp/) | Developer Tooling | Language Server Protocol (LSP) with live SWIFT MT940 statement validation & diagnostics |
| **`bankstatementparser-transport-ebics`** | [`sebastienrousseau/bankstatementparser-transport-ebics`](https://github.com/sebastienrousseau/bankstatementparser-transport-ebics) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-transport-ebics.svg)](https://pypi.org/project/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`](https://github.com/sebastienrousseau/bankstatementparser-writer-xlsx) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-writer-xlsx.svg)](https://pypi.org/project/bankstatementparser-writer-xlsx/) | Output Writer | Formats and exports parsed banking transactions into styled Microsoft Excel (`.xlsx`) workbooks |
| **`bankstatementparser-writer-qif`** | [`sebastienrousseau/bankstatementparser-writer-qif`](https://github.com/sebastienrousseau/bankstatementparser-writer-qif) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-writer-qif.svg)](https://pypi.org/project/bankstatementparser-writer-qif/) | Output Writer | Serializes transactions into standard Quicken Interchange Format (`.qif`) exchange files |
| **`bankstatementparser-writer-ofx`** | [`sebastienrousseau/bankstatementparser-writer-ofx`](https://github.com/sebastienrousseau/bankstatementparser-writer-ofx) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-writer-ofx.svg)](https://pypi.org/project/bankstatementparser-writer-ofx/) | Output Writer | Serializes transactions into standard Open Financial Exchange (`.ofx`) XML/SGML files |
| **`bankstatementparser-writer-swift`** | [`sebastienrousseau/bankstatementparser-writer-swift`](https://github.com/sebastienrousseau/bankstatementparser-writer-swift) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-writer-swift.svg)](https://pypi.org/project/bankstatementparser-writer-swift/) | Output Writer | Exports transactions to SWIFT MT940 customer statements and MT942 interim reports |
| **`bankstatementparser-loader-bai2`** | [`sebastienrousseau/bankstatementparser-loader-bai2`](https://github.com/sebastienrousseau/bankstatementparser-loader-bai2) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-bai2.svg)](https://pypi.org/project/bankstatementparser-loader-bai2/) | Input Loader | Parses BAI2 cash-management and account balance statements |
| **`bankstatementparser-loader-mt942`** | [`sebastienrousseau/bankstatementparser-loader-mt942`](https://github.com/sebastienrousseau/bankstatementparser-loader-mt942) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-mt942.svg)](https://pypi.org/project/bankstatementparser-loader-mt942/) | Input Loader | Parses SWIFT MT942 interim transaction reports with credit/debit summary reconciliation |
| **`bankstatementparser-loader-cfonb`** | [`sebastienrousseau/bankstatementparser-loader-cfonb`](https://github.com/sebastienrousseau/bankstatementparser-loader-cfonb) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-cfonb.svg)](https://pypi.org/project/bankstatementparser-loader-cfonb/) | Input Loader | Parses French CFONB 120 / AFB120 120-byte fixed-width banking statement files |
| **`bankstatementparser-loader-camt054`** | [`sebastienrousseau/bankstatementparser-loader-camt054`](https://github.com/sebastienrousseau/bankstatementparser-loader-camt054) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-camt054.svg)](https://pypi.org/project/bankstatementparser-loader-camt054/) | Input Loader | Ingests ISO 20022 CAMT.054 real-time debit/credit notification stream XML |
| **`bankstatementparser-loader-sepa`** | [`sebastienrousseau/bankstatementparser-loader-sepa`](https://github.com/sebastienrousseau/bankstatementparser-loader-sepa) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-sepa.svg)](https://pypi.org/project/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`](https://github.com/sebastienrousseau/bankstatementparser-loader-bacs) | [![PyPI](https://img.shields.io/pypi/v/bankstatementparser-loader-bacs.svg)](https://pypi.org/project/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](https://opensource.org/license/apache-2-0/).
Any contribution submitted for inclusion shall be licensed as above,
without additional terms.

---

<p align="center">
  <a href="https://bankstatementparser.com">bankstatementparser.com</a> ·
  <a href="https://pypi.org/project/bankstatementparser-mcp/">PyPI</a> ·
  <a href="https://github.com/sebastienrousseau/bankstatementparser-mcp">GitHub</a>
</p>