gnucash-mcp

gnucash-mcp

Free, open-source accounting software that works with the LLM.

Talk to your GnuCash books through Claude (or any AI assistantthat supports MCP). Ask "how am I doing this month," dictateyour transactions out loud, hand over the books for the AI tokeep up while you focus on running your life or your business.

Your data stays on your machine. Your audit log stays on yourmachine. Nothing is uploaded anywhere — the AI reads and writesyour local GnuCash file, and that's it.

Three real, populated sample books ship in this repo so youcan try it before you commit anything. They're realistic — fullyears of activity, mixed currencies, customers, invoices,budgets, the works. Walk through one in five minutes; if itclicks, point the server at your own book and you're done.

The samples are frozen snapshots, not living books — expect thedashboard to flag stale prices and pending scheduled transactionsthat have accumulated since their last regeneration. That'srealistic too (it's what a book looks like after a vacation). Torebuild them fresh through today, run the deterministic generatorsin scripts/synthetic_book/ (phase scripts, in order).

What does it look like?

This is what your AI assistant sees when it opens one of thesample books — a complete financial dashboard in a single call:

Book: samples/alex-chen-morales.gnucash
Currency: USD
Data range: 2025-01-01 to 2026-05-31
Last entry: 2026-05-31 (future-dated, 31 days ahead)
Warnings:
  ⚠ Past due invoice: Berlin Digital GmbH 58 days past 30-day default, EUR 4,200 (no term set)
  ⚠ Stale price: GBP last updated 150 days ago
Accounts: 108 total
Assets: 12 accounts, USD 602680.49
  Condo: USD 473250.00
  VTSAX: 230.7620 VTSAX @ 170.99 (USD 39457.99)
  Vehicle: USD 27845.00
  401k: USD 13404.62
  Checking Account: USD 12393.11
  ...
Liabilities: 4 accounts, USD 418457.79
  Credit cards (2): USD 38044.26
  Loans (2): USD 380413.53
  Top 3: Mortgage USD 372199.55, Chase Sapphire USD 22383.23, Business Amex USD 15661.03
Receivables: 3 accounts, USD 10246.46
  Accounts Receivable EUR: USD 4908.96
  Accounts Receivable: USD 3500.00
  Accounts Receivable CAD: USD 1837.50
Reconciliation:
  Checking Account: 174 splits unreconciled (4 months behind, oldest: 2025-12-30) ⚠
  7 accounts never reconciled ⚠
Net worth trajectory:
  12mo ago: USD 187,925
   6mo ago: USD 180,614
   3mo ago: USD 191,350
   1mo ago: USD 185,444
       now: USD 184,223
Monthly net (last 6 months):
  Apr 2026 (MTD): -9,056
  Mar 2026: +3,092
  Feb 2026: +5,202
  Jan 2026: +1,086
  Dec 2025: +4,853
  Nov 2025: -1,494
Runway: 121 days (USD 84,579 liquid / USD 694/day burn)
Budget (2026 Annual Budget): 41% used / 33% elapsed (+8% over pace)
Transactions: 2473
Scheduled: 13 recurring, none due in next 7 days
Business: 4 customers, 2 vendors, 1 employee

That's not a screenshot — that's the AI's actual orientationview. Net worth trajectory, runway, budget pacing, who owes youmoney, what's overdue, what hasn't been reconciled. One call,and your assistant has the full picture before you've evenfinished saying hello.

Who is this for?

• Personal finance people who keep their books in GnuCashand want to dictate transactions, ask their assistant wherethe money's going, get reconciliation help, plan budgets.
• Small business owners who run their books in GnuCash andwant to issue invoices, track receivables, see vendorspending, manage cash flow without leaving the conversation.
• People who care that their data stays local. No cloudsync. No SaaS. Your .gnucash file is the system of record;this just gives your AI a way to read and write it the wayGnuCash itself does.

You don't need to be a developer. You need:

• A computer (Mac, Windows, or Linux)
• GnuCash itself, or willingness to install it (free atgnucash.org)
• An AI assistant that supports MCP (Claude Desktop is themost common; Claude Code, Continue.dev, and others work too)
• 10 minutes to get the sample books running, then another 10to point at your own

Try it without risking anything

The repo ships three sample books — fully-populated syntheticledgers you can talk to without touching your real data. Pickone, point the server at it, and start asking questions.

samples/alex-chen-morales.gnucash — Personal + freelance

A Seattle-based independent software contractor with a US LLC.USD-default. ~141 accounts, ~2,475 transactions across 2025–2026. Has a mortgage, a brokerage with VTSAX/VBTLX/AAPL/MSFT/ETHholdings, a 401(k), four customers spanning USD/EUR/GBP/CAD withforeign-currency invoices, scheduled bills, a budget — prettymuch everything the server can do, all in one book.

samples/lin-wei.gnucash — Cross-border small business

A Shenzhen-based small-business owner running a cross-bordere-commerce operation. CNY-default. ~105 accounts, ~1,960transactions. Chinese-named customers paying in CNY, USD/EURcustomers paying in foreign currency with realized FX gain/losson rate moves, domestic Chinese investments (茅台, 宁德时代,ETFs), an LPR-based mortgage, mixed payment rails (checking +Alipay + WeChat Pay).

samples/sabine-brenner.gnucash — German freelancer, SKR03 chart

A Munich-based freelance consultant. EUR-default, on a GermanSKR03 chart of accounts — every account name in German. ~110accounts, ~1,500 transactions. This is the i18n oracle: if afeature secretly assumes English account names or USD, Sabine'sbook is where it breaks.

All three books are fictional. Seesamples/README.md for the full breakdown ofwhat's in each.

Quick Start (5 minutes)

1. Download

git clone https://github.com/ninetails-io/gnucash-mcp.git

That's the whole install — there's no build or install step. Theclient launches the server with uv run (next step), which syncsdependencies from the lockfile automatically on every start. Toupdate later, just git pull inside the repo; the next launchpicks up new code and new dependencies with nothing else to do.

If you don't have uv, install it with one line:curl -LsSf https://astral.sh/uv/install.sh | sh

2. Make a working copy of a sample book

The server writes audit logs and auto-backups alongside thebook file. You don't want either of those committed back to therepo, so copy the book somewhere outside the repo first:

mkdir -p ~/gnucash-mcp-scratch
cp gnucash-mcp/samples/alex-chen-morales.gnucash ~/gnucash-mcp-scratch/alex.gnucash

3. Tell Claude Desktop about the server

Find your Claude Desktop config:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this — replace /path/to/gnucash-mcp with the repo you justcloned, and GNUCASH_BOOK_PATH with your book's path:

{
  "mcpServers": {
    "gnucash": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/gnucash-mcp",
        "gnucash-mcp",
        "--modules=all"
      ],
      "env": {
        "GNUCASH_BOOK_PATH": "/Users/yourname/gnucash-mcp-scratch/alex.gnucash"
      }
    }
  }
}

uv run --directory runs the server straight from the clone,resyncing dependencies each launch — so a git pull is all ittakes to update. --modules=all loads every tool (111 of them)so you can poke at anything. Once you know what you actually use,narrow it — see choosing a module setbelow.

Quit Claude Desktop completely (not just close the window —quit) and reopen it. Look for the hammer 🔨 icon next to thetext input. That means the server's connected.

4. Try it

Ask Claude:

• "Summarize the book."
• "What's my net worth been doing?"
• "Show me anyone who owes me money."
• "What did I spend on dining last month?"
• "Set a $500 monthly grocery budget."

The first response usually starts with the dashboard fromabove. Everything after that is conversational.

When you're ready to point at your own book, replace theGNUCASH_BOOK_PATH value with the path to your real .gnucashfile (more on that next), restart Claude Desktop, and ask away.

Connecting to your own book

One-time conversion: GnuCash file format

The server only reads the SQLite form of GnuCash files, notthe older XML form. To convert:

1. Open your book in GnuCash itself
2. File → Save As
3. Change "Data Format" to SQLite3
4. Save with a new filename (e.g. mybook-sqlite.gnucash)
5. Keep the XML original as a backup.

On Linux (Debian/Ubuntu), SQLite3 may be missing from the"Data Format" drop-down entirely — GnuCash needs a backend driverthat isn't installed by default. Close GnuCash, install it, thenreopen and the option appears:

sudo apt update && sudo apt install libdbd-sqlite3

You only do this once. From then on, GnuCash and the MCP serverboth work against the same SQLite file.

Set the path

Update GNUCASH_BOOK_PATH in your Claude Desktop config topoint at your own SQLite-format book. Restart Claude Desktop.

Use absolute paths, not ~ or relative paths. OnMac/Linux: /Users/yourname/Documents/mybook.gnucash. OnWindows: C:\\Users\\yourname\\Documents\\mybook.gnucash(note the doubled backslashes — that's a JSON requirement).

Other AI clients

This is an MCP server, soit works with any client that speaks MCP. Notes for non–ClaudeDesktop clients:

• Claude Code: claude mcp add-json gnucash '{"command":"uv","args":["run","--directory","/path/to/gnucash-mcp","gnucash-mcp","--modules=all"],"env":{"GNUCASH_BOOK_PATH":"/path/to/your/book.gnucash"}}'Add --scope user for all projects, --scope project forthis one only.
• Gemini CLI: gemini mcp add -e GNUCASH_BOOK_PATH="/path/to/your/book.gnucash" gnucash uv run --directory /path/to/gnucash-mcp gnucash-mcp --modules=allThis writes a project .gemini/settings.json with the serverregistered; run /mcp list inside Gemini to confirm it showsgnucash - Ready. (Verified on Linux — if GnuCash never offereda SQLite3 export, see the libdbd-sqlite3 note above. The Geminiwalkthrough and the Linux driver fix both come from@hpuri's testing in#89 —thanks.)
• Anything else: set GNUCASH_BOOK_PATH and run uv run --directory /path/to/gnucash-mcp gnucash-mcp. Any client thatcan spawn a command and speak MCP over stdio will work.

Choosing a module set

--modules=all is the easy default — every tool, 107 of them.For day-to-day use you'll probably want less. Pick the role thatmatches how you'll talk to the server. Each role is a groupthat expands to the underlying tool modules; you can also pickthe leaves individually for a finer cut.

Pick one or more, comma-separated:

"args": ["--modules=bookkeeper"]            // personal finance
"args": ["--modules=investor"]              // self-directed investor
"args": ["--modules=freelancer"]            // solo contractor
"args": ["--modules=business"]              // small business (= freelancer + business_complete)
"args": ["--modules=bookkeeper,investor,freelancer"]  // most things

core is force-added regardless; the explicit listing in theexamples above is for clarity. The leaf modules behind eachgroup (reconciliation, reporting, budgets, scheduling,tax_lots, portfolio, etc.) are individually selectable too —run uv run gnucash-mcp --help from the repo for the full menu.

What you can ask it to do

A non-exhaustive tour. Phrase any of these naturally — theassistant translates.

Recording activity

"I spent $47.50 at Safeway today on groceries, paid with myVisa."

Recorded: $47.50 from Credit Card:Visa toExpenses:Groceries on Apr 30, 2026. Description: "Safeway".

Setting up recurring bills

"Set up my rent as a recurring bill. $1,850 on the 1st ofevery month from checking."

Created scheduled transaction "Monthly Rent": $1,850monthly, from Assets:Checking to Expenses:Rent. Next due:May 1, 2026.

Investment tracking

"I bought $1,000 of VTSAX at $170.99/share in my 401(k)."

Recorded VTSAX purchase: 5.85 shares at $170.99/share. Costbasis: $1,000.00. Lot created for capital-gains trackingwhen you eventually sell.

Invoicing customers

"Create a customer called Acme Corp and invoice them $1,500for consulting."

Created customer Acme Corp (id 000005) and invoice 000019:1× Consulting at $1,500.00 = $1,500.00. Open. Tell me whenyou're ready to post it.

Foreign-currency invoicing

"Invoice Berlin Digital €4,200 for Q1 retainer, due in 30 days."

Created EUR invoice 000020 for Berlin Digital GmbH:1× Q1 Retainer at EUR 4,200 = EUR 4,200. Net 30. When theypay, I'll book the realized exchange-rate gain/loss to yourFX account automatically.

Asking questions

"How much did I spend with each vendor this year?"

Office Depot: $2,340 (4 bills, $0 outstanding)CloudHost Inc: $1,200 (2 bills, $600 outstanding)Legal Associates: $3,500 (1 bill, $3,500 outstanding)Total billed $7,040 / paid $2,940 / outstanding $4,100.

Reconciliation

"Help me reconcile checking against the April statement."

[Walks you through it: pulls unreconciled splits, asks youto confirm cleared transactions, computes the runningbalance, marks the matched ones reconciled, leaves themismatches for you to investigate.]

Privacy and safety

Your data does not leave your machine. This server is alocal process that reads and writes a local file. The AIassistant you're talking to (Claude Desktop, etc.) sees theresults of your tool calls — the same content you'd see onscreen — but the file itself stays where it always was.

Every write is logged. A human-readable audit trail livesalongside your book file at <your-book>.gnucash.mcp/audit/,one log file per day. You can read it at any time to seeexactly what changed and when. Sample entry:

2026-04-30 14:32  POST INVOICE  id:000019
    total: 1500.00  date: 2026-04-30
    account: Assets:Accounts Receivable  txn:a1b2c3d4

Automatic backups. Before the very first write of eachsession, the server snapshots your book to<your-book>.gnucash.mcp/backups/ — so if something goeswrong, you can roll back to a known-good state withoutrelying on Time Machine or your own habit. Backups areverified with PRAGMA integrity_check before being declaredvalid, and skipped when the book hasn't changed since thelast snapshot. See docs/RESTORE_FROM_BACKUP.mdfor the rollback procedure.

Reading timestamps: backup filenames carry UTCtimestamps (filesystem-safe and unambiguous across traveland DST); audit and debug logs use local-dated dailyfiles, matching how you'd search for "what happenedTuesday." Near midnight these can differ by a day — thelist_backups tool always reports both the ISO timestampand a human age, so prefer it over eyeballing filenames.

Reconciled splits are protected. The server refuses todelete or modify reconciled splits without an explicitoverride, so a careless prompt can't quietly invalidate yourlast bank reconciliation.

Voiding ≠ deleting. When you tell the AI to "void thistransaction," it uses GnuCash's proper accounting void —preserving the transaction for the audit trail with valueszeroed. Deletion is the destructive option; the AI will tellyou which one it's doing.

Disclaimer: This software is provided "as is" under theMIT License, without warranty of any kind. Theauthors are not liable for any data loss, corruption, orfinancial discrepancy arising from its use. You are solelyresponsible for maintaining your own backups and verifyingthe accuracy of your books.

Limiting what the AI can see

Each tool's description lives in the AI's system prompt, whichcosts context on every message. Narrowing the toolset to whatyou actually use makes every conversation cheaper. Seechoosing a module set above for thefive role-based options (core, bookkeeper, investor,freelancer, business).

You can also set GNUCASH_MCP_MODULES=core,bookkeeper as anenvironment variable instead of --modules=... in the JSONargs.

What's new in v1.4.2

One call wide, every surface honest — every entry traces to anamed moment of live friction:

• The bulk grammar is complete — update_transactions(per-row TSV edits), broadcast updates (one change, many GUIDs),create_prices (batch quotes + a stale-price work list), and acur column so foreign-denominated transactions batch-enterlike everything else.
• Reconciliation kept honest — reconcile_all honors itsstatement-date bound; a new get_reconciliation_status tooldrills down behind the dashboard's counts; statement-lessaccounts opt out of nagging with the no_reconcile slot; paid-offdormant cards stop warning forever.
• The dashboard hands each session its vocabulary — your topaccounts by recent posting frequency, in short-GUID form, so theAI reaches for compact refs from the first call.
• First outside code contribution — @bhbrunt's price-lookupmemoization and split-graph preload took a 33k-split book'ssummary from never-completing to under 10 seconds (and madesmall books ~45% faster too).
• Audit trail hardened — user text is escaped before itreaches the audit log (no forged entries, no smuggledinstructions), price dry-runs agree with live execution, andmoving the date of a reconciled transaction now requiresforce=true (behavior change).

Tests: 1,954 passing.

What's new in v1.4.1

Batch entry grows up, driven by the bookkeeper's daily workflow:

• The TSV header declares the layout — opt-in memo columns(per-split memos), a notes column (per-transaction notes), andqty columns (investment shares / foreign-currency splits).Legacy submissions parse unchanged; typo'd column names rejectby name; a row may simply end once its last split's amount andaccount are present.
• Auto-fill from history — a row with no split cells at allreproduces your most recent transaction with that description,marked with its source. Twelve recurring bills = twelveref-date-description rows; dry_run the batch to preview everymatch first.
• Batch delete — delete_transaction takes a list of GUIDs:one call, one save, all-or-nothing.
• Every annotation field reachable — notes + action oninvoice/bill/voucher/credit-note line items, a payment memo onpay_invoice, account notes (shared with GnuCash desktop'seditor), and scheduled transactions that actually keep theirdescription.
• Find accounts without paging — query on list_accountsmatches path and description, so "4930" finds the SKR03 account.
• Plus the v1.4 adversarial-review hardening (transactionalswitch_book, per-book backup scoping, i18n fixes) andmonthly-close valuation for flow reports.

Tests: 1,856 passing.

What's in v1.4.0

The release where batch transaction entry entered the scene.v1.3 finished the businessmodule; v1.4 makes the server work correctly on non-English books,adds bulk and multi-book workflows, and lands a secondmulti-currency correctness pass.

Internationalization:

• Account resolution keys off GNCAccountType, never a localizedaccount name — so a de_DE, es_MX, or zh_CN book resolvesIncome, Imbalance, and FX accounts correctly. Designatedaccounts (FX gain/loss, discounts) self-heal via a KVP slot thatis locale- and rename-proof after first use.
• Suspense / Imbalance accounts are excluded from runway andlow-cash signals so a lopsided book doesn't skew the dashboard.
• Three synthetic personas ship in-repo: Alex (USD), LinWei (CNY, zh_CN chart of accounts), and Sabine Brenner(German DATEV SKR03, EUR) — the German book is what makes thei18n bug class visible.

Batch and multi-book workflows:

• create_transactions enters many transactions in one atomiccall and returns a per-transaction result you can correlate backby a caller-supplied ref, plus a duplicates table keyed to it.
• GNUCASH_BOOK_PATH accepts an os.pathsep-separated list ofbooks; switch_book flips the active book mid-session (matchedby unique filename prefix) with a context-reset banner socross-book references don't leak.

Reporting:

• Every list-returning tool paginates with offset and aShowing X-Y of Z indicator; dated tools also render thecovered date range.
• The aggregation reports take group_by for sub-period columns.

Multi-currency correctness (second pass):

• FX gain/loss booked in the book's default currency, both-foreignposting splits valued at the posting-date rate, and lot costbasis in the default currency. Foreign debts with no FX rate areexcluded from debt_payoff_plan with a warning.
• An FX entry-sanity warning fires when a cross-currencytransaction's implied rate diverges sharply from the latestprice on file.

Tests: 1,714 passing.

A condensed changelog of major releases lives inCHANGELOG.md.

Troubleshooting

No 🔨 hammer icon, or "tool not found"

• Quit Claude Desktop completely, then reopen it. (Closing thewindow isn't enough — you have to quit the application.)
• Verify the paths in your config are absolute and correct.
• Check the JSON for trailing commas — they break the configsilently.

"Book not found"

• Use absolute paths, not ~ or relative paths.
• Mac/Linux: /Users/yourname/Documents/book.gnucash
• Windows: C:\\Users\\yourname\\Documents\\book.gnucash(doubled backslashes — JSON requirement)

"Cannot open book" / piecash errors

• Confirm your book is in SQLite format, not XML.
• Make sure GnuCash isn't open with the same book — file lock.
• Try opening the book in GnuCash itself to verify it isn'tcorrupted.

"Account not found"

• Use full account paths: Expenses:Groceries, not justGroceries.
• Or ask the assistant to list accounts: "List my accounts."

Multiple server processes after a client restart

Claude Desktop (and some other MCP clients) may briefly spawntwo or three copies of the server when relaunching. This isclient behavior, not a server bug, and it's mostly harmless:the server opens your book per-request and releases the filelock between calls, so overlapping processes contend only formoments. If you see persistent Lock on the file errors aftera client restart, quit the client fully, confirm withpgrep -fl gnucash-mcp that no strays remain, and relaunch.

Something went wrong

• Open the audit log at <your-book>.gnucash.mcp/audit/ —every write since the server first ran is there withbefore/after detail.
• If you need to roll back, docs/RESTORE_FROM_BACKUP.mdwalks through it.

Support the project

If gnucash-mcp is useful to you, considerbuying me a coffee. It helpskeep development going.

For developers

Contributor guide and design notes live inCLAUDE.md. Quick orientation:

uv sync --extra dev
uv run pytest                       # 1,954 tests as of v1.4.2
uv run ruff check src/ tests/
uv run black --check src/ tests/

The uv run --directory PATH ... form the Quick Start uses isalso how you point a client at a specific worktree — swap thedirectory and you're running that checkout, no reinstall. If youprefer a gnucash-mcp binary on your PATH instead, uv tool install -e ./gnucash-mcp still works and tracks your source.

The server is built onpiecash (Pythoninterface to GnuCash's SQLite books) and theMCP Python SDK.Roughly 18,000 lines of Python source, 20,000 lines of tests,modularized so disabled modules cost nothing at runtime.

License

MIT.

Acknowledgments

• GnuCash — the free, open-sourceaccounting software this server makes conversational.
• piecash — Pythoninterface to GnuCash SQLite books.
• MCP Python SDK —the Model Context Protocol implementation.