Bankstatemently

Official18 toolsLive

by bankstatemently

Convert PDF bank statements into structured transactions, accounts, and balances.

Bankstatemently MCP Server (io.github.bankstatemently/bankstatemently-mcp)

This MCP server converts PDF bank statements into structured transactions, accounts, and balances. The project is associated with “bankstatemently/plugins,” described as marketplace plugins for Bankstatemently that perform the statement-to-structured-data conversion. It is available through the Claude Code marketplace installation flow.

🛠️ Key Features

Converts PDF bank statements into structured transactions
Produces structured accounts
Extracts structured balances
Tool set: 16 tools

🚀 Use Cases

Turn bank statement PDFs into structured transaction data
Generate account and balance information from statement documents

⚡ Developer Benefits

Use via Claude Code marketplace plugin installation
Configure with an api_key using a bsk_live_... key

⚠️ Limitations

Requires an API key to enable the plugin

Topics

claude-codemcpmarketplacepluginbank-statementchatgptmodel-context-protocol

Captured live from the server via tools/list.

request_upload

Mint a single-use upload URL for pushing a conversation-attached PDF to Bankstatemently before converting it. Use this ONLY when you have no other way to reference the attached file (no pdf_file/pdf_url equivalent for this host) — e.g. a code-execution sandbox that can see the file on disk but has no URL for it. Playbook: (1) check your sandbox's uploads/attachments directory first — if the file isn't there yet, the mount can lag behind the conversation; ask the user to re-attach or wait a moment and check again before calling this tool. (2) Call request_upload to get upload_url and upload_id. (3) PUT the raw PDF bytes to upload_url with header Content-Type: application/pdf, e.g.: `curl -X PUT "<upload_url>" -H "Content-Type: application/pdf" --data-binary @<path-to-file>`. (4) Once the PUT succeeds, call convert_statement with upload_id set to the same value — never pdf/pdf_url/pdf_file for this flow. The URL and token are single-use and expire quickly; call request_upload again for a fresh one if the PUT fails partway through — never retry a failed PUT against the same URL. If the PUT fails with a network error or a "host not allowed"-style denial, the sandbox is likely blocking outbound requests to api.bankstatemently.com — tell the user to add api.bankstatemently.com to their host's code-execution allowed-domains setting (on claude.ai: Settings → Capabilities → Code execution) and retry. To convert several statements at once, pass count (1-100) instead of calling this tool once per file: the response returns "uploads", an array of that many { upload_id, upload_url } pairs — PUT each file to its own upload_url, then make ONE convert_statement call with upload_ids set to every upload_id. Free to use — no credits consumed (conversion itself still costs credits, same as any other convert_statement call).

Parameters1

count

integer

optional

Batch size — mint this many independent single-use upload URLs in one call instead of calling request_upload once per file. When set, the response returns "uploads": an array of that many { upload_id, upload_url } pairs. Omit for the default single-URL response.

Raw schema

{
  "type": "object",
  "properties": {
    "count": {
      "description": "Batch size — mint this many independent single-use upload URLs in one call instead of calling request_upload once per file. When set, the response returns \"uploads\": an array of that many { upload_id, upload_url } pairs. Omit for the default single-URL response.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

convert_statement

Convert a bank statement PDF into structured data or a spreadsheet. When the user attaches a PDF in the conversation, it arrives automatically as pdf_file — never encode it yourself. Otherwise, pass pdf_url for a public HTTPS link. If your host has no way to reference the attached file at all (no pdf_file/pdf_url equivalent), call request_upload first and pass its upload_id here instead. The base64 pdf parameter is a last resort only, for a caller with no other way to reference the file. To convert several statements in one call, pass upload_ids (the array from a single request_upload call made with count set) instead of pdf/pdf_url/pdf_file/upload_id — mutually exclusive with those four. This batch form only ADMITS each file (queues it, or reports an already-completed duplicate) and returns immediately with a compact per-file status list plus a summary — it never waits for conversion, so call get_statement per document_id once ready rather than expecting inline results here. Returns accounts, transactions, and metadata. output_format "json" (default) returns the data inline, renderable in chat. The other formats (csv, xlsx, qbo, xero) return a time-limited download link instead: present it as a normal link. Every response includes a "summary" field: use it as the single source of truth for what happened. If the conversation is not in English, translate it faithfully into the conversation language; never add details it doesn't contain. Never echo raw status values (e.g. "completed") or field names. Consumes credits (1 per page). Page limit depends on your plan.

Parameters7

pdf_file	object	optional	An attached PDF (populated automatically by ChatGPT — do not construct this yourself).
pdf	string	optional	Base64-encoded PDF content — last resort only; prefer pdf_file for an attachment or pdf_url for a link
pdf_url	string	optional	HTTPS URL to fetch the PDF from
upload_id	string	optional	An upload_id from request_upload, after PUTting the file to its upload_url. Use this only when your host has no other way to reference the attached file (no pdf_file/pdf_url equivalent).
upload_ids	array	optional	Batch of upload_ids from a single request_upload(count) call, each already PUT to its own upload_url — converts many statements in one call. Mutually exclusive with pdf, pdf_url, pdf_file, and upload_id. Admission only: the response reports per-file status immediately, never waiting for conversion — fetch results per document_id via get_statement.
password	string	optional	Password for encrypted PDFs
output_format	string	optional	Output format

Raw schema

{
  "type": "object",
  "properties": {
    "pdf_file": {
      "description": "An attached PDF (populated automatically by ChatGPT — do not construct this yourself).",
      "type": "object",
      "properties": {
        "download_url": {
          "type": "string",
          "description": "Signed URL ChatGPT provides to fetch the attached PDF's bytes."
        },
        "file_id": {
          "type": "string",
          "description": "ChatGPT's identifier for the attached file."
        },
        "mime_type": {
          "description": "MIME type of the attached file, when ChatGPT provides one.",
          "type": "string"
        },
        "file_name": {
          "description": "Original filename of the attached file, when ChatGPT provides one.",
          "type": "string"
        }
      },
      "required": [
        "download_url",
        "file_id"
      ]
    },
    "pdf": {
      "description": "Base64-encoded PDF content — last resort only; prefer pdf_file for an attachment or pdf_url for a link",
      "type": "string"
    },
    "pdf_url": {
      "description": "HTTPS URL to fetch the PDF from",
      "type": "string",
      "format": "uri"
    },
    "upload_id": {
      "description": "An upload_id from request_upload, after PUTting the file to its upload_url. Use this only when your host has no other way to reference the attached file (no pdf_file/pdf_url equivalent).",
      "type": "string"
    },
    "upload_ids": {
      "description": "Batch of upload_ids from a single request_upload(count) call, each already PUT to its own upload_url — converts many statements in one call. Mutually exclusive with pdf, pdf_url, pdf_file, and upload_id. Admission only: the response reports per-file status immediately, never waiting for conversion — fetch results per document_id via get_statement.",
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "password": {
      "description": "Password for encrypted PDFs",
      "type": "string"
    },
    "output_format": {
      "default": "json",
      "description": "Output format",
      "type": "string",
      "enum": [
        "json",
        "csv",
        "xlsx",
        "qbo",
        "xero"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_statement

Fetch the full converted data for a previously processed document. Use this after convert_statement returns a "processing" status, or to re-fetch results. output_format "json" (default) returns the data inline, renderable in chat. The other formats (csv, xlsx, qbo, xero) return a time-limited download link instead: present it as a normal link. data_mode selects which projection of the data you get: omit it for each output_format's existing default behavior. "normalized" is the cleaned, interpreted view; "original" includes each transaction's raw column values exactly as printed on the source PDF (originalData); "enhanced" is a reformatted view of the original columns (csv/xlsx only for now). Fetch data_mode: "original" when you plan to submit results to evaluate_benchmark — pass its originalData through verbatim; an absent originalData scores that benchmark's raw-fidelity dimension 0 for this document. Every response includes a "summary" field: use it as the single source of truth for what happened. If the conversation is not in English, translate it faithfully into the conversation language; never add details it doesn't contain. Never echo raw status values (e.g. "completed") or field names.

Parameters5

document_id	string	required	Document ID (from convert_statement or list_statements)
output_format	string	optional	Output format
data_mode	string	optional	Omit for each output_format's existing default behavior (json: normalized; csv/xlsx: the export route's own default). "normalized": the cleaned, interpreted data. "original": includes each transaction's raw column values as printed on the source PDF (originalData) — fetch this before submitting to evaluate_benchmark. "enhanced": a reformatted view of the original columns; only available for output_format csv/xlsx today. qbo/xero always export normalized data — omit data_mode (or pass "normalized" explicitly) for those formats.
offset	integer	optional	output_format "json" only. Number of transactions to skip. Omit to start from the beginning.
limit	integer	optional	output_format "json" only. Max transactions to return (default 500, capped at 2000, or 500 with data_mode "original").

Raw schema

{
  "type": "object",
  "properties": {
    "document_id": {
      "type": "string",
      "description": "Document ID (from convert_statement or list_statements)"
    },
    "output_format": {
      "default": "json",
      "description": "Output format",
      "type": "string",
      "enum": [
        "json",
        "csv",
        "xlsx",
        "qbo",
        "xero"
      ]
    },
    "data_mode": {
      "description": "Omit for each output_format's existing default behavior (json: normalized; csv/xlsx: the export route's own default). \"normalized\": the cleaned, interpreted data. \"original\": includes each transaction's raw column values as printed on the source PDF (originalData) — fetch this before submitting to evaluate_benchmark. \"enhanced\": a reformatted view of the original columns; only available for output_format csv/xlsx today. qbo/xero always export normalized data — omit data_mode (or pass \"normalized\" explicitly) for those formats.",
      "type": "string",
      "enum": [
        "original",
        "enhanced",
        "normalized"
      ]
    },
    "offset": {
      "description": "output_format \"json\" only. Number of transactions to skip. Omit to start from the beginning.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "output_format \"json\" only. Max transactions to return (default 500, capped at 2000, or 500 with data_mode \"original\").",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "document_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

categorize_statement

Run AI transaction categorization on a previously processed document, then return its category mappings. Returns cached categories with no charge if this document was already categorized. Consumes credits (pooled per page, same rate as the categorize toggle on the website) the first time — free on every re-fetch after. Every response includes a "summary" field: use it as the single source of truth for what happened.

Parameters1

document_id

string

required

Document ID (from convert_statement or list_statements)

Raw schema

{
  "type": "object",
  "properties": {
    "document_id": {
      "type": "string",
      "description": "Document ID (from convert_statement or list_statements)"
    }
  },
  "required": [
    "document_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

list_statements

Browse your previously converted bank statements with pagination and optional status filter.

Parameters3

limit	integer	optional	Max results (1-100)
offset	integer	optional	Pagination offset
status	string	optional	Filter by status

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 20,
      "description": "Max results (1-100)",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "Filter by status",
      "type": "string",
      "enum": [
        "processing",
        "completed",
        "failed"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

dismiss_statement

Hide a failed, rejected, or cancelled document from future list_statements results. Use this only when the user asks to clear a terminal failed/rejected/cancelled conversion from their history. This is not a delete: it marks the document dismissed and leaves stored data/artifacts untouched.

Parameters1

document_id

string

required

Document ID from list_statements, convert_statement, or get_statement

Raw schema

{
  "type": "object",
  "properties": {
    "document_id": {
      "type": "string",
      "description": "Document ID from list_statements, convert_statement, or get_statement"
    }
  },
  "required": [
    "document_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

adjudicate_transfers

Decide whether ambiguous pairs from list_transfers are transfers. Pass "verdict" when the user has told you; leave it out to let the AI judge decide. Returns the updated list_transfers answer.

Parameters4

amountMin	number	optional	Same floor as list_transfers.
pairs	array	optional	Pairs as list_transfers returned them. Required with verdict; omit to judge every open pair.
verdict	string	optional	The user's verdict. Omit to let the judge decide.
scope	object	optional	Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. "accounts" is a list of account/product chips ({ kind: "account" \| "product", id }, the id of an account descriptor or product returned by a tool); "dateRange" bounds by transaction date (YYYY-MM-DD).

Raw schema

{
  "type": "object",
  "properties": {
    "amountMin": {
      "description": "Same floor as list_transfers.",
      "type": "number"
    },
    "pairs": {
      "description": "Pairs as list_transfers returned them. Required with verdict; omit to judge every open pair.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fromTransactionId": {
            "type": "string",
            "minLength": 1,
            "description": "fromTransactionId, as list_transfers returned it."
          },
          "toTransactionId": {
            "type": "string",
            "minLength": 1,
            "description": "toTransactionId, as list_transfers returned it."
          }
        },
        "required": [
          "fromTransactionId",
          "toTransactionId"
        ]
      }
    },
    "verdict": {
      "description": "The user's verdict. Omit to let the judge decide.",
      "type": "string",
      "enum": [
        "confirmed",
        "rejected"
      ]
    },
    "scope": {
      "description": "Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. \"accounts\" is a list of account/product chips ({ kind: \"account\" | \"product\", id }, the id of an account descriptor or product returned by a tool); \"dateRange\" bounds by transaction date (YYYY-MM-DD).",
      "type": "object",
      "properties": {
        "accounts": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "account",
                    "description": "This chip addresses a single account."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The account id: the `id` of an account descriptor returned by a tool, or of a statement tool `accounts[]` entry."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "product",
                    "description": "This chip addresses a product and expands to its child accounts."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The product id: the `id` of a product returned by a statement tool (`get_statement` / `convert_statement`, `products[].id`)."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Account/product id chips (kind + id) to scope to. Empty = all accounts."
        },
        "dateRange": {
          "description": "Bounds results to transactions within this date range. Omit for no date filter.",
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Start of the date range (inclusive), YYYY-MM-DD."
            },
            "to": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "End of the date range (inclusive), YYYY-MM-DD."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "required": [
        "accounts"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

get_credits

Your remaining Bankstatemently credits — the processing quota, NOT credit/debit transactions. Use for: how many credits do I have, remaining pages, plan limits, quota, how many pages can I upload. 1 credit = 1 page of bank statement processing. Also reports your plan's operational limits (max pages per upload, max upload size, daily spend cap) so you can size a multi-file batch correctly before starting it.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

rate_statement

Report how well a previously converted bank statement was parsed: submit a 1-5 rating, optionally with structured feedback at any rating. Your rating counts toward the average ratings shown on bankstatemently.com. Calling this again for the same document updates your existing rating without clearing feedback already submitted for it. Returns the stored rating state in the response — there is no separate tool to read your own rating back. Every response includes a "summary" field: use it as the single source of truth for what happened.

Parameters4

document_id	string	required	Document ID (from convert_statement or list_statements)
rating	integer	required	1-5 star rating for this conversion
feedback_categories	array	optional	Structured feedback categories.
feedback	string	optional	Free-text feedback.

Raw schema

{
  "type": "object",
  "properties": {
    "document_id": {
      "type": "string",
      "description": "Document ID (from convert_statement or list_statements)"
    },
    "rating": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "1-5 star rating for this conversion"
    },
    "feedback_categories": {
      "description": "Structured feedback categories.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "missing_transactions",
          "incorrect_amounts",
          "export_issue",
          "wrong_dates",
          "formatting_issue",
          "other"
        ]
      }
    },
    "feedback": {
      "description": "Free-text feedback.",
      "type": "string",
      "maxLength": 1000
    }
  },
  "required": [
    "document_id",
    "rating"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

evaluate_benchmark

Score parsed bank statement transactions against the Bankstatemently benchmark ground truth. Accepts a statement_id (e.g. "bsb-001") or content_hash, plus your parsed transactions. Returns extraction accuracy, integrity score, and an overall score. Only statements marked published: true in the catalog can be evaluated — held-out statements return an error. transactions[].originalData is optional but strongly recommended: fetch it via get_statement with data_mode: "original" and pass it through verbatim — an absent originalData scores that transaction's raw-fidelity (parsed) dimension 0; never fabricate a value. Free to use — no credits consumed. Read the benchmark://catalog resource first to see available statements and their published status.

Parameters4

statement_id	string	optional	Benchmark statement ID (e.g. "bsb-001"). Preferred over content_hash.
content_hash	string	optional	SHA-256 hex digest of the PDF. Use statement_id instead if you know it.
accounts	array	optional	Optional account roster for multi-account statements. Each transaction references one via accountId.
transactions	array	required	Parsed transactions (1-2000)

Raw schema

{
  "type": "object",
  "properties": {
    "statement_id": {
      "description": "Benchmark statement ID (e.g. \"bsb-001\"). Preferred over content_hash.",
      "type": "string"
    },
    "content_hash": {
      "description": "SHA-256 hex digest of the PDF. Use statement_id instead if you know it.",
      "type": "string"
    },
    "accounts": {
      "description": "Optional account roster for multi-account statements. Each transaction references one via accountId.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "description": "Submission-internal handle, referenced by transactions[].accountId."
          },
          "accountNumber": {
            "description": "Verbatim printed account number — never normalized by the submitter.",
            "type": "string"
          },
          "name": {
            "description": "Verbatim printed account label.",
            "type": "string"
          },
          "currency": {
            "description": "ISO 4217 currency code.",
            "type": "string"
          }
        },
        "required": [
          "id"
        ]
      }
    },
    "transactions": {
      "minItems": 1,
      "maxItems": 2000,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "ISO 8601 date (YYYY-MM-DD)"
          },
          "description": {
            "type": "string",
            "description": "Transaction description as printed on the statement."
          },
          "amount": {
            "type": "number",
            "description": "Transaction amount. Negative = debit, positive = credit (or use direction)."
          },
          "direction": {
            "description": "Explicit direction. If omitted, inferred from amount sign.",
            "type": "string",
            "enum": [
              "credit",
              "debit"
            ]
          },
          "balance": {
            "description": "Running balance after this transaction, if known.",
            "type": "number"
          },
          "currency": {
            "description": "ISO 4217 currency code for this transaction, if known.",
            "type": "string"
          },
          "originalData": {
            "description": "Raw column values as on the PDF. Omit if unavailable — never fabricate a value; an absence scores the parsed dimension's raw fields 0 rather than polluting the measurement.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "string"
            }
          },
          "accountId": {
            "description": "References accounts[].id — the account this transaction belongs to. Omit for single-account statements.",
            "type": "string"
          }
        },
        "required": [
          "date",
          "description",
          "amount"
        ]
      },
      "description": "Parsed transactions (1-2000)"
    }
  },
  "required": [
    "transactions"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

list_transactions

A transaction is a single line as printed on one account's statement — one side of any movement. Return a filtered list of transactions across your converted statements, capped at 50 rows. Scope defaults to all your completed statements; pass "scope" to narrow to specific accounts/products and/or a date range. Every response names the scope it actually evaluated (document count + covered date range) and each returned row carries its source document's content_hash so you can cite it. For "how many credits do I have" / processing quota / remaining pages, use get_credits instead — that is not a transaction.

Parameters5

filter	object	optional	Subset of transactions to operate on. All fields are optional and combined with AND logic.
limit	number	optional	Maximum rows to return. Default 20, max 50.
sort_by	string	optional	Sort the filtered set before applying limit. "amount" ranks by absolute magnitude (signed amounts are still returned). Omit for today's default (encounter order).
order	string	optional	Sort direction. Default "desc" (largest amount / most recent date first). Only meaningful with sort_by.
scope	object	optional	Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. "accounts" is a list of account/product chips ({ kind: "account" \| "product", id }, the id of an account descriptor or product returned by a tool); "dateRange" bounds by transaction date (YYYY-MM-DD).

Raw schema

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "object",
      "properties": {
        "dateStart": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive lower bound."
        },
        "dateEnd": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive upper bound."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 currency code. E.g. \"USD\", \"HKD\"."
        },
        "text": {
          "type": "string",
          "description": "Whole-row text search over raw transaction fields (case-insensitive)."
        },
        "direction": {
          "type": "string",
          "enum": [
            "credit",
            "debit"
          ],
          "description": "Semantic direction."
        },
        "category": {
          "type": "string",
          "enum": [
            "income",
            "transfers",
            "payroll",
            "rent_premises",
            "utilities_telecom",
            "software_subscriptions",
            "professional_services",
            "bank_fees_interest",
            "taxes_government",
            "travel_vehicle",
            "meals_entertainment",
            "supplies_equipment",
            "insurance_health",
            "loan_payments",
            "groceries_personal",
            "cash",
            "other"
          ],
          "description": "Category slug, e.g. \"meals_entertainment\", \"groceries_personal\"."
        },
        "merchant": {
          "type": "string",
          "description": "Substring match against description or counterparty (case-insensitive)."
        },
        "amountMin": {
          "type": "number",
          "description": "Inclusive minimum absolute amount."
        },
        "amountMax": {
          "type": "number",
          "description": "Inclusive maximum absolute amount."
        }
      },
      "additionalProperties": false,
      "description": "Subset of transactions to operate on. All fields are optional and combined with AND logic."
    },
    "limit": {
      "type": "number",
      "description": "Maximum rows to return. Default 20, max 50."
    },
    "sort_by": {
      "type": "string",
      "enum": [
        "amount",
        "date"
      ],
      "description": "Sort the filtered set before applying limit. \"amount\" ranks by absolute magnitude (signed amounts are still returned). Omit for today's default (encounter order)."
    },
    "order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Sort direction. Default \"desc\" (largest amount / most recent date first). Only meaningful with sort_by."
    },
    "scope": {
      "description": "Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. \"accounts\" is a list of account/product chips ({ kind: \"account\" | \"product\", id }, the id of an account descriptor or product returned by a tool); \"dateRange\" bounds by transaction date (YYYY-MM-DD).",
      "type": "object",
      "properties": {
        "accounts": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "account",
                    "description": "This chip addresses a single account."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The account id: the `id` of an account descriptor returned by a tool, or of a statement tool `accounts[]` entry."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "product",
                    "description": "This chip addresses a product and expands to its child accounts."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The product id: the `id` of a product returned by a statement tool (`get_statement` / `convert_statement`, `products[].id`)."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Account/product id chips (kind + id) to scope to. Empty = all accounts."
        },
        "dateRange": {
          "description": "Bounds results to transactions within this date range. Omit for no date filter.",
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Start of the date range (inclusive), YYYY-MM-DD."
            },
            "to": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "End of the date range (inclusive), YYYY-MM-DD."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "required": [
        "accounts"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

aggregate

Compute a single metric (sum/average/count/max/min) over a filtered set of transactions across your converted statements. Results are per-currency — never sum across currencies yourself. Scope defaults to all your completed statements; pass "scope" to narrow to specific accounts/products and/or a date range. For "how many credits do I have" / processing quota / remaining pages, use get_credits instead — that is not a transaction.

Parameters3

filter	object	optional	Subset of transactions to operate on. All fields are optional and combined with AND logic.
metric	string	required	Aggregation metric.
scope	object	optional	Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. "accounts" is a list of account/product chips ({ kind: "account" \| "product", id }, the id of an account descriptor or product returned by a tool); "dateRange" bounds by transaction date (YYYY-MM-DD).

Raw schema

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "object",
      "properties": {
        "dateStart": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive lower bound."
        },
        "dateEnd": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive upper bound."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 currency code. E.g. \"USD\", \"HKD\"."
        },
        "text": {
          "type": "string",
          "description": "Whole-row text search over raw transaction fields (case-insensitive)."
        },
        "direction": {
          "type": "string",
          "enum": [
            "credit",
            "debit"
          ],
          "description": "Semantic direction."
        },
        "category": {
          "type": "string",
          "enum": [
            "income",
            "transfers",
            "payroll",
            "rent_premises",
            "utilities_telecom",
            "software_subscriptions",
            "professional_services",
            "bank_fees_interest",
            "taxes_government",
            "travel_vehicle",
            "meals_entertainment",
            "supplies_equipment",
            "insurance_health",
            "loan_payments",
            "groceries_personal",
            "cash",
            "other"
          ],
          "description": "Category slug, e.g. \"meals_entertainment\", \"groceries_personal\"."
        },
        "merchant": {
          "type": "string",
          "description": "Substring match against description or counterparty (case-insensitive)."
        },
        "amountMin": {
          "type": "number",
          "description": "Inclusive minimum absolute amount."
        },
        "amountMax": {
          "type": "number",
          "description": "Inclusive maximum absolute amount."
        }
      },
      "additionalProperties": false,
      "description": "Subset of transactions to operate on. All fields are optional and combined with AND logic."
    },
    "metric": {
      "type": "string",
      "enum": [
        "sum",
        "average",
        "count",
        "max",
        "min"
      ],
      "description": "Aggregation metric."
    },
    "scope": {
      "description": "Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. \"accounts\" is a list of account/product chips ({ kind: \"account\" | \"product\", id }, the id of an account descriptor or product returned by a tool); \"dateRange\" bounds by transaction date (YYYY-MM-DD).",
      "type": "object",
      "properties": {
        "accounts": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "account",
                    "description": "This chip addresses a single account."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The account id: the `id` of an account descriptor returned by a tool, or of a statement tool `accounts[]` entry."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "product",
                    "description": "This chip addresses a product and expands to its child accounts."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The product id: the `id` of a product returned by a statement tool (`get_statement` / `convert_statement`, `products[].id`)."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Account/product id chips (kind + id) to scope to. Empty = all accounts."
        },
        "dateRange": {
          "description": "Bounds results to transactions within this date range. Omit for no date filter.",
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Start of the date range (inclusive), YYYY-MM-DD."
            },
            "to": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "End of the date range (inclusive), YYYY-MM-DD."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "required": [
        "accounts"
      ]
    }
  },
  "required": [
    "metric"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

group_by

Group transactions by a dimension (month/category/counterparty/account/currency) and apply a metric to each group. Results are per-currency. The "counterparty" dimension keys on the printed counterparty, else a printed account mask (••1234), else the description's name tokens, so a rail word or reference number never splits one payee; a line with no key groups under "unknown". Scope defaults to all your completed statements; pass "scope" to narrow to specific accounts/products and/or a date range.

Parameters4

filter	object	optional	Subset of transactions to operate on. All fields are optional and combined with AND logic.
dimension	string	required	Grouping dimension.
metric	string	required	Metric per group.
scope	object	optional	Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. "accounts" is a list of account/product chips ({ kind: "account" \| "product", id }, the id of an account descriptor or product returned by a tool); "dateRange" bounds by transaction date (YYYY-MM-DD).

Raw schema

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "object",
      "properties": {
        "dateStart": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive lower bound."
        },
        "dateEnd": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive upper bound."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 currency code. E.g. \"USD\", \"HKD\"."
        },
        "text": {
          "type": "string",
          "description": "Whole-row text search over raw transaction fields (case-insensitive)."
        },
        "direction": {
          "type": "string",
          "enum": [
            "credit",
            "debit"
          ],
          "description": "Semantic direction."
        },
        "category": {
          "type": "string",
          "enum": [
            "income",
            "transfers",
            "payroll",
            "rent_premises",
            "utilities_telecom",
            "software_subscriptions",
            "professional_services",
            "bank_fees_interest",
            "taxes_government",
            "travel_vehicle",
            "meals_entertainment",
            "supplies_equipment",
            "insurance_health",
            "loan_payments",
            "groceries_personal",
            "cash",
            "other"
          ],
          "description": "Category slug, e.g. \"meals_entertainment\", \"groceries_personal\"."
        },
        "merchant": {
          "type": "string",
          "description": "Substring match against description or counterparty (case-insensitive)."
        },
        "amountMin": {
          "type": "number",
          "description": "Inclusive minimum absolute amount."
        },
        "amountMax": {
          "type": "number",
          "description": "Inclusive maximum absolute amount."
        }
      },
      "additionalProperties": false,
      "description": "Subset of transactions to operate on. All fields are optional and combined with AND logic."
    },
    "dimension": {
      "type": "string",
      "enum": [
        "month",
        "category",
        "counterparty",
        "account",
        "currency"
      ],
      "description": "Grouping dimension."
    },
    "metric": {
      "type": "string",
      "enum": [
        "sum",
        "average",
        "count",
        "max",
        "min"
      ],
      "description": "Metric per group."
    },
    "scope": {
      "description": "Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. \"accounts\" is a list of account/product chips ({ kind: \"account\" | \"product\", id }, the id of an account descriptor or product returned by a tool); \"dateRange\" bounds by transaction date (YYYY-MM-DD).",
      "type": "object",
      "properties": {
        "accounts": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "account",
                    "description": "This chip addresses a single account."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The account id: the `id` of an account descriptor returned by a tool, or of a statement tool `accounts[]` entry."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "product",
                    "description": "This chip addresses a product and expands to its child accounts."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The product id: the `id` of a product returned by a statement tool (`get_statement` / `convert_statement`, `products[].id`)."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Account/product id chips (kind + id) to scope to. Empty = all accounts."
        },
        "dateRange": {
          "description": "Bounds results to transactions within this date range. Omit for no date filter.",
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Start of the date range (inclusive), YYYY-MM-DD."
            },
            "to": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "End of the date range (inclusive), YYYY-MM-DD."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "required": [
        "accounts"
      ]
    }
  },
  "required": [
    "dimension",
    "metric"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

top_n

Return the top N groups ranked by metric (descending), per-currency for monetary metrics. Scope defaults to all your completed statements; pass "scope" to narrow to specific accounts/products and/or a date range.

Parameters5

filter	object	optional	Subset of transactions to operate on. All fields are optional and combined with AND logic.
dimension	string	required	Grouping dimension.
metric	string	required	Metric to rank by.
n	number	required	Number of top groups to return.
scope	object	optional	Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. "accounts" is a list of account/product chips ({ kind: "account" \| "product", id }, the id of an account descriptor or product returned by a tool); "dateRange" bounds by transaction date (YYYY-MM-DD).

Raw schema

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "object",
      "properties": {
        "dateStart": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive lower bound."
        },
        "dateEnd": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive upper bound."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 currency code. E.g. \"USD\", \"HKD\"."
        },
        "text": {
          "type": "string",
          "description": "Whole-row text search over raw transaction fields (case-insensitive)."
        },
        "direction": {
          "type": "string",
          "enum": [
            "credit",
            "debit"
          ],
          "description": "Semantic direction."
        },
        "category": {
          "type": "string",
          "enum": [
            "income",
            "transfers",
            "payroll",
            "rent_premises",
            "utilities_telecom",
            "software_subscriptions",
            "professional_services",
            "bank_fees_interest",
            "taxes_government",
            "travel_vehicle",
            "meals_entertainment",
            "supplies_equipment",
            "insurance_health",
            "loan_payments",
            "groceries_personal",
            "cash",
            "other"
          ],
          "description": "Category slug, e.g. \"meals_entertainment\", \"groceries_personal\"."
        },
        "merchant": {
          "type": "string",
          "description": "Substring match against description or counterparty (case-insensitive)."
        },
        "amountMin": {
          "type": "number",
          "description": "Inclusive minimum absolute amount."
        },
        "amountMax": {
          "type": "number",
          "description": "Inclusive maximum absolute amount."
        }
      },
      "additionalProperties": false,
      "description": "Subset of transactions to operate on. All fields are optional and combined with AND logic."
    },
    "dimension": {
      "type": "string",
      "enum": [
        "month",
        "category",
        "counterparty",
        "account",
        "currency"
      ],
      "description": "Grouping dimension."
    },
    "metric": {
      "type": "string",
      "enum": [
        "sum",
        "average",
        "count",
        "max",
        "min"
      ],
      "description": "Metric to rank by."
    },
    "n": {
      "type": "number",
      "description": "Number of top groups to return."
    },
    "scope": {
      "description": "Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. \"accounts\" is a list of account/product chips ({ kind: \"account\" | \"product\", id }, the id of an account descriptor or product returned by a tool); \"dateRange\" bounds by transaction date (YYYY-MM-DD).",
      "type": "object",
      "properties": {
        "accounts": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "account",
                    "description": "This chip addresses a single account."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The account id: the `id` of an account descriptor returned by a tool, or of a statement tool `accounts[]` entry."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "product",
                    "description": "This chip addresses a product and expands to its child accounts."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The product id: the `id` of a product returned by a statement tool (`get_statement` / `convert_statement`, `products[].id`)."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Account/product id chips (kind + id) to scope to. Empty = all accounts."
        },
        "dateRange": {
          "description": "Bounds results to transactions within this date range. Omit for no date filter.",
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Start of the date range (inclusive), YYYY-MM-DD."
            },
            "to": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "End of the date range (inclusive), YYYY-MM-DD."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "required": [
        "accounts"
      ]
    }
  },
  "required": [
    "dimension",
    "metric",
    "n"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

compare

Side-by-side metric comparison for two filtered groups of transactions (e.g. one category vs another, one month vs another). Scope defaults to all your completed statements; pass "scope" to narrow to specific accounts/products and/or a date range.

Parameters4

filterA	object	required	Subset of transactions to operate on. All fields are optional and combined with AND logic.
filterB	object	required	Subset of transactions to operate on. All fields are optional and combined with AND logic.
metric	string	required	Metric for both groups.
scope	object	optional	Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. "accounts" is a list of account/product chips ({ kind: "account" \| "product", id }, the id of an account descriptor or product returned by a tool); "dateRange" bounds by transaction date (YYYY-MM-DD).

Raw schema

{
  "type": "object",
  "properties": {
    "filterA": {
      "type": "object",
      "properties": {
        "dateStart": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive lower bound."
        },
        "dateEnd": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive upper bound."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 currency code. E.g. \"USD\", \"HKD\"."
        },
        "text": {
          "type": "string",
          "description": "Whole-row text search over raw transaction fields (case-insensitive)."
        },
        "direction": {
          "type": "string",
          "enum": [
            "credit",
            "debit"
          ],
          "description": "Semantic direction."
        },
        "category": {
          "type": "string",
          "enum": [
            "income",
            "transfers",
            "payroll",
            "rent_premises",
            "utilities_telecom",
            "software_subscriptions",
            "professional_services",
            "bank_fees_interest",
            "taxes_government",
            "travel_vehicle",
            "meals_entertainment",
            "supplies_equipment",
            "insurance_health",
            "loan_payments",
            "groceries_personal",
            "cash",
            "other"
          ],
          "description": "Category slug, e.g. \"meals_entertainment\", \"groceries_personal\"."
        },
        "merchant": {
          "type": "string",
          "description": "Substring match against description or counterparty (case-insensitive)."
        },
        "amountMin": {
          "type": "number",
          "description": "Inclusive minimum absolute amount."
        },
        "amountMax": {
          "type": "number",
          "description": "Inclusive maximum absolute amount."
        }
      },
      "additionalProperties": false,
      "description": "Subset of transactions to operate on. All fields are optional and combined with AND logic."
    },
    "filterB": {
      "type": "object",
      "properties": {
        "dateStart": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive lower bound."
        },
        "dateEnd": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive upper bound."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 currency code. E.g. \"USD\", \"HKD\"."
        },
        "text": {
          "type": "string",
          "description": "Whole-row text search over raw transaction fields (case-insensitive)."
        },
        "direction": {
          "type": "string",
          "enum": [
            "credit",
            "debit"
          ],
          "description": "Semantic direction."
        },
        "category": {
          "type": "string",
          "enum": [
            "income",
            "transfers",
            "payroll",
            "rent_premises",
            "utilities_telecom",
            "software_subscriptions",
            "professional_services",
            "bank_fees_interest",
            "taxes_government",
            "travel_vehicle",
            "meals_entertainment",
            "supplies_equipment",
            "insurance_health",
            "loan_payments",
            "groceries_personal",
            "cash",
            "other"
          ],
          "description": "Category slug, e.g. \"meals_entertainment\", \"groceries_personal\"."
        },
        "merchant": {
          "type": "string",
          "description": "Substring match against description or counterparty (case-insensitive)."
        },
        "amountMin": {
          "type": "number",
          "description": "Inclusive minimum absolute amount."
        },
        "amountMax": {
          "type": "number",
          "description": "Inclusive maximum absolute amount."
        }
      },
      "additionalProperties": false,
      "description": "Subset of transactions to operate on. All fields are optional and combined with AND logic."
    },
    "metric": {
      "type": "string",
      "enum": [
        "sum",
        "average",
        "count",
        "max",
        "min"
      ],
      "description": "Metric for both groups."
    },
    "scope": {
      "description": "Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. \"accounts\" is a list of account/product chips ({ kind: \"account\" | \"product\", id }, the id of an account descriptor or product returned by a tool); \"dateRange\" bounds by transaction date (YYYY-MM-DD).",
      "type": "object",
      "properties": {
        "accounts": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "account",
                    "description": "This chip addresses a single account."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The account id: the `id` of an account descriptor returned by a tool, or of a statement tool `accounts[]` entry."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "product",
                    "description": "This chip addresses a product and expands to its child accounts."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The product id: the `id` of a product returned by a statement tool (`get_statement` / `convert_statement`, `products[].id`)."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Account/product id chips (kind + id) to scope to. Empty = all accounts."
        },
        "dateRange": {
          "description": "Bounds results to transactions within this date range. Omit for no date filter.",
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Start of the date range (inclusive), YYYY-MM-DD."
            },
            "to": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "End of the date range (inclusive), YYYY-MM-DD."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "required": [
        "accounts"
      ]
    }
  },
  "required": [
    "filterA",
    "filterB",
    "metric"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

time_series

Compute a time series by grouping transactions into week or month buckets and applying a metric — useful for trends. Scope defaults to all your completed statements; pass "scope" to narrow to specific accounts/products and/or a date range.

Parameters4

filter	object	optional	Subset of transactions to operate on. All fields are optional and combined with AND logic.
bucket	string	required	Bucket size.
metric	string	required	Metric per bucket.
scope	object	optional	Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. "accounts" is a list of account/product chips ({ kind: "account" \| "product", id }, the id of an account descriptor or product returned by a tool); "dateRange" bounds by transaction date (YYYY-MM-DD).

Raw schema

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "object",
      "properties": {
        "dateStart": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive lower bound."
        },
        "dateEnd": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive upper bound."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 currency code. E.g. \"USD\", \"HKD\"."
        },
        "text": {
          "type": "string",
          "description": "Whole-row text search over raw transaction fields (case-insensitive)."
        },
        "direction": {
          "type": "string",
          "enum": [
            "credit",
            "debit"
          ],
          "description": "Semantic direction."
        },
        "category": {
          "type": "string",
          "enum": [
            "income",
            "transfers",
            "payroll",
            "rent_premises",
            "utilities_telecom",
            "software_subscriptions",
            "professional_services",
            "bank_fees_interest",
            "taxes_government",
            "travel_vehicle",
            "meals_entertainment",
            "supplies_equipment",
            "insurance_health",
            "loan_payments",
            "groceries_personal",
            "cash",
            "other"
          ],
          "description": "Category slug, e.g. \"meals_entertainment\", \"groceries_personal\"."
        },
        "merchant": {
          "type": "string",
          "description": "Substring match against description or counterparty (case-insensitive)."
        },
        "amountMin": {
          "type": "number",
          "description": "Inclusive minimum absolute amount."
        },
        "amountMax": {
          "type": "number",
          "description": "Inclusive maximum absolute amount."
        }
      },
      "additionalProperties": false,
      "description": "Subset of transactions to operate on. All fields are optional and combined with AND logic."
    },
    "bucket": {
      "type": "string",
      "enum": [
        "week",
        "month"
      ],
      "description": "Bucket size."
    },
    "metric": {
      "type": "string",
      "enum": [
        "sum",
        "average",
        "count",
        "max",
        "min"
      ],
      "description": "Metric per bucket."
    },
    "scope": {
      "description": "Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. \"accounts\" is a list of account/product chips ({ kind: \"account\" | \"product\", id }, the id of an account descriptor or product returned by a tool); \"dateRange\" bounds by transaction date (YYYY-MM-DD).",
      "type": "object",
      "properties": {
        "accounts": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "account",
                    "description": "This chip addresses a single account."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The account id: the `id` of an account descriptor returned by a tool, or of a statement tool `accounts[]` entry."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "product",
                    "description": "This chip addresses a product and expands to its child accounts."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The product id: the `id` of a product returned by a statement tool (`get_statement` / `convert_statement`, `products[].id`)."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Account/product id chips (kind + id) to scope to. Empty = all accounts."
        },
        "dateRange": {
          "description": "Bounds results to transactions within this date range. Omit for no date filter.",
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Start of the date range (inclusive), YYYY-MM-DD."
            },
            "to": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "End of the date range (inclusive), YYYY-MM-DD."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "required": [
        "accounts"
      ]
    }
  },
  "required": [
    "bucket",
    "metric"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

list_transfers

Match transfers between your own accounts. A transfer is TWO transactions — a debit leaving one of your accounts and a credit arriving in another — matched as two sides of the same movement (amount and date aligned); account-level successions (an account closing into a successor) are matched too. A payment to an outside party is not a transfer here: only movements with both sides visible in your statements are matched. THE way to answer any "was money moved between my accounts" / "did I transfer X" question — never try to answer a money-moved-between-accounts question with list_transactions + arithmetic; always call this tool instead. Ties come back as "ambiguous" until decided; call adjudicate_transfers to decide them. Scope defaults to all your completed statements; pass "scope" to narrow to specific accounts/products and/or a date range. Every response reports the match window (in days) it used, even when no transfers are found — a lack of matches is never silent about how hard it looked. To find large movements with NO matching counterpart in your other accounts — e.g. "trace transfers over $10,000; which ones leave without a known destination?" — pass "amountMin": reconciled pairs and successions are filtered to that floor, and the response gains an "unmatched" bucket of large movements (debits leaving, or unexplained credits arriving) with no matching pair, candidate, or succession. Omit amountMin for the ordinary reconciled-pairs answer.

Parameters2

amountMin	number	optional	Inclusive minimum absolute amount. When present, transfers/accountSuccessions are floored to this amount and the response gains an "unmatched" bucket of large movements with no matching counterpart. Omit for the ordinary reconciled-pairs answer.
scope	object	optional	Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. "accounts" is a list of account/product chips ({ kind: "account" \| "product", id }, the id of an account descriptor or product returned by a tool); "dateRange" bounds by transaction date (YYYY-MM-DD).

Raw schema

{
  "type": "object",
  "properties": {
    "amountMin": {
      "type": "number",
      "description": "Inclusive minimum absolute amount. When present, transfers/accountSuccessions are floored to this amount and the response gains an \"unmatched\" bucket of large movements with no matching counterpart. Omit for the ordinary reconciled-pairs answer."
    },
    "scope": {
      "description": "Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. \"accounts\" is a list of account/product chips ({ kind: \"account\" | \"product\", id }, the id of an account descriptor or product returned by a tool); \"dateRange\" bounds by transaction date (YYYY-MM-DD).",
      "type": "object",
      "properties": {
        "accounts": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "account",
                    "description": "This chip addresses a single account."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The account id: the `id` of an account descriptor returned by a tool, or of a statement tool `accounts[]` entry."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "product",
                    "description": "This chip addresses a product and expands to its child accounts."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The product id: the `id` of a product returned by a statement tool (`get_statement` / `convert_statement`, `products[].id`)."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Account/product id chips (kind + id) to scope to. Empty = all accounts."
        },
        "dateRange": {
          "description": "Bounds results to transactions within this date range. Omit for no date filter.",
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Start of the date range (inclusive), YYYY-MM-DD."
            },
            "to": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "End of the date range (inclusive), YYYY-MM-DD."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "required": [
        "accounts"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

list_outflows

Every debit that left your accounts — in no confirmed transfer between your own accounts, and not a fee — each in ONE destination whose kind is also its next step: "own-account" (a printed account mask that names one of your accounts and no matched credit was found: ask for that account's statement), "account" (a printed account mask for an account outside your statements: request that account's statements; an in-kind move such as securities, crypto or escrow starts as a wire to that account and becomes visible only once the receiving statement is uploaded), "cash" (cash out: where it went cannot be followed, so the cumulative amount is the finding), "name" (a named party: review whether it was household spending) and "unknown" (nowhere the line says; kept visible, one entry per line, never merged). A destination carries the cumulative amount sent, per currency, never a balance. "mayBeOwnAccount" lists debits in an open candidate pair ("may be a move between your own accounts") apart, in no total. THE way to answer "did money disappear from my accounts, and where do I look next" — never answer it by summing list_transactions rows. Pass "dateRange" ({ from, to }, inclusive, YYYY-MM-DD) to report only debits in that range, for example from a separation date: transfers are matched over the whole scope first, so a transfer whose credit lies outside the range is still a transfer, never an outflow. Scope defaults to all your completed statements; pass "scope" to narrow to specific accounts/products and/or a date range (a scope date range also narrows what is matched — prefer "dateRange").

Parameters2

dateRange	object	optional	Report only debits dated in this inclusive range. Omit to report every date.
scope	object	optional	Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. "accounts" is a list of account/product chips ({ kind: "account" \| "product", id }, the id of an account descriptor or product returned by a tool); "dateRange" bounds by transaction date (YYYY-MM-DD).

Raw schema

{
  "type": "object",
  "properties": {
    "dateRange": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive start of the range."
        },
        "to": {
          "type": "string",
          "description": "ISO date (YYYY-MM-DD). Inclusive end of the range."
        }
      },
      "required": [
        "from",
        "to"
      ],
      "additionalProperties": false,
      "description": "Report only debits dated in this inclusive range. Omit to report every date."
    },
    "scope": {
      "description": "Optional structural scope (WHO × WHEN). Omit to search across all your completed statements. \"accounts\" is a list of account/product chips ({ kind: \"account\" | \"product\", id }, the id of an account descriptor or product returned by a tool); \"dateRange\" bounds by transaction date (YYYY-MM-DD).",
      "type": "object",
      "properties": {
        "accounts": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "account",
                    "description": "This chip addresses a single account."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The account id: the `id` of an account descriptor returned by a tool, or of a statement tool `accounts[]` entry."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "kind": {
                    "type": "string",
                    "const": "product",
                    "description": "This chip addresses a product and expands to its child accounts."
                  },
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
                    "description": "The product id: the `id` of a product returned by a statement tool (`get_statement` / `convert_statement`, `products[].id`)."
                  }
                },
                "required": [
                  "kind",
                  "id"
                ],
                "additionalProperties": false
              }
            ]
          },
          "description": "Account/product id chips (kind + id) to scope to. Empty = all accounts."
        },
        "dateRange": {
          "description": "Bounds results to transactions within this date range. Omit for no date filter.",
          "type": "object",
          "properties": {
            "from": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "Start of the date range (inclusive), YYYY-MM-DD."
            },
            "to": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
              "description": "End of the date range (inclusive), YYYY-MM-DD."
            }
          },
          "required": [
            "from",
            "to"
          ]
        }
      },
      "required": [
        "accounts"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

README.md4 KBView on GitHub

bankstatemently/plugins

Marketplace plugins for Bankstatemently — convert bank statements.

Install via Claude Code marketplace

bash

/plugin marketplace add bankstatemently/plugins
/plugin install bankstatemently@bankstatemently

After installing, enable the plugin. The first tool call opens your browser to sign in; the plugin asks for no settings.

For a headless setup (CI, scripts), skip the plugin and add the server directly with an API key — see below. Get a key at bankstatemently.com/developer.

Plugins

bankstatemently — MCP server for converting bank statements. Convert PDFs, list statements, check credits, run benchmark evaluations.

Claude Code direct install (no plugin)

Add the hosted MCP server directly and sign in with your browser:

bash

claude mcp add --transport http bankstatemently https://api.bankstatemently.com/mcp

For a headless setup, pass an API key in the X-API-Key header instead (the server rejects Authorization: Bearer):

bash

claude mcp add --transport http bankstatemently https://api.bankstatemently.com/mcp \
  --header "X-API-Key: <your-bsk_live_key>"

Codex

Codex has native OAuth support. This one command detects our server's discovery metadata and opens your browser to sign in — no key is ever stored:

bash

codex mcp add bankstatemently --url https://api.bankstatemently.com/mcp

For headless or CI setups where a browser sign-in isn't possible, use an API key via the mcp-remote bridge instead. Export the key in the shell that launches Codex, before it starts:

bash

export BANKSTATEMENTLY_API_KEY=bsk_live_...

codex mcp add bankstatemently -- npx -y mcp-remote@latest https://api.bankstatemently.com/mcp --header "X-API-Key: ${BANKSTATEMENTLY_API_KEY}"

Codex doesn't yet surface plugin-declared MCP servers into sessions, so the plugin install above (and its bundled skill) isn't available in Codex today — use the commands above instead.

Credential managers & sandboxed clients: never fetch a secret from Keychain, 1Password, or another credential manager inside the MCP server command itself — Codex runs that command sandboxed at tool discovery, so a credential-manager lookup dies silently and the server's tools never appear. Export the key in the shell that launches Codex instead. Also note that mcp-remote logs its resolved header values to stderr, so a wrapper-resolved key can end up in your client logs.

Run over stdio

For stdio-only clients (Claude Desktop's config file, Cursor, headless setups) or a directory scanner that launches the server locally, clone the public repo and run the self-contained mcp-stdio server directly — no Docker, no bridge process:

bash

git clone https://github.com/bankstatemently/plugins.git
cd plugins/mcp-stdio
npm install --omit=dev
BANKSTATEMENTLY_API_KEY=bsk_live_... node dist/stdio.js

BANKSTATEMENTLY_API_KEY is optional at startup: initialize/tools/list answer with no network call and no key either way, so an uncredentialed directory probe still sees the full tool list. A tools/call with no key returns the same auth-required result the hosted server returns. Export the key in the shell or runtime environment that launches the process — never resolve it inside the MCP command (a credential-manager lookup inside a sandboxed client's command dies silently, same caveat as the Codex section above).

Install

Tools (18)

request_uploadconvert_statementget_statementcategorize_statementlist_statementsdismiss_statementadjudicate_transfersget_credits

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.bankstatemently.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "bankstatemently-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.bankstatemently.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Bankstatemently MCP Server (io.github.bankstatemently/bankstatemently-mcp)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

request_upload

convert_statement

get_statement

categorize_statement

list_statements

dismiss_statement

adjudicate_transfers

get_credits

rate_statement

evaluate_benchmark

list_transactions

aggregate

group_by

top_n

compare

time_series

list_transfers

list_outflows

bankstatemently/plugins

Install via Claude Code marketplace

Plugins

Claude Code direct install (no plugin)

Codex

Run over stdio

Install

Remote endpoint

Related servers