gnucash-mcp
MCP server enabling AI assistants to read and write GnuCash accounting data
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ninetails-io--gnucash-mcp)HTML
<a href="/listings/ninetails-io--gnucash-mcp"><img src="/api/listings/ninetails-io--gnucash-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
The one-click way (Claude Desktop)
Download **`gnucash-mcp.mcpb`** from the [latest release](https://github.com/ninetails-io/gnucash-mcp/releases/latest) 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](#one-time-conversion-gnucash-file-format) 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](#4-try-it) 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](#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](#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.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 690 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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](docs/UPGRADING.md)
- before your first write with 1.5.
- **Install in one click:** on Claude Desktop, download the
- `.mcpb` bundle from the
- [latest release](https://github.com/ninetails-io/gnucash-mcp/releases/latest),
- 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](docs/CLIENTS.md). 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](samples/README.md). 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](https://www.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](samples/README.md).
- 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](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](https://github.com/ninetails-io/gnucash-mcp/releases/latest)
- 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](#one-time-conversion-gnucash-file-format)
- 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](#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](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:
- ```bash
- 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](docs/CLIENTS.md#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:
- ```json
- {
- "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](docs/CLIENTS.md)):
- ```bash
- 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`](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:
- ```json
- "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](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](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](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](#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](#or-keep-the-book-in-postgresql-or-mysql).
- PostgreSQL support was contributed by
- [@vchatela](https://github.com/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](docs/UPGRADING.md) 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](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](docs/RESTORE_FROM_BACKUP.md)
- walks through it.
- ---
- ## Support the project
- If gnucash-mcp is useful to you, consider
- [buying me a coffee](https://ko-fi.com/gomezfox). It helps
- keep development going.
- ---
- ## For developers
- Contributor guide and design notes live in
- [CLAUDE.md](CLAUDE.md). Quick orientation:
- ```bash
- 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](https://github.com/sdementen/piecash) (Python
- interface to GnuCash's SQLite books) and the
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).
- Roughly 18,000 lines of Python source, 20,000 lines of tests,
- modularized so disabled modules cost nothing at runtime.
- ## License
- [MIT](LICENSE).
- ## Acknowledgments
- - [GnuCash](https://www.gnucash.org/) — the free, open-source
- accounting software this server makes conversational.
- - [piecash](https://github.com/sdementen/piecash) — Python
- interface to GnuCash SQLite books.
- - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) —
- the Model Context Protocol implementation.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.