GnuCash

gnucash-mcp

An MCP server that lets Claude read your GnuCash book and import bank statements into it. Upload a statement CSV from any bank, and Claude works out its layout, proposes a category for each row, and shows a preview. It flags duplicates before writing anything.

It has two parts:

• gnucash_storage: a piecash wrapper, configured per book, with read helpers and idempotent writes.
• gnucash_mcp: the MCP server that exposes the tools and prompts over stdio.

Requirements: a SQLite book

GnuCash saves books as XML by default, usually gzip-compressed. piecash, which this project is built on, can't read XML. It only reads GnuCash's SQL formats, and this server opens SQLite files. To convert your book:

1. Open it in GnuCash.
2. Choose File > Save As.
3. Set Data Format to sqlite3, pick a file name, and save.
4. Point book_path in your book TOML at the new file.

Keep using the SQLite file in GnuCash from then on. The XML file won't see the imported transactions. If book_path points at an XML book, every tool fails with a message explaining this conversion.

You also need uv and Python 3.13 or newer. uv installs Python for you if needed.

Configure a book

Create a TOML file for your book, for example ~/gnucash/personal.toml:

book_path = "personal.gnucash"   # relative to this TOML file, or an absolute path

bank_account = "Assets:Current Assets:Checking Account" # default bank side for imports open_if_lock = false # open for writing even while GnuCash has the file open do_backup = true # piecash writes a timestamped backup before writing

Optional: "posting" (booking date) or "transaction" (when the purchase happened).

date_source = "posting"

Optional hints about your bank's statement format, added to the import prompts.

statement_notes = ''' Details holds the merchant and a card reference "REF <12 digits>" (use it as external_id). The card date inside Details is YY/MM/DD. '''

Only book_path is required.

statement_notes is the place for your bank's quirks: where a reference ID hides, which of two date columns to use, or what an odd column means. Claude reads the notes during the column-mapping step, but still shows you the mapping to confirm. That way the server stays bank-agnostic, and each user's bank knowledge lives in their own config.

date_source picks which date becomes the transaction date when a statement has two: the bank's posting (booking) date, or the transaction date when you actually paid. Card purchases often post a day or two later, and the card date is often only inside the description. If date_source is unset, Claude asks during import whenever a statement has both. Setting it is recommended. For rows without a reference ID, the date is part of duplicate detection, so switching between the two dates across imports could let the same row in twice.

Install

The server runs with uvx, so there's nothing to install globally. Point GNUCASH_MCP_CONFIG at your book TOML, using an absolute path.

Claude Code:

claude mcp add gnucash -e GNUCASH_MCP_CONFIG=/absolute/path/to/personal.toml -- uvx gnucash-mcp

Claude Desktop: add this to claude_desktop_config.json (on macOS it's in ~/Library/Application Support/Claude/) and restart Claude Desktop:

{

"mcpServers": { "gnucash": { "command": "uvx", "args": ["gnucash-mcp"], "env": {"GNUCASH_MCP_CONFIG": "/absolute/path/to/personal.toml"} } } }

If Claude Desktop can't find uvx, replace "uvx" with its full path (which uvx).

Tools and prompts

Tools:

• list_accounts
• get_account(fullname)
• list_transactions(fullname, start_date, end_date, limit)
• create_account(fullname, account_type, currency=None, description="", placeholder=False): the parent must exist; the currency defaults to the parent's
• find_transactions(search, limit=5): find transactions in any account whose description, notes or number contain the word, newest first.
• copy_transaction(guid, post_date, external_id=None, notes=None): add a copy of an existing transaction with all its splits (also more than two); only the date, number and notes are new. Used by the clone options for entries add_transaction can't write.
• add_transaction(post_date, description, counter_account, amount, account=None, external_id=None, notes=None, force=False, quantity=None)
• update_transaction(guid, post_date=None, description=None, external_id=None, notes=None, counter_account=None, amount=None, account=None, quantity=None): change an existing transaction; fields left out stay as they are, and an empty external_id or notes clears it. Get the guid from list_transactions. Changing amount, quantity or counter_account needs a two-split transaction and moves both splits, so it stays balanced; account (default: the config's bank_account) says which side amount refers to. When only amount changes on a transaction with a commodity counter account, the units stay and the price changes. To change the amount of a copy, call this on the guid copy_transaction returns.
• delete_transaction(guid): permanently delete a transaction and its splits, and return what was deleted.
• reconcile_transactions(guids | start_date/end_date, state="y", account, dry_run=True): set the reconcile state (y reconciled, c cleared, n not reconciled) of an account's splits, chosen by GUID or by post date range (inclusive). Only the split on account changes. The dry run reports how many splits would change and their date range. The write is saved in one go and does not need GnuCash's reconcile window.
• import_transactions(rows, dry_run=True): batch import. Each row gets a status of new, added or duplicate, and duplicates include the existing transactions they match.

If account is omitted, it defaults to the config's bank_account. Read tools and dry runs open the book read-only. Writes open it for writing. A batch import opens it once, so it creates one backup file.

Prompt:

• import_bank_statement: imports a bank CSV with a preview table and one batch write (in Claude Code, run /mcp__gnucash__import_bank_statement).
• review_bank_statement: imports a bank CSV one row at a time, waiting for your decision on each row (in Claude Code, run /mcp__gnucash__review_bank_statement).
• clone_transaction: asks you for a search word, finds the newest similar entry, and adds a new one with the same accounts and description after you confirm the date and amount (in Claude Code, run /mcp__gnucash__clone_transaction).

Buying a commodity (gold, stocks)

When the counter account holds a non-currency commodity, such as gold coins or shares, pass quantity: the units bought or sold, as a positive number. amount stays the value on the bank account in the bank's currency, and the price per unit is amount / quantity. The transaction keeps the bank account's currency; the bank split gets -amount and the counter split gets the value -amount and the quantity quantity (negative when amount is positive, a sale):

add_transaction(

post_date=date(2026, 9, 29), description="Buy 5 from Anis", counter_account="Assets:Gold English Coins 21 carat", # commodity XGL21-8 amount=Decimal("-3330"), # JOD out of the bank quantity=Decimal("5"), # 666 JOD per coin account="Assets:Bank Accounts:ArabBank Jordan", # commodity JOD )

quantity is required for such a counter account and rejected for one in the bank account's currency. It must be positive and no finer than the commodity's fraction. import_transactions rows take the same quantity field. Converting between two currencies is still not supported.

Importing a bank statement

1. Upload the CSV and run the import_bank_statement prompt.
2. Claude works out the CSV layout from its header and first rows, for any bank: the delimiter, the date column and format, the description column, and the amounts. It handles both one signed amount column and separate money-out and money-in columns, and either decimal separator (1,234.56 or 1.234,56). It shows you the mapping with one parsed row, and waits for you to confirm before parsing everything. Money out becomes a negative amount and money in a positive one. Each row gets a short, readable description (e.g. Zalatimo Sweets), and the bank's original text is kept verbatim in the transaction's notes. Claude checks whether the file lists the newest row first, and if so reads it from the bottom up, so rows are written oldest first in the bank's own order (same-day rows are not re-sorted). If you'd rather keep the bank text as the description, say so when confirming the mapping. Then Claude picks a category account for each row.
3. Claude calls import_transactions(rows, dry_run=True) and shows a preview with each row marked new or duplicate.
4. After you confirm, Claude calls import_transactions(rows, dry_run=False). The new rows are written in one go, and duplicates are left out.
5. For each duplicate, Claude asks whether to force it or skip it. Forcing calls add_transaction(..., force=True). This covers, for example, a genuine second identical purchase on the same day.

Each transaction is recorded in the bank account's own currency, so a EUR account in a USD book gets EUR transactions. The category account must use the same currency, because currency conversion isn't supported. If the category you want is missing, Claude offers to create it with create_account and does so once you confirm.

Nothing is written if any row has an unknown account, mixes currencies, or has an amount with more decimals than the bank account's currency allows.

Reviewing row by row

Run review_bank_statement instead. After the same currency, parsing and category steps, Claude shows one row at a time (Row i/N) with its Num (the bank reference stored as the transaction number), proposed category and whether it is new or a duplicate. For each row you choose one of:

• Accept: write the row now, with import_transactions([row], dry_run=False).
• Change: edit the category, description or amount, then review the row again.
• Skip: write nothing.
• Force: for duplicates only; write it anyway with add_transaction(..., force=True).
• Accept all remaining: write the remaining new rows in one batch. Duplicates are still reviewed one at a time.
• Stop: end the review and get a summary.

Rows you approve are written immediately. If you stop halfway, they stay in the book, and a re-run shows them as duplicates. Each approval is a separate write, so with do_backup = true every approved row creates a backup file. Set do_backup = false in the book TOML if you don't want that.

Idempotent writes

from decimal import Decimal

from datetime import date from pathlib import Path from gnucash_storage import ( NewTransaction, add_transaction, load_config, open_configured_book, )

config = load_config(Path("books/development-book.toml")) with open_configured_book(config, readonly=False) as book: added = add_transaction( book, NewTransaction( post_date=date(2025, 11, 28), description="TEST BISTRO REST.", account="Assets:Current Assets:Savings Account", counter_account="Expenses:Dining", amount=Decimal("-36.00"), # money out of the bank account ), force=False, # set force=True to bypass duplicate checking )

A row can carry an optional external_id: a unique reference from the bank, such as a card retrieval reference number (REF 606006000101), an OFX FITID,