bankstatementparser-mcp

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

<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.11` + 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 st