The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Gnucash MCP listing page.
Free, open-source accounting software that works with the LLM.
Talk to your GnuCash books through Claude (or any AI assistant that supports MCP). Ask "how am I doing this month," dictate your transactions out loud, hand over the books for the AI to keep up while you focus on running your life or your business.
Your data stays on your machine. Your audit log stays on your machine. Nothing is uploaded anywhere — the AI reads and writes your local GnuCash file, and that's it.
Three real, populated sample books ship in this repo so you can try it before you commit anything. They're realistic — full years of activity, mixed currencies, customers, invoices, budgets, the works. Walk through one in five minutes; if it clicks, point the server at your own book and you're done.
The samples are frozen snapshots, not living books — expect the
dashboard to flag stale prices and pending scheduled transactions
that have accumulated since their last regeneration. That's
realistic too (it's what a book looks like after a vacation). To
rebuild them fresh through today, run the deterministic generators
in scripts/synthetic_book/ (phase scripts, in order).
This is what your AI assistant sees when it opens one of the sample books — a complete financial dashboard in a single call:
That's not a screenshot — that's the AI's actual orientation view. Net worth trajectory, runway, budget pacing, who owes you money, what's overdue, what hasn't been reconciled. One call, and your assistant has the full picture before you've even finished saying hello.
.gnucash file is the system of record;
this just gives your AI a way to read and write it the way
GnuCash itself does.You don't need to be a developer. You need:
The repo ships three sample books — fully-populated synthetic ledgers you can talk to without touching your real data. Pick one, point the server at it, and start asking questions.
samples/alex-chen-morales.gnucash — Personal + freelanceA 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/ETH holdings, a 401(k), four customers spanning USD/EUR/GBP/CAD with foreign-currency invoices, scheduled bills, a budget — pretty much everything the server can do, all in one book.
samples/lin-wei.gnucash — Cross-border small businessA Shenzhen-based small-business owner running a cross-border e-commerce operation. CNY-default. ~105 accounts, ~1,960 transactions. Chinese-named customers paying in CNY, USD/EUR customers paying in foreign currency with realized FX gain/loss on rate moves, domestic Chinese investments (茅台, 宁德时代, ETFs), an LPR-based mortgage, mixed payment rails (checking + Alipay + WeChat Pay).
samples/sabine-brenner.gnucash — German freelancer, SKR03 chartA Munich-based freelance consultant. EUR-default, on a German SKR03 chart of accounts — every account name in German. ~110 accounts, ~1,500 transactions. This is the i18n oracle: if a feature secretly assumes English account names or USD, Sabine's book is where it breaks.
All three books are fictional. See samples/README.md for the full breakdown of what's in each.
Download gnucash-mcp.mcpb from the
latest release
and double-click it. Claude Desktop installs the server — no
terminal, no config file, no Python. The installer asks three
things:
That's the entire install. Skip ahead to step 4 to take it for a spin.
The path below gives you an updatable git-clone install — for Claude Desktop without the bundle, for other AI clients, or for hacking on the server itself.
The second command gives you a gnucash-mcp command (in
~/.local/bin) with its dependencies in a private environment —
your other Python projects never see them. The -e makes it an
updatable install: the command runs whatever code is in your
clone, so updating is git pull plus a server restart. The one
exception: if an update changes dependencies, run
uv tool install -e ./gnucash-mcp --reinstall once.
If you don't have
uv, install it with one line:curl -LsSf https://astral.sh/uv/install.sh | sh
The server writes audit logs and auto-backups alongside the book file. You don't want either of those committed back to the repo, so copy the book somewhere outside the repo first:
Find your Claude Desktop config:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonAdd this — replace yourname in both paths:
Use the full path to the command: GUI apps launch without
your shell's PATH, so a bare gnucash-mcp may not resolve even
though it works in your terminal. (uv tool dir --bin prints
the right directory if yours differs.) --modules=all loads
every tool (86 of them) so you can poke at anything. Once you
know what you actually use, narrow it — see
choosing a module set below.
Quit Claude Desktop completely (not just close the window — quit) and reopen it. Look for the hammer 🔨 icon next to the text input. That means the server's connected.
Ask Claude:
The first response usually starts with the dashboard from above. Everything after that is conversational.
When you're ready to point at your own book, replace the
GNUCASH_BOOK_PATH value with the path to your real .gnucash
file (more on that next), restart Claude Desktop, and ask away.
The server only reads the SQLite form of GnuCash files, not the older XML form. To convert:
mybook-sqlite.gnucash)On Linux (Debian/Ubuntu), SQLite3 may be missing from the "Data Format" drop-down entirely — GnuCash needs a backend driver that isn't installed by default. Close GnuCash, install it, then reopen and the option appears:
You only do this once. From then on, GnuCash and the MCP server both work against the same SQLite file.
Update GNUCASH_BOOK_PATH in your Claude Desktop config to
point at your own SQLite-format book. Restart Claude Desktop.
Use absolute paths, not
~or relative paths. On Mac/Linux:/Users/yourname/Documents/mybook.gnucash. On Windows:C:\\Users\\yourname\\Documents\\mybook.gnucash(note the doubled backslashes — that's a JSON requirement).
This is an MCP server, so
it works with any client that speaks MCP. Everywhere below,
gnucash-mcp means the full path from the install step
(/Users/yourname/.local/bin/gnucash-mcp; uv tool dir --bin
prints yours).
claude mcp add-json gnucash '{"command":"/Users/yourname/.local/bin/gnucash-mcp","args":["--modules=all"],"env":{"GNUCASH_BOOK_PATH":"/path/to/your/book.gnucash"}}'
Add --scope user for all projects, --scope project for
this one only.gnucash-mcp, type STDIO,
"Command to launch" = the full gnucash-mcp path, one
argument --modules=all, and an environment variable
GNUCASH_BOOK_PATH = your book's path.gemini mcp add -e GNUCASH_BOOK_PATH="/path/to/your/book.gnucash" gnucash /Users/yourname/.local/bin/gnucash-mcp --modules=all
This writes a project .gemini/settings.json with the server
registered; run /mcp list inside Gemini to confirm it shows
gnucash - Ready. (Verified on Linux — if GnuCash never offered
a SQLite3 export, see the libdbd-sqlite3 note above. The Gemini
walkthrough and the Linux driver fix both come from
@hpuri's testing in
#89 —
thanks.)GNUCASH_BOOK_PATH and run
gnucash-mcp. No install at all? uv run --directory /path/to/gnucash-mcp gnucash-mcp and
python -m gnucash_mcp (with the repo on the path) both
still work. Any client that can spawn a command and speak
MCP over stdio will do.--modules=all is the easy default — every tool, 88 of them.
For day-to-day use you'll probably want less. Pick the role that
matches how you'll talk to the server. Each role is a group
that expands to the underlying tool modules; you can also pick
the leaves individually for a finer cut.
| Role | What it gives you | Tools |
|---|---|---|
core | Ledger primitives — accounts, transactions, balances, slots, audit log, backups, balance sheet, reconciliation. Always loaded. | 29 |
bookkeeper | Run reports, manage budgets, schedule recurring transactions. The personal-finance management cluster. (Reconciliation moved into core — any configuration that handles money needs it.) | 17 |
investor | Cost-basis tracking + price/commodity management. Tax-lot accounting needs prices to compute gains, so the bundle is the useful unit. | 12 |
freelancer | Party + document management (polymorphic: customers by default; vendors/employees unlock with business_complete), sales tax, billterms, jobs, credit notes. The full solo-consultant toolkit. | 26 |
business | Full small-business package — group alias: freelancer's tools with the vendor/employee sides unlocked, plus vendor reports. | 27 |
Pick one or more, comma-separated:
core is force-added regardless; the explicit listing in the
examples above is for clarity. The leaf modules behind each
group (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.
A non-exhaustive tour. Phrase any of these naturally — the assistant translates.
"Here's my August checking statement." (attach the PDF)
Rehearsed 31 lines against your book: 24 new, 6 already entered (claimed), 1 needs a look — here's the comparison. Confirm and I'll land the month: entered, categorized, and reconciled to the closing balance in one step.
One statement, two calls, a tied book. The dry-run classifies every line with evidence before anything is written, and the commit refuses wholesale rather than land a month that doesn't tie.
"I spent $47.50 at Safeway today on groceries, paid with my Visa."
Recorded: $47.50 from Credit Card:Visa to Expenses:Groceries on Apr 30, 2026. Description: "Safeway".
"Set up my rent as a recurring bill. $1,850 on the 1st of every month from checking."
Created scheduled transaction "Monthly Rent": $1,850 monthly, from Assets:Checking to Expenses:Rent. Next due: May 1, 2026.
"I bought $1,000 of VTSAX at $170.99/share in my 401(k)."
Recorded VTSAX purchase: 5.85 shares at $170.99/share. Cost basis: $1,000.00. Lot created for capital-gains tracking when you eventually sell.
"Create a customer called Acme Corp and invoice them $1,500 for consulting."
Created customer Acme Corp (id 000005) and invoice 000019: 1× Consulting at $1,500.00 = $1,500.00. Open. Tell me when you're ready to post it.
"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 they pay, I'll book the realized exchange-rate gain/loss to your FX account automatically.
"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.
"Help me reconcile checking against the April statement."
[Walks you through it: pulls unreconciled splits, asks you to confirm cleared transactions, computes the running balance, marks the matched ones reconciled, leaves the mismatches for you to investigate.]
Your data does not leave your machine. This server is a local process that reads and writes a local file. The AI assistant you're talking to (Claude Desktop, etc.) sees the results of your tool calls — the same content you'd see on screen — but the file itself stays where it always was.
Every write is logged. A human-readable audit trail lives
alongside your book file at <your-book>.gnucash.mcp/audit/,
one log file per day. You can read it at any time to see
exactly what changed and when. Sample entry:
Automatic backups. Before the very first write of each
session, the server snapshots your book to
<your-book>.gnucash.mcp/backups/ — so if something goes
wrong, you can roll back to a known-good state without
relying on Time Machine or your own habit. Backups are
verified with PRAGMA integrity_check before being declared
valid, and skipped when the book hasn't changed since the
last snapshot. See docs/RESTORE_FROM_BACKUP.md
for the rollback procedure.
Reading timestamps: backup filenames carry UTC timestamps (filesystem-safe and unambiguous across travel and DST); audit and debug logs use local-dated daily files, matching how you'd search for "what happened Tuesday." Near midnight these can differ by a day — keep that in mind when matching a backup to a day's log.
Reconciled splits are protected. The server refuses to delete or modify reconciled splits without an explicit override, so a careless prompt can't quietly invalidate your last bank reconciliation.
Voiding ≠ deleting. When you tell the AI to "void this transaction," it uses GnuCash's proper accounting void — preserving the transaction for the audit trail with values zeroed. Deletion is the destructive option; the AI will tell you which one it's doing.
Disclaimer: This software is provided "as is" under the MIT License, without warranty of any kind. The authors are not liable for any data loss, corruption, or financial discrepancy arising from its use. You are solely responsible for maintaining your own backups and verifying the accuracy of your books.
Each tool's description lives in the AI's system prompt, which
costs context on every message. Narrowing the toolset to what
you actually use makes every conversation cheaper. See
choosing a module set above for the
five role-based options (core, bookkeeper, investor,
freelancer, business).
You can also set GNUCASH_MCP_MODULES=core,bookkeeper as an
environment variable instead of --modules=... in the JSON
args.
The statement is the call — the bulk-operations line closes with its capstone, and rehearsal spreads to every consequential write:
enter_statement — a complete bank statement (opening
balance, closing balance, every line) enters, claims its
matches against transactions already in the book, and
reconciles in ONE atomic call. Dry-run first by default: every
line classified with side-by-side evidence, and a projected
balance tie that guarantees a rehearsal that ties is a commit
that will tie. No half-landed months, ever.pay_document gains dry_run
(proposed splits, FX and discount treatment, projected balance,
zero writes), and batch entry's dry-run shows self-contained
duplicate comparisons with a review_required status that
never masquerades as clearance.Tests: 2,100+ passing, parallel by default (full suite < 40s).
One call wide, every surface honest — every entry traces to a named moment of live friction:
update_transactions
(per-row TSV edits), broadcast updates (one change, many GUIDs),
create_prices (batch quotes + a stale-price work list), and a
cur column so foreign-denominated transactions batch-enter
like everything else.reconcile_all honors its
statement-date bound; a new get_reconciliation_status tool
drills down behind the dashboard's counts; statement-less
accounts opt out of nagging with the no_reconcile slot; paid-off
dormant cards stop warning forever.force=true (behavior change).Tests: 1,954 passing.
Batch entry grows up, driven by the bookkeeper's daily workflow:
memo columns
(per-split memos), a notes column (per-transaction notes), and
qty columns (investment shares / foreign-currency splits).
Legacy submissions parse unchanged; typo'd column names reject
by name; a row may simply end once its last split's amount and
account are present.dry_run the batch to preview every
match first.delete_transaction takes a list of GUIDs:
one call, one save, all-or-nothing.pay_document, account notes (shared with GnuCash desktop's
editor), and scheduled transactions that actually keep their
description.query on list_accounts
matches path and description, so "4930" finds the SKR03 account.switch_book, per-book backup scoping, i18n fixes) and
monthly-close valuation for flow reports.Tests: 1,856 passing.
The release where batch transaction entry entered the scene. v1.3 finished the business module; v1.4 makes the server work correctly on non-English books, adds bulk and multi-book workflows, and lands a second multi-currency correctness pass.
Internationalization:
GNCAccountType, never a localized
account name — so a de_DE, es_MX, or zh_CN book resolves
Income, Imbalance, and FX accounts correctly. Designated
accounts (FX gain/loss, discounts) self-heal via a KVP slot that
is locale- and rename-proof after first use.Batch and multi-book workflows:
create_transactions enters many transactions in one atomic
call and returns a per-transaction result you can correlate back
by a caller-supplied ref, plus a duplicates table keyed to it.GNUCASH_BOOK_PATH accepts an os.pathsep-separated list of
books; switch_book flips the active book mid-session (matched
by unique filename prefix) with a context-reset banner so
cross-book references don't leak.Reporting:
offset and a
Showing X-Y of Z indicator; dated tools also render the
covered date range.group_by for sub-period columns.Multi-currency correctness (second pass):
debt_payoff_plan with a warning.Tests: 1,714 passing.
A condensed changelog of major releases lives in CHANGELOG.md.
~ or relative paths./Users/yourname/Documents/book.gnucashC:\\Users\\yourname\\Documents\\book.gnucash
(doubled backslashes — JSON requirement)Expenses:Groceries, not just
Groceries.Claude Desktop (and some other MCP clients) may briefly spawn
two or three copies of the server when relaunching. This is
client behavior, not a server bug, and it's mostly harmless:
the server opens your book per-request and releases the file
lock between calls, so overlapping processes contend only for
moments. If you see persistent Lock on the file errors after
a client restart, quit the client fully, confirm with
pgrep -fl gnucash-mcp that no strays remain, and relaunch.
<your-book>.gnucash.mcp/audit/ —
every write since the server first ran is there with
before/after detail.If gnucash-mcp is useful to you, consider buying me a coffee. It helps keep development going.
Contributor guide and design notes live in CLAUDE.md. Quick orientation:
The installed gnucash-mcp command tracks your clone live: it
serves whatever branch the checkout is on, so switching branches
switches the served code at the next restart — handy for testing,
worth remembering when you forget you're mid-branch. To run a
DIFFERENT checkout (a second worktree) without touching the
install, uv run --directory PATH gnucash-mcp still runs any
directory you point it at.
The server is built on piecash (Python interface to GnuCash's SQLite books) and the MCP Python SDK. Roughly 18,000 lines of Python source, 20,000 lines of tests, modularized so disabled modules cost nothing at runtime.
MIT.