Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ninetails-io--gnucash-mcp/badge.svg)](/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

i

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.

  1. # gnucash-mcp
  2. **Free, open-source accounting software that works with the LLM.**
  3. Talk to your GnuCash books through Claude (or any AI assistant
  4. that supports MCP). Ask "how am I doing this month," dictate
  5. your transactions out loud, hand over the books for the AI to
  6. keep up while you focus on running your life or your business.
  7. The server runs on your machine and works on your local GnuCash
  8. file; the file and its audit log never leave it. Your AI
  9. assistant sees what its tool calls return (balances, payees,
  10. invoices), just as you would on screen.
  11. **Upgrading from 1.4?** Read [the upgrade guide](docs/UPGRADING.md)
  12. before your first write with 1.5.
  13. **Install in one click:** on Claude Desktop, download the
  14. `.mcpb` bundle from the
  15. [latest release](https://github.com/ninetails-io/gnucash-mcp/releases/latest),
  16. double-click it, and you're running — no terminal, no config
  17. files. Every other MCP client — ChatGPT/Codex, Gemini,
  18. Antigravity, and the rest — connects with
  19. [a few lines of setup](docs/CLIENTS.md). Either way, the AI
  20. subscription you already pay for becomes a bookkeeper that never
  21. sends a bill.
  22. Three realistic sample books let you try it before you commit
  23. anything: full years of activity, mixed currencies, customers,
  24. invoices, and budgets. The Claude Desktop bundle includes them;
  25. from a clone, [one command builds them](samples/README.md). Walk
  26. through one in five minutes; if it clicks, point the server at
  27. your own book and you're done.
  28. ---
  29. ## What does it look like?
  30. This is what your AI assistant sees when it opens one of the
  31. sample books — a complete financial dashboard in a single call:
  32. ```
  33. Book: alex-chen-morales.gnucash
  34. Currency: USD
  35. Data range: 2025-01-01 to 2026-10-08
  36. Last entry: 2026-10-08 (today)
  37. Chart of accounts: 111 total (109 active) — drill into any branch with list_accounts(root="Assets:Investments"):
  38. Assets (25 total): Investments (9), Current Assets (5), Fixed Assets (3), Receivables (3), Retirement (3)
  39. Liabilities (8 total): Credit Card (3), Loans (3)
  40. Equity (3 total)
  41. Income (11 total): Investment Income (6)
  42. Expenses (64 total): Business (14), Taxes (10), Utilities (6), Auto (4), Housing (4), Interest (4), Insurance (3), Pet (3)
  43. Assets: USD 874270.54
  44. Condo: USD 475000.00
  45. VTSAX: 453.4039 VTSAX @ 185.53 (USD 84120.03)
  46. UWRP 403(b): USD 74778.40
  47. Savings Account: USD 60000.00
  48. Cascade Code LLC Checking: USD 41390.64
  49. ...
  50. Liabilities: USD 389695.79
  51. Credit cards (2): USD 1319.99
  52. Loans & other (2): USD 385873.30
  53. Top 3: Mortgage USD 373846.80, Auto Loan USD 12026.50, Chase Sapphire USD 876.31
  54. Receivables: 2 accounts, USD 27324.47 (4 invoices, 0 overdue; included in Assets total)
  55. Accounts Receivable: USD 22425.00
  56. Accounts Receivable EUR: USD 4899.47
  57. Payables: 1 account, USD 2502.50 (1 bill, 0 overdue; included in Liabilities total)
  58. Accounts Payable: USD 2502.50
  59. Jobs: 3 active
  60. 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):
  61. %528b7d9 Assets:Current Assets:Checking Account [BANK]
  62. %8799a0a Liabilities:Credit Card:Chase Sapphire [CREDIT]
  63. %839fcf8 Expenses:Dining
  64. ...
  65. Reconciliation:
  66. 6 accounts current
  67. Net worth trajectory:
  68. 12mo ago: USD 345,969
  69. 6mo ago: USD 381,961
  70. 3mo ago: USD 429,392
  71. 1mo ago: USD 443,546
  72. now: USD 484,575
  73. Monthly net (income - expenses, last 6 months):
  74. Oct 2026 (MTD): +11,955 (vs Sep 1-8: -2,365)
  75. Sep 2026: +25,894
  76. Aug 2026: +7,588
  77. Jul 2026: +10,307
  78. Jun 2026: +24,092
  79. May 2026: +9,017
  80. Runway: 579 days (USD 246,844 liquid / USD 426/day cash out incl. debt paydown, 180-day avg; cards owe USD 1,320)
  81. Budget (2026 Annual Budget): USD 27,736 spent / USD 28,683 expected by today (-3%)
  82. Transactions: 2227
  83. Scheduled: 20 recurring, 16 due in next 7 days (USD 15,128 out)
  84. Business: 8 customers, 3 vendors
  85. Budgets: 2
  86. Commodities: AAPL, CAD, ETH, EUR, MSFT, USD, VBTLX, VTSAX
  87. ```
  88. That's not a screenshot — that's the AI's actual orientation
  89. view. Net worth trajectory, runway, budget pacing, who owes you
  90. money, what's overdue, what hasn't been reconciled. One call,
  91. and your assistant has the full picture before you've even
  92. finished saying hello.
  93. ---
  94. ## Who is this for?
  95. - **Personal finance people** who keep their books in GnuCash
  96. and want to dictate transactions, ask their assistant where
  97. the money's going, get reconciliation help, plan budgets.
  98. - **Small business owners** who run their books in GnuCash and
  99. want to issue invoices, track receivables, see vendor
  100. spending, manage cash flow without leaving the conversation.
  101. - **People who care that their data stays local.** No cloud
  102. sync. No SaaS. Your `.gnucash` file is the system of record;
  103. this just gives your AI a way to read and write it the way
  104. GnuCash itself does.
  105. You don't need to be a developer. You need:
  106. - A computer (Mac, Windows, or Linux)
  107. - GnuCash itself, or willingness to install it (free at
  108. [gnucash.org](https://www.gnucash.org/))
  109. - An AI assistant that supports MCP (Claude Desktop is the
  110. most common; Claude Code, Continue.dev, and others work too)
  111. - 10 minutes to get the sample books running, then another 10
  112. to point at your own
  113. ---
  114. ## Try it without risking anything
  115. The repo ships three sample personas — synthetic ledgers you can
  116. talk to without touching your real data. The bundle carries them
  117. fully built; from a clone, [one command builds them](samples/README.md).
  118. Pick one, point the server at it, and start asking questions.
  119. ### `samples/alex-chen-morales.gnucash` — Personal + freelance
  120. A Seattle-based independent software contractor with a
  121. single-member LLC and a spouse on a hospital payroll. USD-default.
  122. 111 accounts and over 2,000 transactions from 2025 to the build
  123. date. Has a mortgage, a brokerage with VTSAX/VBTLX/AAPL/MSFT/ETH
  124. holdings, a Solo 401(k) beside the spouse's 403(b), eight
  125. customers invoiced in USD, EUR and CAD, a subcontractor billed
  126. through A/P, Washington B&O tax, scheduled bills, budgets —
  127. pretty much everything the server can do, all in one book.
  128. ### `samples/lin-wei.gnucash` — Shenzhen software studio
  129. A Shenzhen developer running a registered sole-proprietor studio
  130. that builds cross-border e-commerce software, with a spouse on a
  131. hospital payroll. CNY-default, on a native zh_CN chart. 101
  132. accounts and about 3,000 transactions. Shenzhen tech clients
  133. (Tencent, DJI, SF Tech and others) paying in CNY, USD/EUR clients
  134. paying in foreign currency with
  135. realized FX gain/loss on rate moves, domestic Chinese investments
  136. (宁德时代 and two ETFs), a part-time employee, an HKD credit card,
  137. a mortgage, and mixed payment rails (corporate account + Alipay +
  138. WeChat Pay).
  139. ### `samples/sabine-brenner.gnucash` — German freelancer, SKR03 chart
  140. A Munich-based freelance designer. EUR-default, on a German
  141. SKR03 chart of accounts — every account name in German. 125
  142. accounts and about 1,900 transactions, with live VAT returns and a
  143. company car under the 1% rule. If a feature assumes English
  144. account names or USD, Sabine's book is where it breaks.
  145. All three books are fictional. See
  146. [samples/README.md](samples/README.md) for the full breakdown of
  147. what's in each.
  148. ---
  149. ## Quick Start
  150. ### Install in one click (Claude Desktop)
  151. Download the **`.mcpb` bundle** from the
  152. [latest release](https://github.com/ninetails-io/gnucash-mcp/releases/latest)
  153. and double-click it. Claude Desktop installs the server — no
  154. terminal, no config file, no Python. The installer asks three
  155. things:
  156. - **Your GnuCash book(s)** — a file picker. Books must be in
  157. SQLite format; if yours is the older XML format, do the
  158. [one-time conversion](#one-time-conversion-gnucash-file-format)
  159. first. Pick several books to switch between them in-chat.
  160. - **Demo books** — one checkbox serves the three sample books
  161. described above, so you can explore on fictional money before
  162. (or instead of) connecting your own.
  163. - **"Do you invoice clients?"** — yes adds the business suite
  164. (customer invoices, vendor bills, employee expenses).
  165. Everything else — budgets, scheduled transactions, investment
  166. tracking — is always on.
  167. That's the entire install.
  168. ### Try it
  169. Ask Claude:
  170. - "Summarize the book."
  171. - "What's my net worth been doing?"
  172. - "Show me anyone who owes me money."
  173. - "What did I spend on dining last month?"
  174. - "Set a $500 monthly grocery budget."
  175. The first response usually starts with the dashboard from
  176. above. Everything after that is conversational.
  177. When you're ready for your own book, see
  178. [Connecting to your own book](#connecting-to-your-own-book) below.
  179. ### Other AI clients, or installing from source
  180. ChatGPT and Codex, Claude Code, Gemini CLI, Google Antigravity,
  181. and any other MCP client connect through an install from a git
  182. clone, as do database books and anyone working on the server:
  183. see [docs/CLIENTS.md](docs/CLIENTS.md).
  184. ---
  185. ## Connecting to your own book
  186. ### One-time conversion: GnuCash file format
  187. The server only reads the **SQLite** form of GnuCash files, not
  188. the older XML form. To convert:
  189. 1. Open your book in GnuCash itself
  190. 2. **File → Save As**
  191. 3. Change "Data Format" to **SQLite3**
  192. 4. Save with a new filename (e.g. `mybook-sqlite.gnucash`)
  193. 5. **Keep the XML original as a backup.**
  194. **On Linux (Debian/Ubuntu),** SQLite3 may be missing from the
  195. "Data Format" drop-down entirely — GnuCash needs a backend driver
  196. that isn't installed by default. Close GnuCash, install it, then
  197. reopen and the option appears:
  198. ```bash
  199. sudo apt update && sudo apt install libdbd-sqlite3
  200. ```
  201. You only do this once. From then on, GnuCash and the MCP server
  202. both work against the same SQLite file.
  203. **GnuCash 3.8 or newer.** Once the server has written to a book, the
  204. book carries a feature marker ("Use natural signs in budget
  205. amounts") that GnuCash 3.8 introduced, and GnuCash 3.0–3.7 refuses
  206. to open a book marked with a feature it does not know. GnuCash 3.8
  207. and later mark any book with a budget the same way when they open
  208. it, so this only matters if you still run an older 3.x. The server
  209. is tested against GnuCash 5.12.
  210. ### Point the server at it
  211. With the bundle, choose the book in the GnuCash extension's settings
  212. in Claude Desktop, then restart Claude Desktop. With a clone install,
  213. set `GNUCASH_BOOK_PATH` to the book's absolute path; see
  214. [Using your own book](docs/CLIENTS.md#using-your-own-book).
  215. ### Or: keep the book in PostgreSQL or MySQL
  216. GnuCash can also keep a book in a database instead of a file, and
  217. the server serves one of those too. Point it at a connection
  218. string instead of a path:
  219. ```json
  220. {
  221. "command": "/Users/yourname/.local/bin/gnucash-mcp",
  222. "args": ["--modules=all"],
  223. "env": {
  224. "GNUCASH_BOOK_URI": "postgresql://user:password@localhost:5432/gnucash",
  225. "GNUCASH_LOG_DIR": "/Users/yourname/gnucash-mcp-logs"
  226. }
  227. }
  228. ```
  229. Install the driver alongside the server — `postgres` or `mysql`
  230. (MariaDB uses the same one). From inside your clone (the
  231. `gnucash-mcp` folder; see [installing from source](docs/CLIENTS.md)):
  232. ```bash
  233. uv tool install -e ".[postgres]" --reinstall
  234. ```
  235. For MySQL / MariaDB the connection string is
  236. `mysql+pymysql://user:password@localhost:3306/gnucash` and the extra
  237. is `[mysql]`: `uv tool install -e ".[mysql]" --reinstall`. The
  238. shorter forms GnuCash itself writes, `mysql://` and `postgres://`,
  239. work too; the server uses the driver the extra installed.
  240. Install from the clone, as above, not by name: the name `gnucash-mcp`
  241. on PyPI belongs to a different project.
  242. To move an existing book across: open it in GnuCash,
  243. **File → Save As**, pick **postgres** or **mysql**, and fill in the
  244. connection details. (On Debian/Ubuntu those entries need `sudo apt
  245. install libdbd-pgsql` or `libdbd-mysql`, the same way SQLite3 needs
  246. `libdbd-sqlite3`; the macOS and Windows builds ship all three.)
  247. **Keep the file** — it stays a perfectly good backup of everything
  248. up to the moment you switched.
  249. Worth knowing before you switch:
  250. - **`GNUCASH_BOOK_PATH` and `GNUCASH_BOOK_URI` are mutually
  251. exclusive** — a book is a file or a database, and setting both
  252. is a startup error rather than a coin toss over which ledger
  253. your writes land in.
  254. - **`GNUCASH_LOG_DIR` becomes required.** Audit and debug logs
  255. normally live in a folder beside the book file; a connection
  256. string has no "beside".
  257. - **One book per server.** `switch_book` matches on filenames, so
  258. multi-book stays a file feature.
  259. - **The server stops taking backups.** This is the real trade-off:
  260. the automatic safety net exists because it can snapshot a file,
  261. and it can't snapshot your database. `create_backup` says so
  262. rather than pretending. Set up `pg_dump` or `mysqldump` on a
  263. schedule before you move a real book over — see
  264. [`docs/RESTORE_FROM_BACKUP.md`](docs/RESTORE_FROM_BACKUP.md).
  265. - Your password is masked wherever the server names the book — in
  266. tool results, in the dashboard header, and in the audit log — and
  267. in every error message, log line, and startup error, including
  268. the ones a database driver writes. A password given as a query
  269. parameter (`?password=…`, `sslpassword=…`) is masked the same
  270. way.
  271. - **Put the connection string in the `env` block, not on the
  272. command line.** `--book-uri` works, but a password in a command
  273. line is visible to every user of the machine in the process
  274. list. On PostgreSQL you can also leave the password out of the
  275. string entirely and let the driver read `PGPASSWORD` or
  276. `~/.pgpass`.
  277. Both dialects are exercised by the test suite and CI: PostgreSQL
  278. 16 and MariaDB 11, each against a real server.
  279. ---
  280. ## Choosing a module set
  281. `--modules=all` is the easy default — every tool, 86 of them.
  282. For day-to-day use you'll probably want less. Pick the role that
  283. matches how you'll talk to the server; you can also pick the
  284. modules behind each role individually for a finer cut.
  285. | Role | What it gives you | Tools |
  286. |---|---|---|
  287. | `core` | Ledger primitives — accounts, transactions, balances, slots, audit log, backups, balance sheet, **reconciliation**. **Always loaded.** | 29 |
  288. | `bookkeeper` | Everything except business: reports, budgets, scheduled transactions, prices, and investment lots. The personal-finance set. | 30 |
  289. | `investor` | Cost-basis tracking and price management only (a subset of `bookkeeper`). | 13 |
  290. | `business` | Customers, vendors, and employees; invoices, bills, vouchers, and credit notes; sales tax, payment terms, jobs, and vendor reports. | 27 |
  291. Pick one or more, comma-separated:
  292. ```json
  293. "args": ["--modules=bookkeeper"] // personal finance
  294. "args": ["--modules=investor"] // self-directed investor
  295. "args": ["--modules=business"] // invoicing, freelance or small business
  296. "args": ["--modules=bookkeeper,business"] // everything (same as all)
  297. ```
  298. `core` is added regardless. `freelancer` and `business_complete`,
  299. the names 1.4 used, are still accepted and mean `business`. The
  300. modules behind each role (`reconciliation`, `reporting`,
  301. `budgets`, `scheduling`, `tax_lots`, `portfolio`, etc.) are
  302. individually selectable too — run `uv run gnucash-mcp --help` from
  303. the repo for the full menu.
  304. ---
  305. ## What you can ask it to do
  306. A non-exhaustive tour. Phrase any of these naturally — the
  307. assistant translates.
  308. ### Entering a whole statement
  309. > "Here's my August checking statement." *(attach the PDF)*
  310. >
  311. > Rehearsed 31 lines against your book: 24 new, 6 already
  312. > entered (claimed), 1 needs a look — here's the comparison.
  313. > Confirm and I'll land the month: entered, categorized, and
  314. > reconciled to the closing balance in one step.
  315. One statement, two calls, a tied book. The dry-run classifies
  316. every line with evidence before anything is written, and the
  317. commit refuses wholesale rather than land a month that doesn't
  318. tie.
  319. ### Recording activity
  320. > "I spent \$47.50 at Safeway today on groceries, paid with my
  321. > Visa."
  322. >
  323. > Recorded: \$47.50 from Credit Card:Visa to
  324. > Expenses:Groceries on Apr 30, 2026. Description: "Safeway".
  325. ### Setting up recurring bills
  326. > "Set up my rent as a recurring bill. \$1,850 on the 1st of
  327. > every month from checking."
  328. >
  329. > Created scheduled transaction "Monthly Rent": \$1,850
  330. > monthly, from Assets:Checking to Expenses:Rent. Next due:
  331. > May 1, 2026.
  332. ### Investment tracking
  333. > "I bought \$1,000 of VTSAX at \$170.99/share in my 401(k)."
  334. >
  335. > Recorded VTSAX purchase: 5.85 shares at \$170.99/share. Cost
  336. > basis: \$1,000.00. Lot created for capital-gains tracking
  337. > when you eventually sell.
  338. ### Invoicing customers
  339. > "Create a customer called Acme Corp and invoice them \$1,500
  340. > for consulting."
  341. >
  342. > Created customer Acme Corp (id 000005) and invoice 000019:
  343. > 1× Consulting at \$1,500.00 = \$1,500.00. Open. Tell me when
  344. > you're ready to post it.
  345. If you open a server-posted invoice in GnuCash's Process Payment
  346. dialog, set its "Post To" account to the invoice's receivable first:
  347. the dialog lists only the documents posted to the selected account.
  348. ### Foreign-currency invoicing
  349. > "Invoice Berlin Digital €4,200 for Q1 retainer, due in 30 days."
  350. >
  351. > Created EUR invoice 000020 for Berlin Digital GmbH:
  352. > 1× Q1 Retainer at EUR 4,200 = EUR 4,200. Net 30. When they
  353. > pay, I'll book the realized exchange-rate gain/loss to your
  354. > FX account automatically.
  355. ### Asking questions
  356. > "How much did I spend with each vendor this year?"
  357. >
  358. > Office Depot: \$2,340 (4 bills, \$0 outstanding)
  359. > CloudHost Inc: \$1,200 (2 bills, \$600 outstanding)
  360. > Legal Associates: \$3,500 (1 bill, \$3,500 outstanding)
  361. > Total billed \$7,040 / paid \$2,940 / outstanding \$4,100.
  362. ### Reconciliation
  363. > "Help me reconcile checking against the April statement."
  364. >
  365. > [Walks you through it: pulls unreconciled splits, asks you
  366. > to confirm cleared transactions, computes the running
  367. > balance, marks the matched ones reconciled, leaves the
  368. > mismatches for you to investigate.]
  369. ---
  370. ## Privacy and safety
  371. **Your book file never leaves your machine.** This server is a
  372. local process that reads and writes a local file. The AI
  373. assistant you're talking to (Claude Desktop, etc.) sees the
  374. results of your tool calls — the same content you'd see on
  375. screen — but the file itself stays where it always was.
  376. **Every write is logged.** A human-readable audit trail lives
  377. alongside your book file at `<your-book>.gnucash.mcp/audit/`,
  378. one log file per day. You can read it at any time to see
  379. exactly what changed and when. Sample entry:
  380. ```
  381. 2026-04-30 14:32 POST INVOICE id:000019
  382. total: 1500.00 date: 2026-04-30
  383. account: Assets:Accounts Receivable txn:a1b2c3d4
  384. ```
  385. **Automatic backups.** Before the first write of each session
  386. (and again as a long-running session crosses into a new backup
  387. period), the server snapshots your book to
  388. `<your-book>.gnucash.mcp/backups/` — so if something goes
  389. wrong, you can roll back to a known-good state without
  390. relying on Time Machine or your own habit. Backups are
  391. verified with `PRAGMA integrity_check` before being declared
  392. valid, and skipped when the book hasn't changed since the
  393. last snapshot. See [docs/RESTORE_FROM_BACKUP.md](docs/RESTORE_FROM_BACKUP.md)
  394. for the rollback procedure.
  395. > **Reading timestamps:** backup *filenames* carry UTC
  396. > timestamps (filesystem-safe and unambiguous across travel
  397. > and DST); audit and debug logs use *local-dated* daily
  398. > files, matching how you'd search for "what happened
  399. > Tuesday." Near midnight these can differ by a day — keep
  400. > that in mind when matching a backup to a day's log.
  401. **Reconciled splits are protected.** The server refuses to
  402. delete or modify reconciled splits without an explicit
  403. override, so a careless prompt can't quietly invalidate your
  404. last bank reconciliation.
  405. **Voiding ≠ deleting.** When you tell the AI to "void this
  406. transaction," it uses GnuCash's proper accounting void —
  407. preserving the transaction for the audit trail with values
  408. zeroed. Deletion is the destructive option; the AI will tell
  409. you which one it's doing.
  410. > **Disclaimer:** This software is provided "as is" under the
  411. > [MIT License](LICENSE), without warranty of any kind. The
  412. > authors are not liable for any data loss, corruption, or
  413. > financial discrepancy arising from its use. You are solely
  414. > responsible for maintaining your own backups and verifying
  415. > the accuracy of your books.
  416. ---
  417. ## Known limitations
  418. - **Don't edit in GnuCash desktop and through the server at the
  419. same time.** The server respects GnuCash's lock but doesn't hold
  420. one of its own (it opens the book for one call at a time), so
  421. GnuCash won't warn you that the server is using the book.
  422. - **Books with "Use Trading Accounts" turned on:** transactions
  423. across currencies or commodities, including stock and fund
  424. purchases, are refused, because the server can't yet write
  425. trading splits the way GnuCash does. Enter those in GnuCash
  426. desktop; everything in a single currency works as usual.
  427. - **GnuCash 3.8 or newer.** A book the server has written to
  428. carries a feature marker that GnuCash 3.0–3.7 can't open.
  429. - **Foreign-currency spending and income** are valued at each
  430. month's closing rate in the spending and income reports, not at
  431. the cash that paid for them; `cash_flow` reports the cash.
  432. The full list is in [CHANGELOG.md](CHANGELOG.md).
  433. ---
  434. ## Limiting what the AI can see
  435. Each tool's description lives in the AI's system prompt, which
  436. costs context on every message. Narrowing the toolset to what
  437. you actually use makes every conversation cheaper. See
  438. [choosing a module set](#choosing-a-module-set) above for the
  439. four roles (`core`, `bookkeeper`, `investor`, `business`).
  440. You can also set `GNUCASH_MCP_MODULES=core,bookkeeper` as an
  441. environment variable instead of `--modules=...` in the JSON
  442. args.
  443. ---
  444. ## What's new in v1.5.0
  445. - **Books in a database.** Point the server at a book GnuCash keeps
  446. in PostgreSQL or MySQL/MariaDB, not just a SQLite file — see
  447. [Or: keep the book in PostgreSQL or MySQL](#or-keep-the-book-in-postgresql-or-mysql).
  448. PostgreSQL support was contributed by
  449. [@vchatela](https://github.com/vchatela).
  450. - **Everything is stored the way GnuCash desktop stores it.**
  451. Scheduled transactions run in desktop's Since Last Run, budgets,
  452. invoices, credit notes, voids, and prices read the same in both,
  453. and invoice totals match GnuCash's own to the cent. Upgrading
  454. from 1.4? Read [the upgrade guide](docs/UPGRADING.md) first.
  455. - **Prepayments.** Record a customer's or vendor's overpayment as
  456. money held for them, settle a later invoice from it, and unpost
  457. a paid invoice without losing the payment.
  458. - **Num and document links** on every transaction tool, with the
  459. number used as a duplicate check.
  460. - **A map of your chart of accounts** on the dashboard, so the
  461. assistant knows where every account lives before it asks.
  462. - **Sample books built from source**, each checked against its own
  463. country's tax practice (US/Washington, Germany, China) and
  464. current to the day they're built.
  465. Earlier releases are in [CHANGELOG.md](CHANGELOG.md).
  466. ---
  467. ## Troubleshooting
  468. ### No 🔨 hammer icon, or "tool not found"
  469. - Quit Claude Desktop completely, then reopen it. (Closing the
  470. window isn't enough — you have to quit the application.)
  471. - Verify the paths in your config are absolute and correct.
  472. - Check the JSON for trailing commas — they break the config
  473. silently.
  474. ### "Book not found"
  475. - Use absolute paths, not `~` or relative paths.
  476. - Mac/Linux: `/Users/yourname/Documents/book.gnucash`
  477. - Windows: `C:\\Users\\yourname\\Documents\\book.gnucash`
  478. (doubled backslashes — JSON requirement)
  479. ### "Cannot open book" / piecash errors
  480. - Confirm your book is in **SQLite** format, not XML.
  481. - Make sure GnuCash isn't open with the same book — file lock.
  482. The server honors GnuCash's lock but deliberately takes none of
  483. its own (it holds the book for one call at a time), so GnuCash
  484. will open a book the server is using without a warning. Don't
  485. edit in both at once.
  486. - Try opening the book in GnuCash itself to verify it isn't
  487. corrupted.
  488. ### Docker: "both GNUCASH_BOOK_PATH and GNUCASH_BOOK_URI are set"
  489. The image ships with `GNUCASH_BOOK_PATH` pointing at its bundled
  490. demo books. To serve a database book from it, clear that default
  491. on the command line (`-e GNUCASH_BOOK_PATH=`) beside your
  492. `GNUCASH_BOOK_URI`; to serve a mounted file, set
  493. `GNUCASH_BOOK_PATH` to the mounted path and run the container as
  494. the user who owns the file (`--user "$(id -u):$(id -g)"`).
  495. ### "Account not found"
  496. - Use full account paths: `Expenses:Groceries`, not just
  497. `Groceries`.
  498. - Or ask the assistant to list accounts: "List my accounts."
  499. ### Multiple server processes after a client restart
  500. Claude Desktop (and some other MCP clients) may briefly spawn
  501. two or three copies of the server when relaunching. This is
  502. client behavior, not a server bug, and it's mostly harmless:
  503. the server opens your book per-request and releases the file
  504. lock between calls, so overlapping processes contend only for
  505. moments. If you see persistent `Lock on the file` errors after
  506. a client restart, quit the client fully, confirm with
  507. `pgrep -fl gnucash-mcp` that no strays remain, and relaunch.
  508. ### Something went wrong
  509. - Open the audit log at `<your-book>.gnucash.mcp/audit/` —
  510. every write since the server first ran is there with
  511. before/after detail.
  512. - If you need to roll back, [docs/RESTORE_FROM_BACKUP.md](docs/RESTORE_FROM_BACKUP.md)
  513. walks through it.
  514. ---
  515. ## Support the project
  516. If gnucash-mcp is useful to you, consider
  517. [buying me a coffee](https://ko-fi.com/gomezfox). It helps
  518. keep development going.
  519. ---
  520. ## For developers
  521. Contributor guide and design notes live in
  522. [CLAUDE.md](CLAUDE.md). Quick orientation:
  523. ```bash
  524. uv sync --extra dev
  525. uv run pytest # 3,300+ tests as of v1.5.0, parallel by default
  526. uv run ruff check src/ tests/
  527. uv run black --check src/ tests/
  528. ```
  529. The installed `gnucash-mcp` command tracks your clone live: it
  530. serves whatever branch the checkout is on, so switching branches
  531. switches the served code at the next restart — handy for testing,
  532. worth remembering when you forget you're mid-branch. To run a
  533. DIFFERENT checkout (a second worktree) without touching the
  534. install, `uv run --directory PATH gnucash-mcp` still runs any
  535. directory you point it at.
  536. The server is built on
  537. [piecash](https://github.com/sdementen/piecash) (Python
  538. interface to GnuCash's SQLite books) and the
  539. [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).
  540. Roughly 18,000 lines of Python source, 20,000 lines of tests,
  541. modularized so disabled modules cost nothing at runtime.
  542. ## License
  543. [MIT](LICENSE).
  544. ## Acknowledgments
  545. - [GnuCash](https://www.gnucash.org/) — the free, open-source
  546. accounting software this server makes conversational.
  547. - [piecash](https://github.com/sdementen/piecash) — Python
  548. interface to GnuCash SQLite books.
  549. - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) —
  550. the Model Context Protocol implementation.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.