gnucash-mcp

gnucash-mcp

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.

The server runs on your machine and works on your local GnuCash file; the file and its audit log never leave it. Your AI assistant sees what its tool calls return (balances, payees, invoices), just as you would on screen.

Upgrading from 1.4? Read the upgrade guide before your first write with 1.5.

Install in one click: on Claude Desktop, download the .mcpb bundle from the latest release, double-click it, and you're running — no terminal, no config files. Every other MCP client — ChatGPT/Codex, Gemini, Antigravity, and the rest — connects with a few lines of setup. Either way, the AI subscription you already pay for becomes a bookkeeper that never sends a bill.

Three realistic sample books let you try it before you commit anything: full years of activity, mixed currencies, customers, invoices, and budgets. The Claude Desktop bundle includes them; from a clone, one command builds them. Walk through one in five minutes; if it clicks, point the server at your own book and you're done.

---

What does it look like?

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

Book: alex-chen-morales.gnucash
Currency: USD
Data range: 2025-01-01 to 2026-10-08
Last entry: 2026-10-08 (today)
Chart of accounts: 111 total (109 active) — drill into any branch with list_accounts(root="Assets:Investments"):
  Assets (25 total): Investments (9), Current Assets (5), Fixed Assets (3), Receivables (3), Retirement (3)
  Liabilities (8 total): Credit Card (3), Loans (3)
  Equity (3 total)
  Income (11 total): Investment Income (6)
  Expenses (64 total): Business (14), Taxes (10), Utilities (6), Auto (4), Housing (4), Interest (4), Insurance (3), Pet (3)
Assets: USD 874270.54
  Condo: USD 475000.00
  VTSAX: 453.4039 VTSAX @ 185.53 (USD 84120.03)
  UWRP 403(b): USD 74778.40
  Savings Account: USD 60000.00
  Cascade Code LLC Checking: USD 41390.64
  ...
Liabilities: USD 389695.79
  Credit cards (2): USD 1319.99
  Loans & other (2): USD 385873.30
  Top 3: Mortgage USD 373846.80, Auto Loan USD 12026.50, Chase Sapphire USD 876.31
Receivables: 2 accounts, USD 27324.47 (4 invoices, 0 overdue; included in Assets total)
  Accounts Receivable: USD 22425.00
  Accounts Receivable EUR: USD 4899.47
Payables: 1 account, USD 2502.50 (1 bill, 0 overdue; included in Liabilities total)
  Accounts Payable: USD 2502.50
Jobs: 3 active
Frequently used accounts (last 180 days — any account parameter accepts the %guid or the full name; a %guid is fewer tokens and faster to write):
  %528b7d9	Assets:Current Assets:Checking Account [BANK]
  %8799a0a	Liabilities:Credit Card:Chase Sapphire [CREDIT]
  %839fcf8	Expenses:Dining
  ...
Reconciliation:
  6 accounts current
Net worth trajectory:
  12mo ago: USD 345,969
   6mo ago: USD 381,961
   3mo ago: USD 429,392
   1mo ago: USD 443,546
       now: USD 484,575
Monthly net (income - expenses, last 6 months):
  Oct 2026 (MTD): +11,955 (vs Sep 1-8: -2,365)
  Sep 2026: +25,894
  Aug 2026: +7,588
  Jul 2026: +10,307
  Jun 2026: +24,092
  May 2026: +9,017
Runway: 579 days (USD 246,844 liquid / USD 426/day cash out incl. debt paydown, 180-day avg; cards owe USD 1,320)
Budget (2026 Annual Budget): USD 27,736 spent / USD 28,683 expected by today (-3%)
Transactions: 2227
Scheduled: 20 recurring, 16 due in next 7 days (USD 15,128 out)
Business: 8 customers, 3 vendors
Budgets: 2
Commodities: AAPL, CAD, ETH, EUR, MSFT, USD, VBTLX, VTSAX

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.

---

Who is this for?

• Personal finance people who keep their books in GnuCash and want to dictate transactions, ask their assistant where the money's going, get reconciliation help, plan budgets.
• Small business owners who run their books in GnuCash and want to issue invoices, track receivables, see vendor spending, manage cash flow without leaving the conversation.
• People who care that their data stays local. No cloud sync. No SaaS. Your .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:

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

---

Try it without risking anything

The repo ships three sample personas — synthetic ledgers you can talk to without touching your real data. The bundle carries them fully built; from a clone, one command builds them. Pick one, point the server at it, and start asking questions.

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

A Seattle-based independent software contractor with a single-member LLC and a spouse on a hospital payroll. USD-default. 111 accounts and over 2,000 transactions from 2025 to the build date. Has a mortgage, a brokerage with VTSAX/VBTLX/AAPL/MSFT/ETH holdings, a Solo 401(k) beside the spouse's 403(b), eight customers invoiced in USD, EUR and CAD, a subcontractor billed through A/P, Washington B&O tax, scheduled bills, budgets — pretty much everything the server can do, all in one book.

samples/lin-wei.gnucash — Shenzhen software studio

A Shenzhen developer running a registered sole-proprietor studio that builds cross-border e-commerce software, with a spouse on a hospital payroll. CNY-default, on a native zh_CN chart. 101 accounts and about 3,000 transactions. Shenzhen tech clients (Tencent, DJI, SF Tech and others) paying in CNY, USD/EUR clients paying in foreign currency with realized FX gain/loss on rate moves, domestic Chinese investments (宁德时代 and two ETFs), a part-time employee, an HKD credit card, a mortgage, and mixed payment rails (corporate account + Alipay + WeChat Pay).

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

A Munich-based freelance designer. EUR-default, on a German SKR03 chart of accounts — every account name in German. 125 accounts and about 1,900 transactions, with live VAT returns and a company car under the 1% rule. If a feature 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.

---

Quick Start

Install in one click (Claude Desktop)

Download the .mcpb bundle 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:

• Your GnuCash book(s) — a file picker. Books must be in SQLite format; if yours is the older XML format, do the one-time conversion first. Pick several books to switch between them in-chat.
• Demo books — one checkbox serves the three sample books described above, so you can explore on fictional money before (or instead of) connecting your own.
• "Do you invoice clients?" — yes adds the business suite (customer invoices, vendor bills, employee expenses). Everything else — budgets, scheduled transactions, investment tracking — is always on.

That's the entire install.

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 from above. Everything after that is conversational.

When you're ready for your own book, see Connecting to your own book below.

Other AI clients, or installing from source

ChatGPT and Codex, Claude Code, Gemini CLI, Google Antigravity, and any other MCP client connect through an install from a git clone, as do database books and anyone working on the server: see docs/CLIENTS.md.

---

Connecting to your own book

One-time conversion: GnuCash file format

The server only reads the SQLite form of GnuCash files, not the 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 driver that isn't installed by default. Close GnuCash, install it, then reopen and the option appears:

sudo apt update && sudo apt install libdbd-sqlite3

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

GnuCash 3.8 or newer. Once the server has written to a book, the book carries a feature marker ("Use natural signs in budget amounts") that GnuCash 3.8 introduced, and GnuCash 3.0–3.7 refuses to open a book marked with a feature it does not know. GnuCash 3.8 and later mark any book with a budget the same way when they open it, so this only matters if you still run an older 3.x. The server is tested against GnuCash 5.12.

Point the server at it

With the bundle, choose the book in the GnuCash extension's settings in Claude Desktop, then restart Claude Desktop. With a clone install, set GNUCASH_BOOK_PATH to the book's absolute path; see Using your own book.

Or: keep the book in PostgreSQL or MySQL

GnuCash can also keep a book in a database instead of a file, and the server serves one of those too. Point it at a connection string instead of a path:

{
  "command": "/Users/yourname/.local/bin/gnucash-mcp",
  "args": ["--modules=all"],
  "env": {
    "GNUCASH_BOOK_URI": "postgresql://user:password@localhost:5432/gnucash",
    "GNUCASH_LOG_DIR": "/Users/yourname/gnucash-mcp-logs"
  }
}

Install the driver alongside the server — postgres or mysql (MariaDB uses the same one). From inside your clone (the gnucash-mcp folder; see installing from source):

uv tool install -e ".[postgres]" --reinstall

For MySQL / MariaDB the connection string is mysql+pymysql://user:password@localhost:3306/gnucash and the extra is [mysql]: uv tool install -e ".[mysql]" --reinstall. The shorter forms GnuCash itself writes, mysql:// and postgres://, work too; the server uses the driver the extra installed.

Install from the clone, as above, not by name: the name gnucash-mcp on PyPI belongs to a different project.

To move an existing book across: open it in GnuCash, File → Save As, pick postgres or mysql, and fill in the connection details. (On Debian/Ubuntu those entries need sudo apt install libdbd-pgsql or libdbd-mysql, the same way SQLite3 needs libdbd-sqlite3; the macOS and Windows builds ship all three.) Keep the file — it stays a perfectly good backup of everything up to the moment you switched.

Worth knowing before you switch:

• GNUCASH_BOOK_PATH and GNUCASH_BOOK_URI are mutually exclusive — a book is a file or a database, and setting both is a startup error rather than a coin toss over which ledger your writes land in.
• GNUCASH_LOG_DIR becomes required. Audit and debug logs normally live in a folder beside the book file; a connection string has no "beside".
• One book per server. switch_book matches on filenames, so multi-book stays a file feature.
• The server stops taking backups. This is the real trade-off: the automatic safety net exists because it can snapshot a file, and it can't snapshot your database. create_backup says so rather than pretending. Set up pg_dump or mysqldump on a schedule before you move a real book over — see docs/RESTORE_FROM_BACKUP.md.
• Your password is masked wherever the server names the book — in tool results, in the dashboard header, and in the audit log — and in every error message, log line, and startup error, including the ones a database driver writes. A password given as a query parameter (?password=…, sslpassword=…) is masked the same way.
• Put the connection string in the env block, not on the command line. --book-uri works, but a password in a command line is visible to every user of the machine in the process list. On PostgreSQL you can also leave the password out of the string entirely and let the driver read PGPASSWORD or ~/.pgpass.

Both dialects are exercised by the test suite and CI: PostgreSQL 16 and MariaDB 11, each against a real server.

---

Choosing a module set

--modules=all is the easy default — every tool, 86 of them. For day-to-day use you'll probably want less. Pick the role that matches how you'll talk to the server; you can also pick the modules behind each role 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	Everything except business: reports, budgets, scheduled transactions, prices, and investment lots. The personal-finance set.	30
investor	Cost-basis tracking and price management only (a subset of bookkeeper).	13
business	Customers, vendors, and employees; invoices, bills, vouchers, and credit notes; sales tax, payment terms, jobs, and vendor reports.	27

Pick one or more, comma-separated:

"args": ["--modules=bookkeeper"]            // personal finance
"args": ["--modules=investor"]              // self-directed investor
"args": ["--modules=business"]              // invoicing, freelance or small business
"args": ["--modules=bookkeeper,business"]   // everything (same as all)

core is added regardless. freelancer and business_complete, the names 1.4 used, are still accepted and mean business. The modules behind each role (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 — the assistant translates.

Entering a whole statement

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

Recording activity

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

Setting up recurring bills

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

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. Cost basis: $1,000.00. Lot created for capital-gains tracking when you eventually sell.

Invoicing customers

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

If you open a server-posted invoice in GnuCash's Process Payment dialog, set its "Post To" account to the invoice's receivable first: the dialog lists only the documents posted to the selected account.

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 they pay, I'll book the realized exchange-rate gain/loss to your FX 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 you to confirm cleared transactions, computes the running balance, marks the matched ones reconciled, leaves the mismatches for you to investigate.]

---

Privacy and safety

Your book file never leaves 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:

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 first write of each session (and again as a long-running session crosses into a new backup period), 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.

---

Known limitations

• Don't edit in GnuCash desktop and through the server at the same time. The server respects GnuCash's lock but doesn't hold one of its own (it opens the book for one call at a time), so GnuCash won't warn you that the server is using the book.
• Books with "Use Trading Accounts" turned on: transactions across currencies or commodities, including stock and fund purchases, are refused, because the server can't yet write trading splits the way GnuCash does. Enter those in GnuCash desktop; everything in a single currency works as usual.
• GnuCash 3.8 or newer. A book the server has written to carries a feature marker that GnuCash 3.0–3.7 can't open.
• Foreign-currency spending and income are valued at each month's closing rate in the spending and income reports, not at the cash that paid for them; cash_flow reports the cash.

The full list is in CHANGELOG.md.

---

Limiting what the AI can see

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 four roles (core, bookkeeper, investor, business).

You can also set GNUCASH_MCP_MODULES=core,bookkeeper as an environment variable instead of --modules=... in the JSON args.

---

What's new in v1.5.0

• Books in a database. Point the server at a book GnuCash keeps in PostgreSQL or MySQL/MariaDB, not just a SQLite file — see Or: keep the book in PostgreSQL or MySQL. PostgreSQL support was contributed by @vchatela.
• Everything is stored the way GnuCash desktop stores it. Scheduled transactions run in desktop's Since Last Run, budgets, invoices, credit notes, voids, and prices read the same in both, and invoice totals match GnuCash's own to the cent. Upgrading from 1.4? Read the upgrade guide first.
• Prepayments. Record a customer's or vendor's overpayment as money held for them, settle a later invoice from it, and unpost a paid invoice without losing the payment.
• Num and document links on every transaction tool, with the number used as a duplicate check.
• A map of your chart of accounts on the dashboard, so the assistant knows where every account lives before it asks.
• Sample books built from source, each checked against its own country's tax practice (US/Washington, Germany, China) and current to the day they're built.

Earlier releases are in CHANGELOG.md.

---

Troubleshooting

No 🔨 hammer icon, or "tool not found"

• Quit Claude Desktop completely, then reopen it. (Closing the window 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 config silently.

"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. The server honors GnuCash's lock but deliberately takes none of its own (it holds the book for one call at a time), so GnuCash will open a book the server is using without a warning. Don't edit in both at once.
• Try opening the book in GnuCash itself to verify it isn't corrupted.

Docker: "both GNUCASH_BOOK_PATH and GNUCASH_BOOK_URI are set"

The image ships with GNUCASH_BOOK_PATH pointing at its bundled demo books. To serve a database book from it, clear that default on the command line (-e GNUCASH_BOOK_PATH=) beside your GNUCASH_BOOK_URI; to serve a mounted file, set GNUCASH_BOOK_PATH to the mounted path and run the container as the user who owns the file (--user "$(id -u):$(id -g)").

"Account not found"

• Use full account paths: Expenses:Groceries, not just Groceries.
• 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 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.

Something went wrong

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

---

Support the project

If gnucash-mcp is useful to you, consider buying me a coffee. It helps keep development going.

---

For developers

Contributor guide and design notes live in CLAUDE.md. Quick orientation:

uv sync --extra dev
uv run pytest                       # 3,300+ tests as of v1.5.0, parallel by default
uv run ruff check src/ tests/
uv run black --check src/ tests/

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.

License

MIT.

Acknowledgments

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