GnuCash MCP server

gnucash-mcp

<!-- mcp-name: io.github.tillawy/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:

idempotent writes.

• gnucash_storage: a piecash wrapper, configured per book, with read helpers and

• 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.

datesource 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 datesource 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 GNUCASHMCPCONFIG 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 claudedesktopconfig.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:

Shortened. The full README is on GitHub.