# sebastienrousseau/camt053-mcp [Health: Active] **Category:** 💰 Finance & Fintech **Repository:** https://github.com/sebastienrousseau/camt053-mcp **GitHub Stars:** 1 **Views:** 3 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/sebastienrousseau-camt053-mcp ## Description ISO 20022 bank-statement parsing + reversing entries (camt.053 Bank-to-Customer Statement). 19 tools + 3 resources + 4 guided prompts across message-type discovery, return-reason lookup, schema introspection, IBAN/BIC/LEI validation, camt.053 parsing + XSD validation, Nov 2026 CBPR+ cliff readiness check, curated SEPA / CBPR+ / HVPS+ rulebook citation lookup, accounting-platform journal export (Xero + QuickBooks Online), LLM-driven entry classification via MCP Sampling, entry listing/filtering, and one-shot validated reversing-entry XML generation. Built on the camt053 library (100% line + branch coverage, SLSA Build L3 + PEP 740 attestations, Apache-2.0). Install pip install camt053-mcp, run camt053-mcp. ## Tools Capabilities this server exposes over MCP: - **list_message_types** — List every supported ISO 20022 camt.05x message type and its name. Use this first, before any validation or generation call, to discover the exact ``message_type`` strings this server accepts. For the return-reason codes rather than message types, call ``list_return_reasons`` instead. Returns a list of ``{"message_type": ..., "name": ...}`` dictionaries, one per supported message type (e.g. ``camt.053.001.14``). - **list_return_reasons** — List every known ISO external return reason code with its name. Use this to discover the ``reason_code`` values that ``filter_entries`` and ``generate_reversal`` accept (e.g. ``AC04`` Closed Account). For the supported message types rather than reason codes, use ``list_message_types``. Returns a list of ``{"code": ..., "name": ...}`` dictionaries (e.g. ``{"code": "AC04", "name": "Closed Account Number"}``). - **get_required_fields** — List only the required input field names for a camt message type. Use this for a quick checklist of the mandatory columns before building reversing-entry records. When you need full type/format constraints (not just which fields are required), call ``get_input_schema`` instead. Args: message_type: A supported ISO 20022 camt.05x message type. - **get_input_schema** — Return the full JSON Schema for a message type's flat input record. Use this to learn every field, its type, and its constraints before assembling records, or to drive a form/UI. For just the required-field names use ``get_required_fields``; to actually check records against this schema use ``validate_records``. Args: message_type: A supported ISO 20022 camt.05x message type. - **validate_records** — Validate flat records against a message type's input JSON Schema. Use this on in-memory reversing-entry records to catch structural/type errors per row before generation. To validate a whole camt.05x *document* (XML) against its XSD instead, use ``validate_statement``. Returns a report ``{"valid": bool, "total": int, "valid_count": int, "errors": [...]}``. Args: message_type: A supported ISO 20022 camt.05x message type. records: One or more flat reversing-entry records to validate. - **validate_identifier** — Validate a single financial identifier (IBAN, BIC, or LEI). Use this for a one-off identifier check with a clear pass/fail. To validate identifiers embedded across a whole batch of records, prefer ``validate_records`` rather than calling this per field. Returns ``{"kind": str, "value": str, "valid": bool}``. Args: kind: One of ``"iban"``, ``"bic"``, or ``"lei"`` (case-insensitive). value: The identifier value to check. - **parse_statement** — Parse an incoming camt.05x statement XML string into structured data. Use this to turn a raw statement into a navigable dict (header, statements, accounts, balances, entries). To pull just the flat entry list use ``list_entries``; to only check the document is schema-valid use ``validate_statement``. Returns the parsed document as a JSON-serialisable dict (group header plus statements, each with its account, balances, and entries), or an ``{"error": ...}`` payload if the XML cannot be parsed. Args: xml: The raw statement XML as a string. - **convert_mt940_to_camt053** — Convert a legacy SWIFT MT940 statement into a camt.053 structure. Use this as the Phase-1 migration wedge: SWIFT MT940 customer statements retire in **November 2028**, so this tool bridges the gap by turning raw MT940 text into the same JSON-serialisable camt.053 document shape that ``parse_statement`` returns (group header plus statements, each with its account, balances, and entries). Downstream tools (``list_entries``, ``filter_entries``, ``classify_entry``, ``export_journal``) then work on the result unchanged. Wraps the ``camt053-loader-mt940`` library's ``parse_mt940``; the MT parsing itself is delegated (no MT grammar is reimplemented here). The resulting ``ParsedDocument`` is serialised with the same ``to_dict()`` the server's other parse tools use, so agents get a consistent structure. Nothing is read from or written to disk. Returns the converted document as a JSON-serialisable dict, or an ``{"error": ...}`` payload if the MT940 text cannot be parsed (e.g. a missing ``:20:`` reference or a malformed balance / statement line). Args: mt940_text: The raw MT940 statement text as a string. - **convert_mt942** — Convert a legacy SWIFT MT942 interim report into a camt.052 structure. Use this as the Phase-1 migration wedge for intraday reporting: SWIFT MT94x messages retire in **November 2028**, so this tool bridges the gap by turning raw MT942 *Interim Transaction Report* text into the same JSON-serialisable camt.052 (Bank-to-Customer Account **Report**) document shape the server's parse tools return (group header plus statements, each with its account, balances, and entries). MT942 is the intraday sibling of MT940: where MT940 maps to camt.053 (end-of-day statement), MT942 maps to camt.052, so the resulting ``message_type`` is ``camt.052.001.08``. Downstream tools (``list_entries``, ``filter_entries``, ``classify_entry``, ``export_journal``) then work on the result unchanged. Wraps the ``camt053-loader-mt942`` library's ``parse_mt942``; the MT parsing itself is delegated (no MT grammar is reimplemented here). The resulting ``ParsedDocument`` is serialised with the same ``to_dict()`` the server's other parse tools use, so agents get a consistent structure. Nothing is read from or written to disk. **Documented model limitation.** The ``camt053`` typed model is camt.053-statement-oriented: it has no dedicated field for camt.052's floor-limit (````) or transaction-summary (````) blocks. Rather than drop that data, the loader surfaces it on the balance list using clearly proprietary ``type_code`` values so consumers can recognise and filter them: ``:34F:`` floor limits become ``FLIMD`` / ``FLIMC`` balances, and ``:90D:`` / ``:90C:`` entry-count summaries become ``SUMD:`` / ``SUMC:`` balances (the ISO ``NbOfNtries`` count is encoded after the colon; the sum is the balance ``amount``). See the loader's README. Returns the converted document as a JSON-serialisable dict, or an ``{"error": ...}`` payload if the MT942 text cannot be parsed (e.g. a missing ``:20:`` reference or a malformed floor-limit / summary / statement line). Args: mt942_text: The raw MT942 interim transaction report text as a string. - **validate_statement** — Validate an incoming camt.05x statement XML against its XSD schema. Use this to confirm a document is well-formed and schema-valid before processing it. This checks XSD conformance only; for the Nov 2026 CBPR+ business rules use ``check_cbpr_readiness``, and to extract the data use ``parse_statement``. Detects the document's message type, validates it against the matching ISO 20022 schema, and returns a report ``{"valid": bool, "message_type": str, "errors": [...]}``. A well-formed but schema-invalid document yields ``valid=False`` with a populated ``errors`` list (and the detected ``message_type``); a valid one yields ``valid=True`` with no errors. Returns an ``{"error": ...}`` payload instead if the XML cannot be parsed (e.g. it is malformed or is not a camt ``Document``). Args: xml: The raw statement XML as a string. - **check_cbpr_readiness** — Check a camt.053 statement against the CBPR+ Nov 2026 acceptance rules. Use this to audit a statement for the business-rule changes (schema version, structured postal addresses) enforced from the Nov 2026 cutover. For plain XSD schema validity use ``validate_statement`` instead; for just the cutover date use ``get_cbpr_cutover_date``. A coordinated CBPR+ / Fedwire / CHAPS / T2 cutover lands on **14-16 November 2026**: unstructured-only postal addresses get rejected, ``camt.110/111`` exceptions and investigations become mandatory, and T2S R2026.NOV upgrades camt.053 / 054 to schema revision MR2026. This tool walks the supplied payload and reports every issue that will fail the Nov 2026 acceptance rules: * **Schema version** vs the CBPR+ current set (``camt.053.001.08`` / ``camt.053.001.13``); ``.02``-``.07`` are flagged as deprecated warnings; unknown / non-camt.053 namespaces as errors. * **Postal addresses**: every ```` is classified as fully structured, hybrid, or **unstructured-only** (```` without ```` + ```` siblings, the Nov 2026 reject case). Returns a dictionary ``{"cbpr_ready": bool, "schema_version": str | None, "checked_at": ISO-8601 UTC, "cutover_date": "2026-11-16", "issues": [...], "summary": {...}}``. ``cbpr_ready`` is ``True`` iff no ``severity="error"`` issue was raised. An ``{"error": ...}`` envelope is returned instead if the XML is malformed or refused by the hardened pre-flight (DOCTYPE / ENTITY / oversized payload). Args: xml: The raw camt.05x statement XML as a string. - **get_cbpr_cutover_date** — Return the official CBPR+ / Nov 2026 cutover date as ISO 8601. Use this to quote the enforcement date directly, without parsing a document. To actually audit a statement against the rules that take effect on that date, call ``check_cbpr_readiness`` instead. The cutover (``2026-11-16``) is the date after which the rules checked by ``check_cbpr_readiness`` are enforced by the major clearing systems; payments that fail will be rejected at receive-time. Surfaced as a discrete tool so agents can quote it directly without having to call a readiness check first. - **cite_rulebook** — Return a curated payments-rulebook citation for a single clause. Use this to quote one specific rule (with its canonical source URL) once you know the ``scheme``/``version``/``clause``. To discover which clauses exist first, call ``list_rulebook_clauses``. Looks up one well-known rule across the SEPA, CBPR+, and HVPS+ rulebooks and returns a short summary together with the canonical source URL so an agent can quote the rule and the operator can verify it against the official document. The registry is a curated convenience layer, not a verbatim reproduction of copyrighted text. Always defer to ``source_url`` for authoritative wording before relying on a citation for compliance or contractual decisions; the returned ``disclaimer`` field repeats this for the calling agent. Args: scheme: One of ``"SEPA"``, ``"CBPR+"``, or ``"HVPS+"`` (case sensitive). version: The rulebook version (e.g. ``"2025"`` or ``"2026"``). clause: A kebab-case clause identifier from ``list_rulebook_clauses``. Returns: A citation dict ``{"scheme", "version", "clause", "title", "summary", "source_url", "as_of", "disclaimer"}`` or an ``{"error": ...}`` payload if the citation is not in the registry. - **list_rulebook_clauses** — List the curated rulebook clauses the server can cite, optionally filtered. Use this to browse the citation registry and pick a ``clause`` id; then pass that id to ``cite_rulebook`` to fetch the full summary and source URL. Returns the full registry, optionally filtered by ``scheme`` and / or ``version``. Use the resulting ``clause`` values as input to ``cite_rulebook``. Args: scheme: Restrict to one scheme (e.g. ``"SEPA"``). ``None`` returns all schemes. version: Restrict to one version (e.g. ``"2026"``). ``None`` returns all versions. - **search_rulebook_vector** — Search the curated rulebook clauses by lexical-vector similarity. Use this when you know *what* a rule is about but not its exact ``scheme``/``version``/``clause`` id: describe it in natural language and get back the closest curated clauses, each with a similarity ``score``. Then pass the winning ``scheme``/``version``/``clause`` to ``cite_rulebook`` for the full citation, or browse everything with ``list_rulebook_clauses``. Retrieval is a **deterministic lexical-vector cosine** search over the same curated SEPA / CBPR+ / HVPS+ summaries that back ``cite_rulebook`` (no external, copyrighted, or auth-gated rulebook text is indexed). Each clause and the query are hashed into a fixed 256-dimension term-frequency vector (whole words plus character 3/4-grams, BLAKE2b-bucketed so results are reproducible across processes) and ranked by cosine distance with ``sqlite-vec``. It is offline and does **not** use a large neural embedding model, so the same query always yields the same ranking and no model download or network call happens at query time. ``sqlite-vec`` ships in the optional ``[vector]`` extra and is imported lazily; when it is not installed this returns a graceful ``{"error": ...}`` payload asking the operator to ``pip install 'camt053-mcp[vector]'`` rather than failing to import. Args: query: The natural-language search string. top_k: The maximum number of clauses to return (default ``5``, clamped to the corpus size). Returns: ``{"query", "top_k", "returned", "method", "results", "disclaimer"}`` where ``results`` is the ranked list of clause dicts (each with an added ``score``), or an ``{"error": ...}`` payload on a bad argument or a missing ``[vector]`` extra. - **export_journal** — Export a camt.053 statement as accounting-platform journal-entry payloads. Use this to reshape a statement's booked entries into ready-to-POST Xero or QuickBooks payloads (the tool builds the payloads only; it does not call any external API or write files). To discover the valid ``target`` values first, call ``list_export_journal_targets``. Parses the supplied statement and re-shapes every booked entry into a target-specific journal-entry payload ready for direct POST to the accounting platform's REST API. Supported targets (see ``camt053_mcp.export_journal.SUPPORTED_TARGETS``): * ``"xero"`` - returns a list of Xero ``BankTransactions`` payloads. Each entry maps to ``{Type, Reference, Date, BankAccount, Contact, LineAmountTypes, CurrencyCode, LineItems}``; CRDT entries become ``Type=RECEIVE`` and DBIT entries ``Type=SPEND``. * ``"qbo"`` - returns a list of QuickBooks Online ``JournalEntry`` payloads. Each entry produces a balanced two-line journal (one to the bank account, one to a clearing account; sign flipped on debit entries). Operator-specific values (account codes, contact identifiers, realm IDs) appear as ``"OPERATOR_FILL"`` placeholders so the operator knows exactly what still needs wiring. The response's ``placeholder_count`` field reports the total. NetSuite + SAP S/4HANA targets are tracked as a follow-up in #17. Args: xml: The raw camt.053 statement XML as a string. target: One of ``"xero"`` or ``"qbo"`` (default ``"xero"``). Returns: ``{"target", "entries", "placeholder_count", "placeholder_field"}`` on success, or ``{"error": ...}`` on failure (unsupported target / malformed XML / parse refusal). - **list_export_journal_targets** — List the accounting-platform targets the ``export_journal`` tool supports. Use this to tell a user which ``target`` values ``export_journal`` accepts before invoking it. This lists export destinations only; for the LLM classifier's category vocabulary use ``list_classify_entry_categories``. Returns the sorted list of valid ``target`` arguments accepted by ``export_journal`` (``["qbo", "xero"]`` today). NetSuite and SAP S/4HANA support is a tracked follow-up. - **classify_entry** — Classify one statement entry into a category via MCP LLM Sampling. Use this when you want a semantic, model-driven label for an entry (payroll, fee, refund, …) rather than a deterministic rule match. Because it delegates an LLM completion to the client it is open-world and non-idempotent; for the fixed candidate categories it chooses from, call ``list_classify_entry_categories`` first. Uses the **MCP Sampling** protocol primitive: the server (this process) asks the *client* (the agent's host application) to perform an LLM completion on the server's behalf, then receives the model's structured response. Keeps every LLM call in the operator's existing model contract (privacy, billing, audit). The model is asked to choose exactly one category from ``categories`` (or :data:`camt053_mcp.classify.DEFAULT_CATEGORIES` if ``None`` is passed) and return a structured ``{category, confidence, explanation}`` payload. Clients that do not support Sampling will get an ``{"error": "..."}`` envelope and can fall back to a rules-only classifier. Args: ctx: The MCPServer Context (auto-injected; provides ``session.create_message``). entry: A statement entry dict (the shape returned by ``parse_statement`` / ``list_entries``). categories: The candidate categories. ``None`` uses the built-in default list (12 common payment buckets). Returns: ``{"category", "confidence", "explanation"}`` on success or ``{"error": "..."}`` on Sampling failure / malformed model response / out-of-vocabulary category. - **list_classify_entry_categories** — List the default candidate categories the ``classify_entry`` tool uses. Use this to quote the built-in category vocabulary to a user before running the LLM classifier. This is a static list lookup (no model call); to actually classify an entry, call ``classify_entry``. Operators can override the list per call; this tool exposes the default the prompt template ships with so an agent can quote them to the user before invoking the classifier. - **get_tenant_context** — Return the multi-tenant scoping context of the current call. Use this to confirm which tenant/account scope the server attributes the session to. On the streamable-HTTP transport (D7, #42) the ``tenant`` field carries the value of the optional ``Camt053-Account`` request header the caller sent; over stdio (or when the caller sent no header) it is ``None``. The same value is stamped as the ``scope`` on the server's audit log, so an agent can verify its calls are attributed to the right tenant. The lookup is read-only and deterministic for a given request: nothing is validated or mutated, and no external system is touched. Args: ctx: The MCPServer Context (auto-injected; carries the underlying HTTP request, when there is one). Returns: ``{"service": "camt053-mcp", "tenant": str | None}``. - **list_entries** — List every booked entry across all statements in a camt.05x document. Use this to get the flat, paginable entry list from a statement. To keep only the entries carrying a given return-reason code use ``filter_entries``; for the full nested document structure use ``parse_statement``. When ``limit`` is ``None`` (the default) the full list of entries is returned. When ``limit`` is given, a paginated envelope ``{"total", "offset", "limit", "entries"}`` is returned instead, exposing the ``offset:offset + limit`` slice. A negative ``offset`` or ``limit`` yields an ``{"error": ...}`` payload. Args: xml: The raw statement XML as a string. offset: The zero-based index of the first entry to return (paginated mode only; default ``0``). limit: The maximum number of entries to return, or ``None`` for the full list (default ``None``). - **filter_entries** — List only the statement entries carrying a given return reason code. Use this to preview exactly which entries a reversal would touch before calling ``generate_reversal`` with the same ``reason_code``. For every entry regardless of reason code use ``list_entries`` instead. When ``limit`` is ``None`` (the default) the full list of matching entries is returned, preserving the behaviour expected by existing callers. When ``limit`` is given, a paginated envelope ``{"total", "offset", "limit", "entries"}`` is returned instead, exposing the ``offset:offset + limit`` slice. A negative ``offset`` or ``limit`` yields an ``{"error": ...}`` payload. Args: xml: The raw statement XML as a string. reason_code: The ISO external return reason to match (default ``"AC04"`` Closed Account). offset: The zero-based index of the first entry to return (paginated mode only; default ``0``). limit: The maximum number of entries to return, or ``None`` for the full list (default ``None``). - **detect_statement_anomalies** — Screen a camt.05x statement for deterministic, rule-based anomalies. Use this as a fast, explainable first pass over an incoming statement before deeper review or reversal. It applies three fixed heuristics over the parsed entry list (see ``list_entries``) and never calls out to a model or the network, so the same statement always yields the same result: * **Duplicate references** (severity ``HIGH``) -- two or more entries share an end-to-end id (or, absent one, an entry reference), a classic double-payment signal. * **Unusual fee deductions** (severity ``MEDIUM``) -- a fee/charge debit whose amount exceeds a fixed fraction (25%) of the largest ordinary transaction amount on the statement. * **Velocity spikes** (severity ``LOW``/``MEDIUM``) -- a booking-date window whose entry count runs far above the statement's median per-window count. Returns ``{"anomalies": [{"type", "severity", "detail", "entry_refs"}], "checked_entries": }``; ``anomalies`` is empty for a clean statement. Returns an ``{"error": ...}`` payload instead if the XML cannot be parsed. Args: statement_xml: The raw statement XML as a string. - **generate_reversal** — Generate a validated camt.053.001.14 reversal document from a statement. This is the headline one-shot workflow: pass an incoming statement and a return-reason code and get back the reversal XML (nothing is written to disk). Preview which entries will be reversed first with ``filter_entries`` using the same ``reason_code``. This is the headline one-shot workflow: parse the incoming camt.053, pick the entries with the requested return reason (e.g. AC04 Closed Account), and emit a validated camt.053.001.14 reversal statement. Returns the validated XML document as a string, or an ``{"error": ...}`` payload (serialized) if generation fails. Args: xml: The raw incoming statement XML as a string. reason_code: The ISO external return reason to reverse (default ``"AC04"``). ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `uvx` (confidence: high): ```json "mcpServers": { "camt053-mcp": { "command": "uvx", "args": ["camt053-mcp"] } } ``` ## Documentation ## What sebastienrousseau/camt053-mcp MCP server does The sebastienrousseau/camt053-mcp MCP server turns the camt053 ISO 20022 bank-statement library into MCP tools for AI clients. It works with camt.05x messages, including camt.053 statements and camt.052 reports produced through MT942 conversion. Inputs and outputs are handled in memory: statement XML and legacy MT text are supplied as strings, while parsed documents, validation reports, journal payloads, and generated XML are returned to the caller. The main reversal workflow accepts an incoming statement and an ISO return-reason code, selects matching entries, and produces a validated camt.053.001.14 reversal document. Supporting tools let an agent discover valid message types and reason codes, inspect schemas, validate records, and preview entries before generating a reversal. ## How it works Tools are exposed through MCP and delegate to the shared camt053 service layer. Parsing produces a structured document containing the group header, statements, accounts, balances, and entries. Flat entry-list tools provide filtering and optional pagination, while anomaly detection applies fixed rules for duplicate references, unusually large fee deductions, and transaction-count spikes. Validation operates at different levels. Record validation checks flat input data against a message-type JSON Schema. Statement validation checks XML against the matching ISO 20022 XSD. The CBPR+ readiness check separately evaluates supported camt.053 schema revisions and postal-address structure for the November 2026 acceptance rules. Rulebook search is limited to a curated, offline registry covering SEPA, CBPR+, and HVPS+ clauses. Its vector search uses deterministic lexical vectors rather than a hosted embedding service. Entry classification is different: classify_entry uses MCP Sampling to ask the connected client to perform an LLM completion, so clients without Sampling cannot use that tool. ## Setup and configuration Install the package with pip and launch the executable over the default stdio transport: ```sh python -m pip install camt053-mcp camt053-mcp ``` The package requires Python 3.10 or newer and runs on macOS, Linux, and Windows. A client configuration can register `camt053-mcp` as a stdio MCP server. The optional `vector` extra enables rulebook similarity search; without it, that tool returns an error directing the operator to install the extra. ## Tools and capabilities The sebastienrousseau/camt053-mcp MCP server includes capabilities for: - Discovering supported camt message types, return reasons, required fields, and complete input schemas. - Parsing camt.05x XML and converting MT940 or MT942 text into compatible structured documents. - Validating identifiers, records, XML/XSD conformance, and CBPR+ readiness. - Listing, paginating, filtering, classifying, and screening statement entries for anomalies. - Generating reversal XML for selected return reasons. - Creating Xero BankTransactions or QuickBooks Online JournalEntry payloads without calling either platform. - Browsing, searching, and citing curated SEPA, CBPR+, and HVPS+ rulebook clauses. Journal exports contain operator-fill placeholders for values such as account codes, contacts, and realm identifiers. The tool prepares payloads but does not post them to an accounting API. ## Limitations and notes The server does not write generated documents to disk or make external accounting-platform API calls. Rulebook citations are summaries with source URLs, not authoritative reproductions of the underlying rulebooks. MT942 data that has no dedicated field in the camt.053-oriented model is surfaced through documented proprietary balance type codes. The HTTP transport supports OAuth 2.1 resource-server authentication according to the repository material, while local stdio usage is the straightforward installation path. The CBPR+ readiness tool reports the cutover date as 2026-11-16 and checks the rules represented by the server; it is not a general certification of every clearing-system requirement. _Full upstream README: https://allmcps.com/mcp/sebastienrousseau-camt053-mcp/readme_