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