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.

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

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: 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 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 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 + 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/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 business

A 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 chart

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

Quick Start

The one-click way (Claude Desktop)

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:

• 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. Skip ahead to step 4 to take it for a spin.

The manual way (any MCP client, or development)

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.

1. Download and install

git clone https://github.com/ninetails-io/gnucash-mcp.git
uv tool install -e ./gnucash-mcp

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

2. Make a working copy of a sample book

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:

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 yourname in both paths:

{
  "mcpServers": {
    "gnucash": {
      "command": "/Users/yourname/.local/bin/gnucash-mcp",
      "args": ["--modules=all"],
      "env": {
        "GNUCASH_BOOK_PATH": "/Users/yourname/gnucash-mcp-scratch/alex.gnucash"
      }
    }
  }
}

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.

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

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.