gnucash-mcp

Create a customer (client), vendor (supplier, contractor, payee), or employee record. 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" (a client who pays you — accounts receivable), "vendor" (a supplier, contractor, or payee you pay — accounts payable), or "employee" …

Record a price for a commodity (stock, NAV, exchange rate). GnuCash keeps ONE price per pair per day, and so does this tool. ``status`` says what happened: ``created``; ``updated`` (the same source, rewritten); ``replaced`` (the day's price from a lower-ranked source, or quoted the other way round, gave way); or ``kept`` — NOTHING WAS WRITTEN, because the day already has a price from a source that outranks this one (``note`` and ``existing`` say which). Sources rank in the order listed under ``source`` below: a feed quote ("Finance::Quote") outranks the default "user:price", and "user:price-e…

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:ecb - ``ref``: your correlation key, echoed in results. - ``ns``: commodity namespace; empty auto-resolves when t…

Create a recurring transaction template. Stored in GnuCash's own template format, so the schedule shows in GnuCash desktop's editor and its Since-Last-Run posts it. Schedules made in desktop can be instantiated here. 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 te…

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%) post one tax split per tax account, each the document's tax for that account rounded once, the way GnuCash desktop totals an invoice. 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``: "…

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 the oldest occurrence not yet entered — the overdue one if the dashboard reports one, else the next due. Call again to walk forward through missed periods. Any schedule still stored in the pre-native shape is migrated on this call, nothing posted for the others (``templates_migrated`` in the response).

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:A…

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 …

Delete an account from the chart of accounts. Safeguards prevent deletion if the account has children or transactions. Args: name: Account to delete. Account name ("Assets:Checking") or %short guid ("%d53d547").

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, if the key contains '/' (reserved for internal hierarchical slots; user slots are flat), or if the key is GnuCash's own data rather than a custom string (reconcile-info, ofx, import-map, placeholder, …). set_account_slot re-creates a removed key. Args: account: Account name ("Assets:Checking") or %short guid ("%d53d547"). key: Slot key to remove.

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

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

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.

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

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.

Delete a scheduled transaction. Does not affect transactions already created from this schedule. Args: guid: Scheduled transaction GUID (or 8+ char prefix).

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.

Delete one transaction by GUID — or several in one call. Safeguards prevent deletion if a transaction has reconciled splits or splits in lots — a lot split is cost basis or an invoice payment, and deleting it reopens the lot (force=true overrides either) — 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…

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): 1. ``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, descripti…

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 name ("Assets:Checking") or %short guid ("%d53d547").

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 name ("Assets:Checking") or %short guid ("%d53d547"). key: Specific slot key to retrieve. If omitted, returns all slots.

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 (de…

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 name ("Assets:Checking") or %short guid ("%d53d547"). as_of_date: Date in ISO format (YYYY-MM-DD). Defaults to today.

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.

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.

Compare actual spending against budget. Returns a compact text table by default with ⚠ markers on categories exceeding budget. A budget with both income and expense targets closes with INCOME / EXPENSES / NET lines rather than one TOTAL. 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 one account …

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. The response carries ``status`` (open = editable, not yet booked; posted = on the books, balance owed; paid = balance zero; applied = a credit note fully consumed against its target) and, once posted, ``amount_paid`` and ``amount_due`` from the same lot arithmetic ``get_outstanding_documents`` uses; ``overpaid: true`` marks a negative balance. A paid document keeps its amou…

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

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.

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

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 urgen…

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.

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

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 st…

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.

Get details for a specific transaction by GUID. Returns its splits (account, value, quantity, memo, ``action``, reconcile state) and, when set, ``notes``, ``num`` (GnuCash's Num column) and ``doc_link`` (the transaction's document link). In a book with "Use Split Action Field for Number" on, a register's Num is that account's split ``action``. Args: guid: Transaction GUID (32-character hex string, or 8+ char prefix)

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 name ("Assets:Checking") or %short guid ("%d53d547"). as_of_date: Only include splits on or before this date (YYYY-MM-DD) verbose: …

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. Overdue occurrences (due date passed, never entered) lead the list, marked ``N days overdue``; each schedule appears once, at its oldest un-entered date, which is the date ``create_transaction_from_scheduled`` posts by default. 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 …

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 …

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 amo…

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

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

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 …

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); a credit note…

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. party_type: Filter by "customer" or "vendor". Omit for all. owner_id: Filter by specific customer or vendor ID (requires party_type). active_only: If True (default), exclude inac…

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 name ("Assets:Checking") or %short guid ("%d53d547"). 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 …

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 …

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 …

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…

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>splits`` - Filtered by account (register form): ``DATE<TAB>guid<TAB>±Amount<TAB>Description<TAB>other splits`` Column 3 is the signed impact on the filtered account; that account is dropped from the splits column. - Either form then adds the notes when present, and a labeled ``num:<number>`` …

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 to move. Account name ("Assets:Checking")…

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: …

Record a payment against a posted customer invoice (receive a customer payment), vendor bill (pay a supplier), employee voucher (reimburse an employee), or credit note (refund). Handles partial payments, early-payment discounts, cross-currency FX gain/loss, and prepayments. Creates a payment transaction from the specified bank/cash account to the document's A/R or A/P account. Partial payments are supported: the response's ``payment`` is this call's amount, ``total_paid`` is cumulative across all payments, and ``remaining_balance`` is what is still owed; ``status`` is ``partial`` until the ba…

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 t…

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 …

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 str…

Search transactions by description, memo, notes, num, or amount. Compact format (default): ``DATE<TAB>guid<TAB>Description<TAB>splits``, then the notes when present and a labeled ``num:<number>`` cell when the transaction has a Num. In a book with "Use Split Action Field for Number" on, that cell reads ``tnum:`` (the transaction's T-Num) and each leg's number follows it in the splits as ``#<number>``. 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; pag…

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 name ("Assets:Checking") or %short guid ("%d53d547"). key: Slot key (e.g., "apr", "credit_limit"). GnuCash's own keys (reconcile-info, lot-mgmt, ofx, import-map, placeholder, hidden, …) are refused; use update_account for placeholder. value: Slot value (always stored as string).

Set a budget target for an account. Args: budget_name: Name of the budget. account: Account name ("Assets:Checking") or %short guid ("%d53d547"). amount: Monthly budget amount as string (e.g., "500.00"), as a magnitude for every account type — "5000" on an income account means 5,000 expected in. The server stores GnuCash's natural sign underneath. 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 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.

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 an…

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.

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 clears the document's posted-state metadata. The document returns to "open" state and can be edited or re-posted. Payments are kept, as GnuCash keeps them: the money stays on the books as the party's unapplied payment (``payments_kept`` in the response), and after re-posting the document is settled from it with ``pay_document(from_prepayment=true)``. Do NOT void a payment in order to unpost — the bank line is real. A credit-note ap…

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. The notes it had before the void come back; a transaction that had none keeps the void's note, as in GnuCash. 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 …

Update an existing account's properties. Args: name: Account to update. Account name ("Assets:Checking") or %short guid ("%d53d547"). 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 byt…

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

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 …

Update a scheduled transaction. Any schedule still stored in the pre-native (1.2–1.4.4) shape is converted to GnuCash's template format on this call, nothing posted. A call with no changes is the deliberate one-step conversion of a whole book: run it once after upgrading, before the next GnuCash desktop session. Args: guid: Scheduled transaction GUID (or 8+ char prefix). enabled: Enable or disable. start_date: ``"YYYY-MM-DD"`` to move the schedule's start — what desktop's Scheduled Transaction Editor does. The start is the recurrence's phase anchor, so a m…

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 val…

Update MANY transactions with per-row values (bulk edit). INPUT — ``updates`` is a TSV block: header ``guid`` plus any of ``description``, ``notes``, ``date``, ``num`` (GnuCash's Num column), ``link`` (the document link) — 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/mo An 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``, ``num,link``, …) — e…

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 rathe…

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. An invoice's or bill's posting transaction cannot be voided (it is read-only, as in GnuCash): use unpost_document. A PAYMENT can be voided, e.g. when it bounces. Args: guid: Transaction GUID to void (32-character hex string, or 8+ char prefix) reason: Reason for voiding (required for audit trail) force: Void even though a split is reconciled. Refused without it; …