gnucash-mcp
This MCP server lets you read, manage, and write GnuCash accounting data conversationally — book summaries, transactions, accounts, invoices, budgets, reconciliation, investment tracking, and more, all against your local SQLite book.
Orientation & exploration: get the book summary, server config, account lists and details, balances, transactions, commodities, budgets, and switch between multiple books.
Transaction entry & editing: create single or bulk (TSV) transactions, search, update (including broadcast updates), delete, replace splits, void/unvoid, with duplicate detection and dry-run previews.
Account management: create, update, move, and delete accounts, plus custom account metadata slots.
Reconciliation: view unreconciled splits, reconcile targeted splits or an entire statement in one call, and check per-account reconciliation status.
Budgets: create budgets, set per-account amounts, generate budget-vs-actual reports, and delete budgets.
Business documents: manage customers, vendors, employees, jobs, billing terms, tax tables, invoices, bills, vouchers, and credit notes — add line items, post, pay (with early-payment discounts and FX gain/loss handling), unpost, and delete.
Investment tracking: create and list commodities, record prices (individually or in bulk), manage lots, assign splits to lots, and calculate capital gains.
Reporting: spending by category, vendor spending reports, outstanding invoices, job reports, and net-worth/dashboard summaries.
Safety & audit: audit log reading, on-demand and automatic backups, backup pruning, and protections around reconciled splits and posting records.
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, VTSAXThat'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.
Related MCP server: ZenMoney MCP
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
.gnucashfile 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:
Open your book in GnuCash itself
File → Save As
Change "Data Format" to SQLite3
Save with a new filename (e.g.
mybook-sqlite.gnucash)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-sqlite3You 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]" --reinstallFor 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_PATHandGNUCASH_BOOK_URIare 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_DIRbecomes 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_bookmatches 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_backupsays so rather than pretending. Set uppg_dumpormysqldumpon a schedule before you move a real book over — seedocs/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
envblock, not on the command line.--book-uriworks, 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 readPGPASSWORDor~/.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 |
| Ledger primitives — accounts, transactions, balances, slots, audit log, backups, balance sheet, reconciliation. Always loaded. | 29 |
| Everything except business: reports, budgets, scheduled transactions, prices, and investment lots. The personal-finance set. | 30 |
| Cost-basis tracking and price management only (a subset of | 13 |
| 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:a1b2c3d4Automatic 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_flowreports 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.gnucashWindows:
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 justGroceries.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.
Available Tools
87 toolsadd_document_entryA
Add a line item to a customer invoice, vendor bill, employee voucher, or credit note.
Only unposted documents accept entries — unpost_document first to amend a posted one. Amounts are decimal strings; the line total is quantity × price (plus tax when a taxtable is attached).
Args: document_type: "invoice", "bill", "voucher", or "credit_note". id: Document ID (e.g., "000001"). account: Income account for invoices / credit notes; expense account for bills and vouchers. Full path, %short GUID, or full GUID. description: Line item description. quantity: Quantity as a decimal string (e.g., "3"). price: Unit price as a decimal string (e.g., "125.00"). party_type: Credit notes only — disambiguates when a customer and vendor credit note share an ID. taxtable: Tax table name to apply. Optional. tax_included: Whether price already includes tax. notes: Optional entry notes. action: Optional entry action label (e.g., "Hours").
Inputs: id (required), price (required), account (required), quantity (required), +7 more. Returns: result
apply_credit_noteA
Net a posted credit note against a posted invoice or bill from the same owner. No cash moves — the credit balance transfers between lots on the same A/R or A/P account.
This is the most common credit-note settlement path: the
bookkeeper issues a credit note against an overcharge,
then nets it against the next invoice from that customer
(or applies it to an outstanding bill on the vendor side).
Use pay_document instead when the credit note will be
settled by sending or receiving cash.
Args:
credit_note_id: The credit note to apply (must be
posted).
applies_to_invoice_id: The target invoice/bill (must
be posted, same owner, same currency, same A/R
or A/P post account). Need not be the document
the credit note was created against — that link
is provenance, and the response notes the
divergence when this target differs from it.
amount: Decimal-string amount to apply, in the
document currency. Defaults to min(credit_note_ remaining, target_remaining) — apply as much
as possible.
apply_date: ISO date for the netting transaction.
Defaults to today.
owner_type: Optional 'customer' or 'vendor'
disambiguator for ID collisions.
Inputs: credit_note_id (required), applies_to_invoice_id (required), amount, apply_date, +1 more. Returns: result
assign_split_to_lotADestructiveIdempotent
Assign a transaction split to a lot.
Use after creating a buy/sell transaction to link the investment account split to its lot for cost basis tracking.
Args: split_guid: GUID of the split (from transaction's investment account). 8+ char prefix accepted. lot_guid: GUID of the lot (or 8+ char prefix).
Workflow: 1. create_lot("Assets:VTSAX", "VTSAX Jan 2026") 2. create_transactions(...one-row batch buying 10 shares, qty column on the investment leg...) 3. assign_split_to_lot(investment_split_guid, lot_guid)
Inputs: lot_guid (required), split_guid (required). Returns: result
balance_sheetARead-only
Generate a balance sheet as of a specific date.
Shows assets, liabilities, and equity with account breakdowns. A = L + E holds by construction; non-zero unrealized P&L appears as a synthetic equity row.
Args:
as_of_date: Date in ISO format (YYYY-MM-DD). Defaults to
today — matching get_book_summary's implicit
cutoff so cross-tool comparisons agree without
threading the same date into both calls. Pass an
explicit date for historical snapshots.
Inputs: as_of_date. Returns: result
calculate_lot_gainARead-only
Calculate potential or actual capital gain for a lot.
If shares and sale_price provided, calculates hypothetical gain. Otherwise uses lot's current state and latest price.
Args: lot_guid: Lot GUID (or 8+ char prefix). shares: Optional number of shares to calculate for. Defaults to all remaining shares. sale_price: Optional sale price per share. Defaults to latest price for the commodity.
Inputs: lot_guid (required), shares, sale_price. Returns: result
cash_flowARead-only
Calculate cash flow (inflows and outflows) for a period.
Scope is BANK and CASH accounts by default. Credit-card and
investment movements are not cash flow (they're liability /
asset changes — use balance_sheet). An explicit account=
of any type works but the default scope is narrow.
Internal transfers (transactions with no INCOME or EXPENSE
leg — transfer to savings, currency wallet shuffle, paying
a credit card from checking) are filtered by default. The
default totals answer "where did money come from and where
did it go?" rather than "every debit and credit." Pass
include_transfers=true for the gross flow (e.g. for
reconciling against a bank statement).
Args: start_date: Start of period (YYYY-MM-DD) end_date: End of period (YYYY-MM-DD) account: Optional specific account to analyze (defaults to all cash/bank accounts) include_transfers: When False (default), filter internal transfers. When True, include every cash/bank movement regardless of category. group_by: Optional "month", "quarter", or "year" — split the range into sub-period columns and return an Inflows / Outflows / Net trend table (TSV).
Inputs: end_date (required), start_date (required), account, group_by, +1 more. Returns: result
close_lotADestructiveIdempotent
Mark a lot as closed.
Use when a lot is fully sold but wasn't automatically marked closed, or to manually close a lot with zero shares.
Args: guid: Lot GUID (or 8+ char prefix).
Note: Lots are automatically marked closed when their quantity reaches zero through assigned splits. This tool is for manual cleanup.
Inputs: guid (required). Returns: result
create_accountA
Create a new account in the chart of accounts.
Args: name: Account name (e.g., "AI Subscriptions"). account_type: One of ASSET, BANK, CASH, CREDIT, EQUITY, EXPENSE, INCOME, LIABILITY, MUTUAL, STOCK, RECEIVABLE, PAYABLE. parent: Parent account ref (full path, %short GUID, or full 32-char GUID). Omit for top-level. description: Optional description. placeholder: Container-only account. Default False. commodity: ISO currency code ("USD") or stock/fund symbol ("VTSAX"). Defaults to book's default currency. commodity_namespace: "CURRENCY" (default), "FUND", or an exchange ("NASDAQ", "NYSE"). Required with non-currency commodities. notes: Optional free-text notes (max 4096 bytes). Shows in GnuCash desktop's account editor Notes field.
Inputs: name (required), account_type (required), notes, parent, +4 more. Returns: result
create_backupARead-only
Create an on-demand backup of the GnuCash book.
Uses SQLite's online backup API so the snapshot is safe even
if the book is being read or written concurrently by GnuCash
desktop. Verifies the copy with PRAGMA integrity_check
before declaring success; a failed check deletes the bad
backup and raises.
Manual backups are kept indefinitely — automatic retention (session / weekly / monthly stages) does not touch them. To review or remove backups, the user works with the files directly in the backup directory; no tool can list or delete them.
The response includes a restore_hint describing the
filesystem command to restore from this backup. Restore is a
human-run filesystem operation, not an MCP tool — see
docs/RESTORE_FROM_BACKUP.md for details.
Args:
label: Optional free-text label (sanitized to
[A-Za-z0-9_-]) appended to the filename for human
context, e.g. "pre-recategorization" or
"pre-tax-filing".
Inputs: label. Returns: result
create_billtermA
Create a new billing term.
Args: name: Billterm name (e.g., "Net 30"). due_days: Number of days until payment is due. Default 30. description: Optional description. discount_days: Days within which early discount applies. discount_percent: Early payment discount percentage (e.g., "2" for 2%).
Inputs: name (required), due_days, description, discount_days, +1 more. Returns: result
create_budgetA
Create a new budget.
Args:
name: Budget name (e.g., "2026 Budget").
year: Budget year. Defaults to current year. Ignored when
start_date is provided.
num_periods: Number of periods. Default 12 (monthly for a year).
period_type: Period length:
- "monthly" (default)
- "quarterly"
- "weekly"
description: Optional description.
start_date: Optional ISO date (YYYY-MM-DD) when the
budget's first period begins. When omitted, falls
back to January 1 of year. Use this to author
a historical budget for comparison against past
actuals (e.g. start_date="2024-01-01") or to
start mid-year.
Inputs: name (required), year, start_date, description, +2 more. Returns: result
create_commodityA
Create a new commodity (stock, mutual fund, etc.).
Args: mnemonic: Symbol (e.g., "VTSAX"). Unique within namespace. fullname: Human-readable name. namespace: "FUND" (default) for mutual funds, "NASDAQ"/"NYSE"/ "AMEX" for stocks, or any custom string. fraction: Smallest fractional unit. 1 = whole units, 100 = 2 decimals, 10000 = 4 decimals (default, shares), 1000000 = 6 decimals (crypto). cusip: Optional CUSIP/ISIN identifier.
Inputs: fullname (required), mnemonic (required), cusip, fraction, +1 more. Returns: result
create_documentA
Create a customer invoice, vendor bill, employee expense voucher, or credit note.
The owner side derives from the document type — invoice →
customer, bill → vendor, voucher → employee. Credit notes
exist on both sides, so they alone require party_type
("customer" or "vendor"). After creating, add line items
with add_document_entry, then post_document to put it on
the books.
Args: document_type: "invoice", "bill", "voucher", or "credit_note". owner_id: The owning party's ID (customer ID for invoices, vendor ID for bills, employee ID for vouchers). ID counters are per type. party_type: Required for credit notes only ("customer" or "vendor" — which side the credit belongs to). Derived from document_type otherwise. date_opened: ISO date. Defaults to today (echoed in the response). notes: Optional notes (max 4096 characters). currency: ISO code. Defaults to the owner's currency, then the book default. term: Billterm name (e.g., "Net 30"). Optional. id: Custom document number; auto-generated when omitted. job_id: Optional Job to group under (invoices and bills; must belong to the same owner). applies_to_id: Credit notes only — the invoice/bill this credit note reverses. The link is PROVENANCE, not a constraint: apply_credit_note can net the credit against any open document from the same owner (its response notes the divergence when the applied target differs from this link).
Inputs: owner_id (required), document_type (required), id, term, +6 more. Returns: result
create_jobA
Create a job for a customer or vendor.
A job groups invoices (or bills) from one counterparty under a project-level container. Useful when a single customer has multiple distinct engagements (e.g., 'API Rewrite' and 'Q3 Maintenance') that should be reported on separately even though invoices flow to the same A/R.
Args: owner_id: Customer or vendor ID (e.g., "000001"). owner_type: "customer" or "vendor". Employees are not supported (no GnuCash desktop UI for employee jobs). name: Human-readable job name (e.g., "API Rewrite"). reference: Optional reference string (PO number, project code).
Inputs: name (required), owner_id (required), owner_type (required), reference. Returns: result
create_lotA
Create a new, empty lot for cost basis tracking.
Additive: the lot starts open with no splits attached, and nothing else in the book changes. A lot groups one purchase with its later sales so cost basis and capital gain compute per purchase. The full flow: create_lot → create_transactions (the buy, a one-row batch) → assign_split_to_lot → calculate_lot_gain; the lot auto-closes when its assigned splits net to zero shares. Errors if the account ref matches nothing. Skip this tool when you only want a valuation — get_book_summary and balance_sheet price holdings without lots.
Args: account: Account ref for the investment account: full path (e.g., "Assets:Investments:VTSAX"), %short GUID, or full 32-char GUID. title: Lot identifier (e.g., "VTSAX 2026-01-15 purchase"). notes: Optional notes.
Inputs: title (required), account (required), notes. Returns: result
create_partyA
Create a customer, vendor, or employee.
Additive: each call creates a fresh party — names are NOT checked for duplicates, so list_parties first when unsure. Returns the assigned ID (e.g., "000001"), the handle every later call wants. ID counters are PER TYPE: customer 000001 and vendor 000001 are different parties, which is why party_type is required everywhere.
Args: party_type: "customer" (pays you), "vendor" (you pay), or "employee" (expense-voucher workflows). name: Party name (e.g., "Acme Corp", "Jane Smith"). currency: ISO currency code (e.g., "USD", "EUR"). Defaults to book's default currency. notes: Optional notes (max 4096 characters). Employees have no notes field — rejected, not ignored. address: Optional address with keys: name, addr1, addr2, addr3, addr4, phone, fax, email. Each sub-field capped at 1024 characters.
Inputs: name (required), party_type (required), notes, address, +1 more. Returns: result
create_priceA
Record a price for a commodity (stock, NAV, exchange rate).
An existing price with the same commodity/currency/date/source is updated rather than duplicated.
Args:
commodity: Symbol (e.g., "VTSAX").
namespace: Commodity namespace (e.g., "FUND", "NASDAQ").
value: Price per unit as decimal string (e.g., "250.45").
currency: ISO currency code. Defaults to the book's default
currency — so create_price(commodity="USD", value="7.30")
on a CNY-default book stores "1 USD = 7.30 CNY" (the
natural reading). Pass explicitly for cross-currency
pairs that don't involve the book default.
date: ISO date (YYYY-MM-DD). Defaults to today.
price_type: "nav" (default, mutual funds), "last", "bid",
"ask", or "unknown".
source: Source identifier. Default "user:price".
Inputs: value (required), commodity (required), namespace (required), date, +3 more. Returns: result
create_pricesA
Record MANY prices in one call (bulk quote entry).
INPUT — prices is a TSV block: a header row, then one row
per price. Required columns ref, commodity, date, value;
optional columns extend the header IN ORDER:
ns, cur, source, type (stop anywhere; rows may end early;
empty cells take defaults)::
ref<TAB>commodity<TAB>date<TAB>value<TAB>cur<TAB>source
1<TAB>VTSAX<TAB>2026-07-21<TAB>148.32<TAB><TAB>web:yahoo
2<TAB>EUR<TAB>2026-07-21<TAB>1.0845<TAB><TAB>web:ecbref: your correlation key, echoed in results.ns: commodity namespace; empty auto-resolves when the symbol is unambiguous across namespaces.cur: quote currency; empty = book default.source: where the quote came from (provenance — default "user:price");type: nav/last/bid/ask.
Per-row semantics are create_price's exactly: an existing
price with the same commodity/currency/date/source is UPDATED
in place (status: updated), never duplicated. One book
open, one save, on_error="abort" (default) sinks the
whole batch on any bad row; dry_run=true previews as
would_create / would_update.
The companion work list: list_commodities(stale_days=30, held_only=true).
Inputs: prices (required), dry_run, on_error. Returns: result
create_scheduled_transactionA
Create a recurring transaction template.
Args:
name: Scheduled transaction name (e.g., "Monthly Rent").
description: Transaction description at instantiation.
splits: List of split dicts, e.g.
[{"account": "Expenses:Rent", "amount": "1850.00"}, ...].
amount / quantity must be decimal strings;
quantity is required when an account's commodity
differs from the template's transaction currency.
start_date: First occurrence (YYYY-MM-DD).
frequency: "weekly", "biweekly" (2w), "monthly",
"bimonthly" (2mo), "quarterly" (3mo), or "yearly".
end_date: Optional last occurrence (YYYY-MM-DD).
enabled: Active. Default True.
notes: Transaction notes applied to every instantiated
transaction (what the payment is — visible in
GnuCash's double-line register view).
currency: ISO code denominating every instantiated
transaction; defaults to the book default. Use when
no leg is in the book currency (a USD-to-USD card
payment scheduled inside a CNY book) so amounts are
the foreign currency's own numbers. Not updatable
after creation — delete and recreate to change it.
Inputs: name (required), splits (required), frequency (required), start_date (required), +5 more. Returns: result
create_taxtableA
Create a new sales-tax table.
A taxtable holds one or more entries. Each entry contributes either a percentage rate or a flat-value surcharge routed to a specific GL account (ASSET for input-tax credit, LIABILITY for output sales tax payable). Multi-entry composites (e.g., GST 5% + PST 7%) produce multiple tax splits per line at posting time.
Args:
name: Taxtable name, unique within the book
(e.g., "CA Sales 7.25%", "BC GST+PST").
entries: List of {type, amount, account} dicts.
type: "value" or "percentage".
amount: positive decimal as string. Percentages
are the rate ("5.00" = 5%, not "0.05").
account: account path, %short-guid, or full GUID.
Must be ASSET or LIABILITY type. All entries on a
single taxtable must reference accounts in the same
commodity.
Example: create_taxtable( name="BC GST+PST", entries=[ {"type": "percentage", "amount": "5.00", "account": "Liabilities:GST Payable"}, {"type": "percentage", "amount": "7.00", "account": "Liabilities:PST Payable"}, ], )
Inputs: name (required), entries (required). Returns: result
create_transaction_from_scheduledA
Create an actual transaction from a scheduled template.
Args: guid: Scheduled transaction GUID (or 8+ char prefix). transaction_date: Date for the transaction. Defaults to next occurrence.
Inputs: guid (required), transaction_date. Returns: result
create_transactionsA
Create transactions in one atomic command (bulk entry) —
the canonical entry tool for one transaction or many. A
single transaction is a one-row batch (the former
create_transaction tool was removed; this replaces it).
INPUT — transactions is a TSV block: a header row, then one
row per transaction. The HEADER DECLARES THE LAYOUT. Base form:
splits are (amount, account) column PAIRS, repeated as wide
as a transaction needs::
ref<TAB>date<TAB>description<TAB>amt1<TAB>acct1<TAB>amt2<TAB>acct2...
1<TAB>2026-05-21<TAB>Gas<TAB>-54.19<TAB>Assets:Checking<TAB>54.19<TAB>Expenses:Auto:FuelTwo opt-in extensions, each activated by naming it in the header (legacy headers parse exactly as before):
PER-SPLIT MEMOS — declare
memosplit columns; splits become(amount, account, memo)TRIPLES::ref<TAB>date<TAB>description<TAB>amt1<TAB>acct1<TAB>memo1<TAB>amt2<TAB>acct2<TAB>memo2 1<TAB>2026-05-21<TAB>Gas<TAB>-54.19<TAB>Assets:Checking<TAB>card #4471<TAB>54.19<TAB>Expenses:Auto:FuelEmpty memo cells mid-row keep their tabs; a row may simply END once its last split's amount and account are present (trailing memo/qty cells are read as empty — no placeholder tabs needed, as above).
PER-TRANSACTION NOTES — declare a
notescolumn directly afterdescription::ref<TAB>date<TAB>description<TAB>notes<TAB>amt1<TAB>acct1...FIELD TARGETING for statement entry:
descriptionis the clean name;notesis what the purchase WAS — interpreted, not transcribed — and is what humans see in GnuCash's double-line register; the bank leg'smemois where the RAW statement line goes (provenance, visible only in expanded split view). Prefer fillingnoteswhenever the description alone doesn't tell the story.PER-TRANSACTION CURRENCY — declare a
curcolumn afterdescription(before or afternotes); an ISO code cell sets THAT ROW's transaction currency, an empty cell keeps the book default::ref<TAB>date<TAB>description<TAB>cur<TAB>amt1<TAB>acct1<TAB>amt2<TAB>acct2 1<TAB>2026-07-15<TAB>USD Card Payment<TAB>USD<TAB>-500<TAB>Assets:USD Checking<TAB>500<TAB>Liabilities:USD CardWith
cur, the row'samtcells are in that currency and must balance in it. Use it when NO leg is in the book's default currency (a USD-to-USD transfer inside a CNY book needs no invented CNY values and no qty). Splits on accounts of any OTHER commodity still needqty. The currency must already exist in the book, andcurcannot combine with an auto-fill row.PER-SPLIT QUANTITY — declare
qtysplit columns for splits whose ACCOUNT commodity differs from the book default (investment shares, foreign-currency accounts)::ref<TAB>date<TAB>description<TAB>amt1<TAB>acct1<TAB>qty1<TAB>amt2<TAB>acct2<TAB>qty2 1<TAB>2026-07-01<TAB>VFIFX Purchase<TAB>-505.17<TAB>Assets:Checking<TAB><TAB>505.17<TAB>Assets:401k:VFIFX<TAB>7.7936amountstays in the book's default currency (the transaction currency — batch never changes that);qtyis the amount in the account's own commodity. An EMPTY qty cell means the account uses the default currency (quantity == amount). A non-default-commodity account with an empty qty rejects that row.PER-SPLIT ACTION — declare
actsplit columns for GnuCash's typed movement tag ("Buy"/"Sell"/"Dividend" on investment legs — desktop convention; "Wire"/"ATM" on bank legs). Same group mechanics asmemo/qty; empty cells skip it. Rarely needed for plain spending.
All extensions combine; when several split fields are
declared, the header's FIRST group fixes their order (e.g.
amt, acct, memo, qty).
AUTO-FILL — a row with NO split cells at all (ends right
after description/notes) reproduces the most recent
transaction with the same description — splits, memos, and
quantities included::
1<TAB>2026-07-01<TAB>Rent
2<TAB>2026-07-01<TAB>NetflixAuto-filled rows are marked auto_filled_from:<guid> in
the results reason column; a row whose description
matches nothing rejects ("no matching transaction to
auto-fill from"). Use dry_run=true to preview what a
batch of auto-fills would book. Perfect for recurring
monthly entries. Transaction notes are NOT copied from
the source (notes are often time-bound — "first
appearance, investigate" must not replicate); supply a
notes cell when the new instance needs one.
ref: YOUR correlation key per row (e.g. 1, 2, 3), unique within the batch. It is echoed back so you can match results to what you sent; the server never reuses or interprets it.date: ISO YYYY-MM-DD.amount/qty: decimal STRINGS (never raw JSON numbers). Each transaction needs=2 splits balancing to zero in the default currency. Rows may differ in width (2 splits vs 3).
The transaction currency is the book default unless the row declares one via the
curcolumn (see PER-TRANSACTION CURRENCY above).
BEHAVIOR — one book-open, one atomic save:
A STRUCTURAL error (unbalanced, unknown account, bad pairs) aborts the WHOLE batch by default; nothing is written. Pass
on_error="skip"to write the good rows and reject only the bad ones.A duplicate rejects ONLY its row;
force=Trueoverrides all blocking duplicates.dry_run=Truevalidates + screens without writing.
OUTPUT — a JSON envelope of two TSV tables joined by ref:
results(always):ref, status, txn_guid, dup_count, max_confidence, reason. status iscreated|rejected|would_create(dry_run, candidate-free rows only) |review_required(dry_run rows with >=1 duplicate candidate — rule each against the duplicates table before committing); reason is a code likeduplicate_detectedor the validation message.max_confidence(HIGH/MEDIUM/blank) is the row's top duplicate candidate — enough for the common keep/drop call without the join.duplicates(only when matches exist): SELF-CONTAINED comparison rows, sorted strongest-correspondence first —ref, candidate_guid, confidence, state, date_new, date_old, date_delta_days, amt_new, amt_old, amt_delta, cur, desc_new, desc_old, notes_old, memo_old, cat_new, cat_old, split_match, signals._new= your proposed row,_old= the existing transaction;cat_*are the category (non-payment) legs asaccount=amount|...;split_match(exact/partial/none) compares them — MEDIUM on date+amount butnoneon category is usually a distinct purchase. Amounts are SIGNED (direction matters: a deposit is not a payment's twin).amt_deltais blank on cross-currency candidates (curnames the candidate's currency exactly when the frames differ);memo_oldandstateblanks mean this surface can't fill them. Never re-read your own input — both sides are in the row. Σ(dup_count) equals the duplicates row count.Dry runs additionally lead with
summary(would-create/ review-required/rejected counts + the homework line) and close witheffects— the projected per-account balance deltas of the rows that would land.
Args: transactions: The TSV block described above. force: Override ALL blocking (HIGH) duplicates this batch. dry_run: Validate + screen, write nothing. on_error: "abort" (default) or "skip" for structural errors.
Inputs: transactions (required), force, dry_run, on_error. Returns: result
debt_payoff_planARead-only
Calculate an avalanche-method debt payoff schedule with YETI multiplier.
Auto-discovers CREDIT/LIABILITY accounts that have an 'apr' slot set. Set APRs via set_account_slot (e.g., set_account_slot("Liabilities:Visa", "apr", "23.49")).
Assumptions the schedule is computed under: interest compounds monthly at apr/12 on the running balance; one payment per debt per month starting this month; extra budget beyond the minimums goes to the highest-APR debt first (avalanche); balances are as of today in the book default currency; amounts round to 0.01. Debts the plan cannot include are CONFESSED in ⚠ lines, never silently dropped: foreign-currency debts with no FX rate, loans with no minimum_payment/loan_term_months to estimate a payment from, and balance-carrying debts with no 'apr' slot.
Returns a compact text summary by default — kill order with
balances/APRs/payoff months, YETI line, totals, debt-free date.
Use verbose=true for the structured dict (per-account
interest_paid / credit_limit / minimum_payment,
plus the structured yeti block) suitable for programmatic
consumers.
YETI (Your Expense's True Impact) shows the true cost of a purchase when carrying debt: "A $1.00 purchase will cost you $1.68 by the time your debt is paid off."
Args: monthly_budget: Total monthly amount available for all debt payments combined additional_purchase: Dollar amount to calculate YETI for (default "1.00") verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report.
Inputs: monthly_budget (required), verbose, additional_purchase. Returns: result
delete_accountBDestructiveIdempotent
Delete an account from the chart of accounts.
Safeguards prevent deletion if the account has children or transactions.
Args: name: Account ref to delete (full path, %short GUID, or full 32-char GUID)
Inputs: name (required). Returns: result
delete_account_slotADestructiveIdempotent
Remove one custom metadata slot from an account.
Permanent, and surgical: only the named key is deleted — other slots, the account, and its transactions are untouched. Errors, changing nothing, if the account ref or key doesn't exist, or if the key contains '/' (reserved for internal hierarchical slots; user slots are flat). get_account_slots lists the removable keys; set_account_slot re-creates one.
Args: account: Account ref: full path (e.g., "Liabilities:Credit Cards:Capital One"), %short GUID, or full 32-char GUID. key: Slot key to remove.
Inputs: key (required), account (required). Returns: result
delete_budgetADestructiveIdempotent
Delete a budget and every per-period amount set on it.
Permanent — there is no undo and no archive state. Only the plan is removed: transactions and account balances are untouched (budgets are plans, not postings). Errors, changing nothing, if the name matches no budget — list_budgets shows what exists, exact and case-sensitive. To retire a budget while keeping its numbers readable, simply stop reporting on it instead of deleting.
Args: name: Budget name (exact, case-sensitive).
Inputs: name (required). Returns: result
delete_documentADestructiveIdempotent
Delete an UNPOSTED customer invoice, vendor bill, employee voucher, or credit note.
Posted documents are on the books — unpost_document first (payments block unposting; the audit trail outranks tidiness).
Args: document_type: "invoice", "bill", "voucher", or "credit_note". id: Document ID (e.g., "000001"). party_type: Owner side, credit notes only — pass it when a credit note's ID collides with a document of the same ID on the other side (ID counters are per type).
Inputs: id (required), document_type (required), party_type. Returns: result
delete_jobADestructiveIdempotent
Delete a job.
Refuses by default when invoices/bills are linked to the
job (data-loss prevention). force=True re-parents
every linked invoice back to its underlying customer or
vendor before deleting the job row, preserving invoice
history. Use update_job(active=False) instead if you
want to keep the job in place but mark the project done.
Args: job_id: Job ID. force: If True, re-parent linked invoices instead of refusing. Default False.
Inputs: job_id (required), force. Returns: result
delete_partyADestructiveIdempotent
Delete a customer, vendor, or employee.
Blocked while the party has documents (invoices, bills, vouchers, credit notes) — the audit trail outranks tidiness. Prefer update_party(active=false) to retire a party while keeping its history.
Args: party_type: "customer", "vendor", or "employee" (ID counters collide across types — always required). id: Party ID (e.g., "000001").
Inputs: id (required), party_type (required). Returns: result
delete_priceADestructiveIdempotent
Delete a single price entry.
Identifies the price by (commodity, namespace, date).
Pass source to disambiguate when multiple prices exist
on the same commodity+date (e.g. one user-entered and one
fetched from a feed).
Args: commodity: Symbol (e.g., "VTSAX", "USD", "EUR"). namespace: Namespace (e.g., "FUND", "CURRENCY"). date: ISO date (YYYY-MM-DD) of the price to delete. source: Optional source tag (e.g., "user:price", "user:yfinance"). Required when multiple prices exist on the same commodity+date.
Inputs: date (required), commodity (required), namespace (required), source. Returns: result
delete_scheduled_transactionADestructiveIdempotent
Delete a scheduled transaction.
Does not affect transactions already created from this schedule.
Args: guid: Scheduled transaction GUID (or 8+ char prefix).
Inputs: guid (required). Returns: result
delete_taxtableADestructiveIdempotent
Delete a sales-tax table.
Refuses when any Entry row references the taxtable (computed via SQL on the entries table). Voided invoices still pin their taxtables — voided entry rows persist for audit-trail purposes. Remove or re-assign referencing entries first.
Args: name: Taxtable name.
Inputs: name (required). Returns: result
delete_transactionADestructiveIdempotent
Delete one transaction by GUID — or several in one call.
Safeguards prevent deletion if a transaction has reconciled splits (force=true overrides) or is an invoice's posting record (unpost_document first).
Pass a LIST of GUIDs to delete several in one book open /
one save. The batch is all-or-nothing: every guid is
validated before anything is deleted, so a bad guid rejects
the whole call with nothing removed. Response for a list is
{status, count, transactions: [{guid, description}]};
a single guid returns the single-object shape as before.
Args: guid: Transaction GUID (32-char hex or 8+ char prefix), or a list of them. force: Allow deleting transactions with reconciled splits.
Inputs: guid (required), force. Returns: result
enter_statementADestructiveIdempotent
Enter a COMPLETE bank/card statement in one atomic call: create the new lines, claim the ones already in the book, and reconcile everything against the closing balance — all in one save, or nothing at all.
THE WORKFLOW (two calls around your judgment):
dry_run=true(the DEFAULT) — transcribe the statement and get back a classification of every line: NEW (not in the book), MATCH (an existing unreconciled split corresponds), OVERLAP (already reconciled), AMBIGUOUS (several candidates). MATCH/AMBIGUOUS rows come with the candidate's full annotation (date, amount, description, notes, memo, short GUID) so you can adjudicate each one.Rule every MATCH/AMBIGUOUS row yourself, adapt annotations, confirm with the user.
dry_run=false— NEW rows now carry interpreted description/notes and counter-splits; MATCH rows carrymatch=<split guid>claims. The server enters, claims, reconciles every statement-touched split atstatement_date, and saves once.
TRANSCRIBE, DON'T INTERPRET (dry-run): amounts and balances
go in EXACTLY as the statement prints them — for credit
cards too (charges positive, balance as amount owed). The
server applies the sign convention from the account's type;
you never flip a sign. The gate
opening + sum(lines) == closing must hold or the call
rejects: transcribe every line.
INPUT — lines is a TSV block. Header: ref, date
first, then any order of description, notes,
raw, match, amount (required), then optional
amt, acct, memo, qty counter-split groups (batch
grammar). The statement account's own leg is SYNTHESIZED —
never a column. Dry-run typically needs only::
ref<TAB>date<TAB>raw<TAB>amount
1<TAB>2026-07-03<TAB>POS DEBIT WHOLEFDS #123<TAB>-87.12raw= the verbatim statement line; it lands on the bank leg's memo (provenance).description/notesare your interpretation (commit).match= the split GUID this line claims instead of creating (from the dry-run candidates table). Claim rows may also carryraw(updates the claimed split's memo) andnotes(updates the transaction's notes), and END at their last fixed column — they take no split cells. The claimed amount must equal the line amount exactly — fix the book first if they disagree.A commit row with no counter-splits auto-fills from the most recent same-description 2-split transaction, adapted to the line amount (marked
auto_filled_from:<guid>). The precedent must have exactly one leg on the statement account and no cross-commodity leg — anything else rejects with "supply explicit counter-splits". Explicit counter-splits must not name the statement account (its leg is synthesized).
SAFETY: the account's reconciled balance must tie to
opening_balance (a prior unentered statement blocks
commit), every created-vs-existing exact overlap must be
explicitly claimed or forced, and the projected closing tie
is verified BEFORE anything is written. The two force
flags are INDEPENDENT: force_base=true lands onto an
untied opening base (the consequent tie discrepancy is
recorded, and duplicate detection STAYS ON);
force_duplicates=true creates past exact twins you
have adjudicated as distinct. Neither bypasses the
statement's own self-check. After the save, the reconciled
balance is read back and verified against the tie.
OUTPUT (dry-run): summary (class counts), lines
(ref, class, cands, note — the note is the resolved
disposition: the guard's refusal coaching verbatim, the
auto-fill prediction, or "will claim …"), candidates —
SELF-CONTAINED comparison rows sorted
strongest-correspondence first (ref, candidate_guid, confidence, state, date_new/old + delta, amt_new/old + delta, cur, desc_new/old, notes_old, memo_old, cat_new/old, split_match, signals; _new = the statement line in
book convention, _old = the existing split — never
re-read your own input; cur is structurally blank on
this surface), plus warnings (only when present;
candidates likewise) and tie — the projected
reconciled balance vs the closing, with a count of rows
this exact payload would refuse at commit. The dry-run
rehearses the SAME disposition procedure commit runs —
force included. The tie is the only verdict;
MATCH/AMBIGUOUS rows are yours to rule.
OUTPUT (commit): results (ref, status, guid, note;
status is created | claimed | skipped_duplicate, or on a
refused statement rejected | statement_aborted — the note
column carries the row's coaching and
auto_filled_from:<guid> markers), plus, on success
only, the new reconciled balance and the tie (a refusal
returns just summary + results).
Args: account: Statement account ref (path, %short, or GUID). BANK/CASH/ASSET/CREDIT/LIABILITY only. statement_date: The statement's closing date (YYYY-MM-DD); every touched split reconciles at it. opening_balance: Opening balance, exactly as printed. closing_balance: Closing balance, exactly as printed. lines: The TSV block described above. dry_run: DEFAULT TRUE — the rehearsal is the workflow. force_base: Land onto an untied opening base; the tie discrepancy is recorded, twin detection stays on. force_duplicates: Create past exact unclaimed twins (you adjudicated them as distinct charges). show_all: Dry-run only. Lines with MEDIUM/HIGH candidates suppress their LOW amount-coincidences (the cands column notes "+N LOW suppressed"); show_all=true lists everything.
Inputs: lines (required), account (required), statement_date (required), closing_balance (required), +5 more. Returns: result
get_accountARead-only
Get details for one account: type, commodity, description, placeholder flag, GUID, and hierarchy position.
Read-only. Returns {"error": "Account not found: ..."}
when the ref matches nothing — nothing raises. Use
list_accounts to discover refs in bulk, get_balance when you
only need a number, get_account_slots for custom metadata
(APR, credit_limit, ...).
Args: name: Account ref: full path (e.g. 'Assets:Bank:Checking'), %short GUID, or full 32-char GUID
Inputs: name (required). Returns: result
get_account_slotsARead-only
Read slots (custom metadata) from an account.
Slots are key-value pairs stored on accounts for metadata like APR, credit limit, reward rates, or any custom data.
Args: account: Account ref: full path (e.g., "Liabilities:Credit Cards:Capital One"), %short GUID, or full 32-char GUID. key: Specific slot key to retrieve. If omitted, returns all slots.
Inputs: account (required), key. Returns: result
get_audit_logARead-only
Read audit log entries for a date.
Returns the human-readable text audit log, led by a
Showing X-Y of Z audit entries (date) indicator. Each write
operation (CREATE, UPDATE, DELETE, VOID, RECONCILE, etc.) is one
entry separated by a blank line. Reads are not logged.
Unlike the row-list tools, the window is anchored to the most
recent entry: offset pages backward into history (offset=0
is the newest page), since "what happened lately" is the usual
question. limit=0 returns the count only.
Args: log_date: Date to read (YYYY-MM-DD). Defaults to today. limit: Page size (default 50). 0 = count only. offset: Entries to skip back from the most recent (default 0).
Inputs: limit, offset, log_date. Returns: result
get_balanceARead-only
Get the balance of an account as of a specific date.
Defaults to today's date — future-dated transactions
(scheduled payments, accrued interest) are excluded. To
project a balance forward including future entries, pass
an explicit as_of_date past today.
Args: account_name: Account ref: full path (e.g. 'Assets:Bank:Checking'), %short GUID, or full 32-char GUID as_of_date: Date in ISO format (YYYY-MM-DD). Defaults to today.
Inputs: account_name (required), as_of_date. Returns: result
get_book_summaryARead-only
Get a compact overview of the entire GnuCash book.
Returns book path, currency, account structure, transaction counts, key balances, net worth, commodities, and scheduled transactions in a single text response. Use this first to orient yourself.
Inputs: no named parameters. Returns: result
get_budgetARead-only
Get full details of a budget including all budget amounts.
Returns a compact text table by default — collapses uniform
periods (e.g., "250/mo (all periods)") so the typical
12-cell repeat doesn't dominate the response. Use verbose=true
for the full structured periods dict per account.
Args: name: Budget name. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report.
Inputs: name (required), verbose. Returns: result
get_budget_reportARead-only
Compare actual spending against budget.
Returns a compact text table by default with ⚠ markers on categories exceeding budget. Use verbose=true for the full structured dict.
Args: budget_name: Name of the budget. period: Which period to report: - None: Current period based on today's date (default) - Integer 0-11: Specific period - "ytd": Year to date (all periods up to current) - "all": All periods account: Optional filter to specific account or parent account. include_children: If True and account specified, include child accounts. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report.
Inputs: budget_name (required), period, account, verbose, +1 more. Returns: result
get_documentARead-only
Get full details for a customer invoice, vendor bill, employee voucher, or credit note, including line items.
Returns all entries with quantities, prices, and totals;
the response's type field names the document kind.
Status vocabulary: open = editable, not yet booked; posted =
on the books, payable; paid = remaining balance zero. The
full definitions live on list_documents; the unpaid list
is get_outstanding_documents.
Args: id: Document ID (e.g., "000001"). This is the human-readable ID, not the internal GUID. document_type: "invoice", "bill", "voucher", or "credit_note" — disambiguates when IDs collide across per-type counters. party_type: Owner side ("customer"/"vendor") — needed only for credit notes, which exist on both sides.
Inputs: id (required), party_type, document_type. Returns: result
get_job_reportARead-only
Per-job summary: billed / paid / outstanding totals across all linked invoices, plus the per-invoice breakdown.
Totals are returned as totals_by_currency (a dict
keyed by ISO currency code) so the same shape works
whether the job's invoices share a currency or span
multiple. Both posted and unposted (draft) invoices are
included — drafts contribute their face value as
billed + outstanding with paid=0, so the
report shows the full pipeline.
Args: job_id: Job ID (e.g., "000001").
Inputs: job_id (required). Returns: result
get_latest_priceARead-only
Get the most recent price for a commodity.
Args: commodity: Symbol of the commodity (e.g., "VTSAX"). namespace: Namespace of the commodity (e.g., "FUND"). currency: Currency for the price. Defaults to the book's default currency. Pass explicitly to get a price quoted in a non-default currency.
Returns: JSON with date, value, type, and source of most recent price. Returns null if no price exists.
Inputs: commodity (required), namespace (required), currency. Returns: result
get_lotARead-only
Get detailed information about a lot.
Args: guid: Lot GUID (or 8+ char prefix).
Returns: JSON with lot details including all splits: - title, notes, is_closed - splits: list of all splits with date, quantity, value - summary: total quantity, cost basis, cost per share
Inputs: guid (required). Returns: result
get_outstanding_documentsARead-only
Get all posted customer invoices, vendor bills, employee vouchers, and credit notes with outstanding balances.
This is the authoritative unpaid list: outstanding = posted
with a remaining balance > 0. One call answers "what is
actually unpaid?" — no need to combine list_documents and
get_document (full status vocabulary on list_documents).
Leads with a Showing X-Y of Z invoices (date range) line,
then a compact one-line-per-doc format by default with action
columns (due date, days past due, currency, BILL tag, owner).
Sorted most-overdue-first so the bookkeeper sees the urgent
items at the top. Page with offset; limit=0 returns the
count only.
Use verbose=true for structured JSON with original_amount /
amount_paid / amount_due breakdown — the shape
pay_document workflows expect.
Args: party_type: Filter by "customer" or "vendor". Omit for all. customer_id: Filter by specific customer ID. vendor_id: Filter by specific vendor ID. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: limit, offset, verbose, vendor_id, +2 more. Returns: result
get_partyARead-only
Get details for one customer, vendor, or employee by ID.
Args: party_type: "customer", "vendor", or "employee" — required because ID counters collide across types (customer 000001 ≠ vendor 000001). id: Party ID (e.g., "000001"). This is the human-readable ID shown in GnuCash, not the internal GUID.
Inputs: id (required), party_type (required). Returns: result
get_pricesARead-only
Get price history for a commodity.
Leads with a Showing X-Y of Z prices (date range) line, then
a compact aligned text table by default. Page with offset;
limit=0 returns the count only. Use verbose=true for the full
structured envelope (prices list, showing, total,
offset, count).
Args: commodity: Symbol of the commodity (e.g., "VTSAX"). namespace: Namespace of the commodity (e.g., "FUND"). start_date: Optional start date filter (YYYY-MM-DD). end_date: Optional end date filter (YYYY-MM-DD). currency: Optional currency filter (e.g., "USD"). limit: Page size (default 50, max 250). 0 = count only. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. offset: 0-indexed first row to return (default 0).
Inputs: commodity (required), namespace (required), limit, offset, +4 more. Returns: result
get_reconciliation_statusARead-only
Per-account reconciliation table behind the dashboard's aggregate counts — answers "WHICH accounts are never reconciled / dormant / behind?"
One line per reconcilable account with activity, bucketed
exactly as the dashboard classifies them: behind
(most-behind first, with pending-split counts), never,
current, dormant ($0, fully reconciled, idle), and
excluded (opted out via the account's no_reconcile
slot — the right setting for loans, escrow payables, and
other statement-less accounts: set_account_slot(account,
"no_reconcile", "1"). Reporting-only; reconcile tools still
work on excluded accounts).
Args: verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return.
Inputs: limit, offset, verbose. Returns: result
get_server_configARead-only
Get the server's loaded configuration.
Returns loaded modules, tool count, book path, debug mode, and version. Use this to verify which tools are available in this session.
Inputs: no named parameters. Returns: result
get_transactionBRead-only
Get details for a specific transaction by GUID.
Args: guid: Transaction GUID (32-character hex string, or 8+ char prefix)
Inputs: guid (required). Returns: result
get_unreconciled_splitsARead-only
Get unreconciled splits for an account.
Leads with a Showing X-Y of Z splits indicator, then one
line per split, then a summary footer reflecting the full
unreconciled set (so the headline is honest even when individual
lines are clipped). Page with offset; limit=0 returns
the count only.
Use verbose=true for structured JSON with split GUIDs, amounts, totals,
and the showing indicator as a structured field.
Args: account: Account ref: full path (e.g. 'Assets:Bank:Checking'), %short GUID, or full 32-char GUID as_of_date: Only include splits on or before this date (YYYY-MM-DD) verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: account (required), limit, offset, verbose, +1 more. Returns: result
get_upcoming_transactionsARead-only
Get scheduled transactions due within a time window.
This is the "what bills are coming up?" query. Leads with a
Showing X-Y of Z upcoming transactions (date range) line,
soonest first. Page with offset; limit=0 returns the
count only.
Args: days: Look ahead window in days. Default 14. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: days, limit, offset, verbose. Returns: result
income_by_sourceARead-only
Get income breakdown by source for a period.
Returns a compact aligned text table by default. Use verbose=true for the structured dict.
Args: start_date: Start of period (YYYY-MM-DD) end_date: End of period (YYYY-MM-DD) depth: Hierarchy depth for grouping (1 = top-level categories, 2 = subcategories) verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. group_by: Optional "month", "quarter", or "year" — split the range into sub-period columns and return a multi-period TSV table (source rows, one column per period plus Total and Avg). Overrides verbose.
Inputs: end_date (required), start_date (required), depth, verbose, +1 more. Returns: result
list_accountsARead-only
List all accounts in the GnuCash chart of accounts.
Leads with a Showing X-Y of Z accounts line, then a compact
one-line-per-account format by default. Page with offset;
limit=0 returns the count only. Use verbose=true for full
JSON with guid, type, commodity, etc.
To FIND an account without paging the whole chart, pass
query — a case-insensitive substring matched against each
account's full path and description (e.g. query="grocer" or
query="4930" on a numbered chart). Results emit %short GUIDs
that every account-taking tool accepts. For searching
transactions by text or amount, use search_transactions.
Args:
root: Filter to a subtree (e.g., "Expenses" for expense accounts only).
verbose: If false (default), compact text output — optimized
for reading and token efficiency. If true, structured
JSON, for when you need machine-readable fields rather
than a report.
limit: Page size (default 50, max 250). 0 = count only.
offset: 0-indexed first row to return (default 0).
query: Case-insensitive substring filter on account
path/description. Combines with root.
Inputs: root, limit, query, offset, +1 more. Returns: result
list_billtermsARead-only
List all billing terms.
Leads with a Showing X-Y of Z billterms line, then a compact
one-line-per-term format by default. Page with offset;
limit=0 returns the count only. Use verbose=true for full
JSON with guid, discount details, etc.
Args: verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: limit, offset, verbose. Returns: result
list_budgetsARead-only
List all budgets in the book.
Leads with a Showing X-Y of Z budgets line, then a compact
one-line-per-budget format by default. Page with offset;
limit=0 returns the count only. Use verbose=true for the full
JSON envelope.
Args: verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: limit, offset, verbose. Returns: result
list_commoditiesARead-only
List all commodities (currencies, stocks, etc.) in the book.
Leads with a Showing X-Y of Z commodities line, then a
compact one-line-per-commodity format by default. Page with
offset; limit=0 returns the count only. Use verbose=true
for structured JSON with fraction, latest prices, etc.
THE PRICE-UPDATE WORK LIST: stale_days=30, held_only=true
returns exactly the commodities needing fresh quotes, each
marked Nd stale or no price on file. Look the quotes
up, then record them all in one create_prices call.
Args: verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0). stale_days: Only commodities whose latest market price is at least this many days old, including never-priced ones, excluding the book default currency. Omit for the unfiltered list. held_only: Only commodities some real account is denominated in. Filters AND-combine.
Inputs: limit, offset, verbose, held_only, +1 more. Returns: result
list_documentsARead-only
List customer invoices, vendor bills, employee vouchers, and credit notes.
Leads with a Showing X-Y of Z invoices (date range) line,
then a compact one-line-per-invoice format by default. Page with
offset; limit=0 returns the count only. Use verbose=true
for structured JSON with GUIDs, dates, notes, etc.
Status vocabulary (shared by every invoice/bill tool):
open = created and editable, not yet booked to A/R//A/P —
not payable. posted = booked to A/R//A/P with a lot
tracking its balance — payable. paid = posted with a zero
remaining balance (lot closed). outstanding = posted with
a remaining balance — the unpaid subset; get it directly from
get_outstanding_documents rather than deriving it here.
The status filter below covers document state
(open/posted) only; settlement state lives on the lot.
Args: status: Filter by status: "posted" or "open", or omit for all. document_type: Filter to one document kind ("invoice", "bill", "voucher", "credit_note"). Omit for all. party_type: Filter by owner side ("customer", "vendor"). Omit for all. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. job_id: Filter to invoices grouped under a specific job — useful for the "what's part of this engagement?" listing pattern. offset: 0-indexed first row to return (default 0).
Inputs: limit, job_id, offset, status, +3 more. Returns: result
list_jobsARead-only
List jobs, optionally filtered.
Leads with a Showing X-Y of Z jobs line; page with
offset, or pass limit=0 for the count only.
Pass id for one job's full details (name, owner,
active state, linked invoice/bill IDs) — the exact-lookup
mode that replaced get_job.
Args: id: Job ID for a single-job detail lookup (e.g., "000001"). All other filters are ignored. owner_type: Filter by "customer" or "vendor". Omit for all. owner_id: Filter by specific customer or vendor ID (requires owner_type). active_only: If True (default), exclude inactive jobs. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: id, limit, offset, verbose, +3 more. Returns: result
list_lotsARead-only
List all lots for an investment account.
Leads with a Showing X-Y of Z lots line, then a compact
one-line-per-lot format by default. Page with offset;
limit=0 returns the count only. Use verbose=true for full
JSON with guid, title, notes, etc.
Args: account: Account ref (full path, %short GUID, or full 32-char GUID). include_closed: If True, include fully-sold lots. Default False. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: account (required), limit, offset, verbose, +1 more. Returns: result
list_partiesARead-only
List customers, vendors, and/or employees.
Leads with a Showing X-Y of Z line per type, then a
compact one-line-per-party format by default. Page with
offset; limit=0 returns the count only. Use
verbose=true for full JSON with guid, address, notes, etc.
Args: party_type: "customer", "vendor", or "employee". Omit for all three (sections in that order). active_only: If True, only show active parties. Default True. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size per type (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: limit, offset, verbose, party_type, +1 more. Returns: result
list_scheduled_transactionsARead-only
List all scheduled transactions.
Leads with a Showing X-Y of Z scheduled transactions line,
then a compact one-line-per-schedule format by default. Page with
offset; limit=0 returns the count only. Use verbose=true
for structured JSON with GUIDs, splits, dates, etc.
Args: enabled_only: If True, only show enabled schedules. Default True. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: limit, offset, verbose, enabled_only. Returns: result
list_taxtablesARead-only
List all sales-tax tables, or get one by name.
Leads with a Showing X-Y of Z taxtables line. Compact format
(default): one line per taxtable with name, entry count, and
per-entry rate→account routing. Page with offset; limit=0
returns the count only. Verbose: structured JSON with resolved account
paths and refcount.
Args: name: Tax table name for a single-table detail lookup (entries, rates, account routing, refcount). All other parameters are ignored. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).
Inputs: name, limit, offset, verbose. Returns: result
list_transactionsARead-only
List transactions with optional filters.
Leads with a Showing X-Y of Z transactions (date range)
line so a truncated view is never mistaken for the whole set.
Page with offset; limit=0 returns the count only.
Compact format (default):
Unfiltered:
DATE<TAB>guid<TAB>Description<TAB>splitsFiltered by account (register form):
DATE<TAB>guid<TAB>±Amount<TAB>Description<TAB>other splitsColumn 3 is the signed impact on the filtered account; that account is dropped from the splits column.
Transactions with more than 4 splits collapse to the top 3 by
|value| plus +N more — call get_transaction for the
full breakdown.
Args: account: Filter by account name (switches output to register form) start_date: Start date in ISO format (YYYY-MM-DD) end_date: End date in ISO format (YYYY-MM-DD) limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0). verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report.
Inputs: limit, offset, account, verbose, +2 more. Returns: result
move_accountADestructiveIdempotent
Move an account — children and balances ride along — under a new parent in the hierarchy.
No transaction data changes: only the account's position (and therefore every descendant's full path) is rewritten. Errors, changing nothing, if either ref matches no account, if the move would create a cycle (new parent is the account itself or one of its descendants), or if the new parent already has a child of the same name. %short GUIDs survive the move; saved full paths do not. Use update_account to rename in place instead of moving.
Args: name: Account ref to move (full path e.g. "Expenses:Old:Account", %short GUID, or full 32-char GUID) new_parent: New parent account ref (full path, %short GUID, or full 32-char GUID)
Inputs: name (required), new_parent (required). Returns: result
net_worthARead-only
Calculate net worth (assets minus liabilities), as one value or a trajectory.
Read-only. Valuation is as-of: each date values holdings at the latest market rate on or before it, in the book's default currency; voided transactions are excluded. end_date alone gives one number; add start_date + interval for a series (one value per interval step from start_date, end_date always included as the last row). For the full A = L + E statement with per-account detail, use balance_sheet; this tool is the headline number and its trend. The dashboard's trajectory section is this same calculation.
Args: end_date: Calculate net worth as of this date (YYYY-MM-DD) start_date: Optional start date for time series (YYYY-MM-DD) interval: Optional interval for time series: 'month', 'quarter', or 'year'
Inputs: end_date (required), interval, start_date. Returns: result
pay_documentA
Record a payment against a posted customer invoice, vendor bill, employee voucher, or credit note.
Creates a payment transaction from the specified bank/cash account to the document's A/R or A/P account. Partial payments are supported.
dry_run=true rehearses the payment without booking it:
the full validation, conversion, discount, and FX pipeline
runs and the response shows the proposed splits, the
remaining balance after, whether the invoice would settle in
full, and any account the real call would auto-create. Same
inputs, same code path — a rehearsal that succeeds is a
payment that will book. Recommended before complex payments
(cross-currency, discounts, credit-note refunds).
For cross-currency payments where the rate moved between
post-date and pay-date, a realized FX gain/loss split is
booked. Pass fx_account to control routing; otherwise
the server picks the unique INCOME/EXPENSE account whose
leaf name matches "fx", "forex", "foreign exchange",
"currency gain/loss", "exchange gain/loss", or "currency
translation". When zero or multiple match, the canonical
Income:Foreign Exchange Gain/Loss is used (auto-created
if absent), and an fx_notice is returned listing
ambiguous candidates so you can pass fx_account
explicitly next time.
For invoices with early-payment-discount terms (e.g.,
"2/10 Net 30" = 2% off if paid within 10 days), pass
apply_discount=True to settle via discount. The tool
validates that the invoice has discount terms, the payment
date is within the discount window, and the shortfall
matches the expected discount on pre-tax principal. Each
failure mode rejects with a specific error rather than
silently downgrading to a partial payment. discount_account
controls routing the same way fx_account does
(auto-resolves to Expenses:Sales Discounts for customer
payments, Income:Purchase Discounts Taken for vendor
bill payments).
Args:
id: Document ID (e.g., "000001").
payment_account: Bank or cash account for payment (e.g., "Assets:Checking").
amount: Payment amount as decimal string (e.g., "500.00").
payment_date: Payment date (YYYY-MM-DD). Defaults to today.
description: Description for the payment transaction. Optional.
document_type: "invoice", "bill", "voucher", or
"credit_note" — disambiguates when IDs collide.
party_type: Owner side, credit notes only.
fx_account: Optional INCOME or EXPENSE account to receive
realized FX gain/loss (cross-currency payments only).
Accepts a full path, %short GUID, or full 32-char GUID.
apply_discount: When True, treat this payment as the
final settlement and absorb the early-payment
discount from the invoice's billterm. Default False
— explicit opt-in. Hard-rejects on credit notes
(refunds don't take discounts).
discount_account: Optional INCOME or EXPENSE account to
receive the discount split. Auto-resolves when
omitted. Accepts full path, %short GUID, or full
32-char GUID.
force: Override the stale-FX-rate guard. A cross-currency
payment etches the rate at pay time; if the latest
price is 7–90 days from the payment date the payment
is refused with stale_fx_rate unless force=True
(the override is recorded as fx_stale/"forced").
A rate beyond the 90-day cap cannot be forced.
memo: Optional memo for the bank-account split (e.g.,
check number or wire reference). description
names the whole transaction; memo annotates the
cash movement.
dry_run: When True, rehearse without writing — returns
the proposed splits and projected outcome instead of
booking. Default False.
Returns:
status is "paid" when the document settles to
zero, "partial" when a balance remains, and
"would_pay" on dry runs — plus the amount paid,
remaining balance, and transaction reference.
Inputs: id (required), amount (required), payment_account (required), memo, +9 more. Returns: result
post_documentAIdempotent
Post a customer invoice, vendor bill, employee voucher, or credit note to A/R or A/P.
Posting creates a transaction in the A/R or A/P account and makes the invoice official. Once posted, entries cannot be added.
For a foreign-currency document, the exchange rate is etched
at posting and cannot be updated retroactively. If the latest
price for the invoice currency is more than 7 days from the
post date (the GNUCASH_FX_GUARD_DAYS window), posting is
refused with a stale_fx_rate error — run create_price
for a rate near the post date, then retry, or pass
force=True to post with the stale rate (recorded in the
response and audit log as fx_stale/"forced"). A rate
beyond the 90-day staleness cap cannot be forced.
Args: id: Document ID (e.g., "000001"). post_account: A/R or A/P account path (e.g., "Assets:Accounts Receivable"). post_date: Date in ISO format (YYYY-MM-DD). Defaults to today. due_date: Payment due date (YYYY-MM-DD). Optional. description: Description for the posting transaction. Optional. document_type: "invoice", "bill", "voucher", or "credit_note" — disambiguates when IDs collide. party_type: Owner side, credit notes only. force: Override the stale-FX-rate guard and post with a 7–90 day stale rate. Default False.
Inputs: id (required), post_account (required), force, due_date, +4 more. Returns: result
reconcile_accountADestructiveIdempotent
Reconcile splits against a statement balance.
SIGN CONVENTION: statement_balance is the ACCOUNT's balance in GnuCash's signs — for liability accounts (credit cards) a $5,000 owed balance is "-5000", not "5000".
Two modes:
Targeted (
split_guids=[...]): reconcile exactly the listed splits (SPLIT guids from get_unreconciled_splits, not transaction guids). Use when statement and book disagree and you need to pick a subset.Bulk (
reconcile_all=true): reconcile every unreconciled split dated on or before through_date (default: statement_date — a statement reconciliation is bounded by the statement). One call, no GUID round-trip.
Both modes verify the resulting reconciled balance ties to statement_balance before mutating; mismatch rejects with the discrepancy amount.
TYPICAL STATEMENT FLOW (credit card or bank): batch-enter the statement's transactions (create_transactions), then reconcile_all with the statement's closing date and balance. Multi-month catch-up: enter all months in one batch, then one reconcile_all per statement, oldest first — the through_date default keeps each sweep inside its own statement.
Args: account: Account ref: full path (e.g. 'Assets:Bank:Checking'), %short GUID, or full 32-char GUID statement_date: Statement ending date (YYYY-MM-DD) statement_balance: Expected balance from statement (as string, e.g., '1234.56') split_guids: List of split GUIDs to reconcile (targeted mode). Omit for bulk mode. reconcile_all: When true, reconcile all unreconciled splits up to through_date. through_date: Date filter for bulk mode (YYYY-MM-DD); defaults to statement_date.
Inputs: account (required), statement_date (required), statement_balance (required), split_guids, +3 more. Returns: result
replace_splitsADestructiveIdempotent
Replace all splits in a transaction with a new set.
Replace all splits in a transaction with a completely new set. The transaction's currency, description, date, and notes are preserved. New splits must balance to zero.
A new split that reproduces an existing one (same account, amount, and quantity) is an UNCHANGED leg: it keeps the old split's memo (supply a memo to override) and its reconcile state. So recategorizing the expense leg of a reconciled bank transaction is safe — resubmit the bank leg as-is and only the changed leg resets.
Args: guid: Transaction GUID (32-character hex string, or 8+ char prefix) splits: Complete new set of splits. Each split needs: - 'account' (required): Account ref — full path, %short GUID, or full 32-char GUID - 'amount' (required): Value in transaction currency, as a decimal string - 'quantity' (optional): Amount in account's commodity, as a decimal string. Required if account commodity differs from transaction currency. - 'memo' (optional): Split memo force: Required only when the replacement would CHANGE a reconciled split (or remove splits from lots) — unchanged reconciled legs are preserved without it.
Inputs: guid (required), splits (required), force. Returns: result
search_transactionsARead-only
Search transactions by description, memo, notes, or amount.
Compact format (default):
DATE<TAB>guid<TAB>Description<TAB>splits
Transactions with more than 4 splits collapse to the top 3 by
|value| plus +N more — call get_transaction for the
full breakdown. Leads with a Showing X-Y of Z transactions
line; page with offset, or pass limit=0 for the count.
Args: query: Search query string. For amount, supports: exact ("100"), greater (">100"), less ("<100"), range ("100-200") field: Field to search: 'description', 'memo', 'notes', or 'amount' limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0). verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report.
Inputs: query (required), field, limit, offset, +1 more. Returns: result
set_account_slotADestructiveIdempotent
Set a custom metadata slot on an account.
Stores a key-value pair on the account. Values are stored as strings. Use for APR, credit limits, reward rates, or any per-account metadata.
Args: account: Account ref: full path (e.g., "Liabilities:Credit Cards:Capital One"), %short GUID, or full 32-char GUID. key: Slot key (e.g., "apr", "credit_limit"). value: Slot value (always stored as string).
Inputs: key (required), value (required), account (required). Returns: result
set_budget_amountADestructiveIdempotent
Set a budget target for an account.
Args: budget_name: Name of the budget. account: Account ref: full path (e.g., "Expenses:Groceries"), %short GUID, or full 32-char GUID. amount: Monthly budget amount as string (e.g., "500.00"). period: Which period(s) to set: - None or "all": Set same amount for all periods (default) - Integer 0-11: Set specific period (0 = January for yearly budget) - "q1", "q2", "q3", "q4": Set all periods in quarter
Inputs: amount (required), account (required), budget_name (required), period. Returns: result
set_reconcile_stateADestructiveIdempotent
Set the reconciliation state for a split.
Args: split_guid: GUID of the split to update (32-character hex string, or 8+ char prefix) state: New reconcile state: 'n' (new), 'c' (cleared), 'y' (reconciled) reconcile_date: Date in ISO format (YYYY-MM-DD). Required for 'y', defaults to today.
Inputs: state (required), split_guid (required), reconcile_date. Returns: result
spending_by_categoryARead-only
Get spending breakdown by expense category for a period.
Returns a compact aligned text table by default. Use verbose=true for the structured dict (programmatic consumers, plotting).
Args: start_date: Start of period (YYYY-MM-DD), inclusive. No calendar snapping — for calendar-month figures pass full month boundaries (e.g. 2026-05-01 to 2026-07-31). end_date: End of period (YYYY-MM-DD), inclusive. depth: Hierarchy depth for grouping (1 = top-level categories, 2 = subcategories) verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. group_by: Optional "month", "quarter", or "year" — split the range into sub-period columns and return a multi-period TSV table (category rows, one column per period plus Total and Avg). Overrides verbose.
Inputs: end_date (required), start_date (required), depth, verbose, +1 more. Returns: result
switch_bookAIdempotent
Switch the active GnuCash book (multi-book sessions only).
All subsequent tool calls — and the audit/debug logs — operate on the newly-selected book until the next switch. Only present when GNUCASH_BOOK_PATH lists 2+ books.
Inputs: name (required). Returns: result
unpost_documentADestructiveIdempotent
Reverse a posted customer invoice, vendor bill, employee voucher, or credit note (each keeps its type through the round-trip).
Deletes the posting transaction and lot, and clears the invoice's posted-state metadata. The invoice returns to "open" state and can be edited or re-posted. Refuses if the invoice has any payments applied — void payments first, then unpost.
Args: id: Document ID (e.g., "000001"). document_type: "invoice", "bill", "voucher", or "credit_note" — disambiguates when IDs collide. party_type: Owner side, credit notes only.
Inputs: id (required), party_type, document_type. Returns: result
unvoid_transactionADestructiveIdempotent
Restore a voided transaction to its pre-void amounts.
The inverse of void_transaction: original split values come back from the slots the void stored, and the void markers and reason are cleared. All-or-nothing — if any split's stored void data is missing, the tool errors and restores nothing (no partial resurrection). Errors too if the transaction isn't found or isn't voided. Restored splits return as UNreconciled ('n'), so a previously reconciled transaction needs reconciling again afterward.
Args: guid: Transaction GUID to unvoid (32-character hex string, or 8+ char prefix)
Inputs: guid (required). Returns: result
update_accountADestructiveIdempotent
Update an existing account's properties.
Args: name: Account ref to update (full path e.g. "Expenses:Groceries", %short GUID, or full 32-char GUID) new_name: New name for the account (just the leaf name, not full path) description: New description placeholder: New placeholder status (true = container only) account_type: New account type (e.g., "CREDIT", "BANK"). Only changes within the same debit/credit polarity are allowed — e.g., LIABILITY to CREDIT, ASSET to BANK. Cross-polarity changes (e.g., ASSET to LIABILITY) are blocked. notes: New notes (max 4096 bytes; shared with GnuCash desktop's Notes field). Pass "" to clear.
Inputs: name (required), notes, new_name, description, +2 more. Returns: result
update_jobADestructiveIdempotent
Update a job's name, reference, or active state.
Any subset of fields can be passed; unspecified fields are left unchanged. Returns a diff-style response.
Args: job_id: Job ID. name: New name (optional). reference: New reference (optional). active: New active flag — pass False to deactivate a completed job without deleting it (preserves history).
Inputs: job_id (required), name, active, reference. Returns: result
update_partyADestructiveIdempotent
Update a customer's, vendor's, or employee's mutable fields.
None = no change on every parameter; pass an empty
string to clear notes. Returns a diff-style response
with the changed fields only.
Args: party_type: "customer", "vendor", or "employee" (ID counters collide across types — always required). id: Party ID (e.g., "000001"). name: New display name. currency: New ISO currency code (future documents only). notes: New notes; "" clears. Employees have no notes field — rejected, not ignored. active: Set active/inactive (inactive parties hide from default listings but keep their history). address: Full replacement address (see create_party).
Inputs: id (required), party_type (required), name, notes, +3 more. Returns: result
update_scheduled_transactionADestructiveIdempotent
Update a scheduled transaction.
Args: guid: Scheduled transaction GUID (or 8+ char prefix). enabled: Enable or disable. end_date: Three-state field for the schedule's end date.
- Omit (or pass ``null``): leave unchanged.
- Pass ``"YYYY-MM-DD"``: set to that date.
- Pass ``""`` (empty string): clear the existing
end date back to "no end" (open-ended schedule).
The empty-string sentinel exists because MCP tool
schemas don't easily express "set to null" as a
distinct value from "no change supplied" — both
arrive as Python ``None``. Empty-string is the
explicit "clear it" signal.
notes: Instantiation notes applied to transactions
created from this schedule going forward (existing
transactions untouched). Same three-state
convention as end_date: text to set, ``""`` to
clear, omit to leave unchanged.
Inputs: guid (required), notes, enabled, end_date. Returns: result
update_taxtableADestructiveIdempotent
Update a sales-tax table's name and/or entries.
Diff-style response: only changed fields are returned.
Entry replacement on a taxtable that's already in use is
destructive to FUTURE entries' tax math. Existing posted
invoices retain their original splits (splits are stored,
not derived), but new entries on any document will use the
replacement entries' rates. When refcount > 0 and
entries is given, force=True is required to proceed.
Args:
name: Current taxtable name.
new_name: New name (optional).
entries: Replacement entry list (optional). Same shape
and validation as create_taxtable.
force: Required to replace entries when the taxtable
is already referenced by document entries.
Inputs: name (required), force, entries, new_name. Returns: result
update_transactionsADestructiveIdempotent
Update MANY transactions with per-row values (bulk edit).
INPUT — updates is a TSV block: header guid plus any
of description, notes, date (at least one), then
one row per transaction::
guid<TAB>description<TAB>notes
56926ac2<TAB>PayPal Credit Payment<TAB>Resolved — card payment
7f0fc117<TAB><TAB>Netflix subscription, $22.10/moAn EMPTY cell leaves that field UNCHANGED. To blank a field,
opt in with a clear column: its cell names the fields to
clear on that row (notes or description,notes) —
explicit per row, so a sparse batch can never mass-erase by
accident. date is not clearable; a row that sets and
clears the same field rejects. Splits and memos are not
updatable here (replace_splits)::
guid<TAB>notes<TAB>clear
56926ac2<TAB>Verified subscription<TAB>
7f0fc117<TAB><TAB>notesOne book open, one save; on_error="abort" (default)
sinks the batch on any bad row, "skip" keeps good rows.
Date moves on transactions with reconciled splits are
rejected per row unless force=true (they shift the
transaction out of its reconciled statement period).
Returns a results TSV keyed by your input guids. This is
the canonical update tool for one transaction or many (the
former update_transaction tool was removed; this
replaces it — same value across many transactions = the
same cells repeated per row).
Inputs: updates (required), force, on_error. Returns: result
vendor_spending_reportARead-only
Get spending breakdown by vendor for a period.
Analyzes posted vendor bills to show total billed, total paid, and outstanding amounts per vendor.
Returns a compact aligned text table by default. Use verbose=true for the structured dict (programmatic consumers).
Args: start_date: Start of period (YYYY-MM-DD). end_date: End of period (YYYY-MM-DD). vendor_id: Optional filter to a specific vendor. verbose: If false (default), compact text output — optimized for reading and token efficiency. If true, structured JSON, for when you need machine-readable fields rather than a report. group_by: Optional "month", "quarter", or "year" — split the range into sub-period columns of total billed per vendor and return a multi-period TSV table. Overrides verbose.
Inputs: end_date (required), start_date (required), verbose, group_by, +1 more. Returns: result
void_transactionADestructiveIdempotent
Void a transaction (proper accounting void, not delete).
Voiding preserves the transaction for audit purposes but zeroes out all split values. Use this instead of delete when you need to maintain an audit trail.
Args: guid: Transaction GUID to void (32-character hex string, or 8+ char prefix) reason: Reason for voiding (required for audit trail)
Inputs: guid (required), reason (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 87 tools
Most tools target a distinct resource+action (create_account vs update_account vs delete_account), and workflows like document status are carefully explained. The main ambiguities are the single-vs-bulk price pairs (create_price/create_prices, get_prices/get_latest_price) and the overlapping transaction entry tools (create_transactions vs enter_statement), though descriptions do disambiguate them.
The core follows a consistent verb_noun pattern (list_accounts, create_transactions, delete_price, reconcile_account), but many report-style tools break it with noun phrases like balance_sheet, cash_flow, net_worth, spending_by_category, and vendor_spending_report. The mix is readable but not uniform.
87 tools is far beyond a typical practical surface and will overwhelm agents even though GnuCash is a broad domain. Many bulk/single and report variants inflate the count; the server would be more usable consolidated to ~50 tools.
Coverage is impressively deep: accounts, transactions, reconciliation, documents, parties, jobs, budgets, commodities, prices, lots, scheduled transactions, and reporting all have lifecycle or workflow support. Notable gaps remain — billterms have no update/delete, documents have no header-edit or entry-removal tools, and backups cannot be listed or restored via the API.
Maintenance
Related MCP Connectors
Read and update double-entry books: accounts, invoices, bills, bank activity and reports.
Personal, family and business books over fiat and crypto. Reads and records; it cannot pay.
Bookkeeping for owner-operated businesses. Query transactions, invoices, and reports.
Multi-currency budgeting: read and update your accounts, transactions, categories and budgets.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with local Beancount accounting ledgers through structured tools for viewing accounts, balances, and transactions, as well as inserting/removing transactions and answering natural-language questions via BeanQuery. Provides deterministic, validated, and auditable financial data operations with offline-first functionality.1-
- AlicenseNot gradedqualityBmaintenanceEnables reading and changing personal finance data—accounts, transactions, categories, budgets, and reminders—and generating reports through 28 MCP tools over local stdio or authenticated remote HTTP.MIT
- AlicenseNot gradedqualityBmaintenanceEnables offline management of sales contracts, customer receipts, traceable earnings accruals, actual payouts, and personal finance forecasts through a local stdio interface.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants and scripts to read, analyze and safely write self-hosted personal finance books, covering accounts, transactions, categories, tags, monthly and category reports, net worth, cash flow, recurring payments, installment plans and bulk imports. Writes are safeguarded with dry runs, delete confirmation, and an optional read-only mode, while amounts are returned exactly as both minor units and decimal strings with totals kept per currency.MIT