Skip to main content

moneywiz-mcp

An MCP server that reads and edits your MoneyWiz ledger on macOS by calling MoneyWiz's own business methods inside the running app. Balances, budgets, category allocations, transfer legs and iCloud sync stay the app's job: this server supplies validated inputs and reads the results back from the live object graph.

Unofficial. Not affiliated with or endorsed by SilverWiz, the makers of MoneyWiz. It is unrelated to the read-only connector built into MoneyWiz. It writes to your real financial data and attaches a debugger-level hook to the app, so read Requirements and Safety first.

Verified against MoneyWiz 2026.44.4 (build 466) on macOS (Apple silicon).

Requirements

  • macOS with MoneyWiz installed from the Mac App Store, running with its ledger open.

  • uv (or any Python 3.11+ installer).

  • Permission to attach to MoneyWiz. MoneyWiz is a hardened-runtime build without get-task-allow. This server has been tested with System Integrity Protection disabled; macOS normally refuses debugger attachment to such apps while SIP is on. The debug authorization must also allow it, once per machine:

    # keep a copy of the current rule so you can restore it later
    security authorizationdb read system.privilege.taskport > ~/taskport-right-backup.plist
    
    sudo DevToolsSecurity -enable
    sudo security authorizationdb write system.privilege.taskport is-developer
    

    The last command lets members of the _developer group attach without a password prompt, which is what makes this work for MCP clients started from a terminal or over SSH. Check membership with id; join with sudo dseditgroup -o edit -a "$USER" -t user _developer. The trade-off: any process running as you can then attach to your other apps. To undo it:

    sudo security authorizationdb write system.privilege.taskport < ~/taskport-right-backup.plist
    

    Without this, every call fails with "macOS denied task_for_pid".

Install

uv tool install moneywiz-mcp      # installs the `moneywiz-mcp` command

or run it on demand with uvx moneywiz-mcp. The first start downloads the Frida runtime, so an installed tool starts faster under MCP clients with short start-up timeouts.

Connect a client

The server speaks MCP over stdio. Use moneywiz-mcp as the command (or uvx with argument moneywiz-mcp).

Claude Code

claude mcp add --scope user moneywiz -- moneywiz-mcp

Codex

codex mcp add moneywiz -- moneywiz-mcp

Claude Desktop and other JSON-configured clients — add to mcpServers (Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "moneywiz": { "command": "uvx", "args": ["moneywiz-mcp"] }
  }
}

GUI apps may not see your shell's PATH; if the command is not found, use the absolute path from which moneywiz-mcp or which uvx.

Then ask the client to call moneywiz_status: it reports the app version, the open database and ledger totals. If MoneyWiz is not running you get a clear error; open the app and retry. The server reconnects by itself after MoneyWiz restarts.

To let the server open MoneyWiz when it is not running, set MONEYWIZ_LAUNCH=1 (claude mcp add --scope user -e MONEYWIZ_LAUNCH=1 moneywiz -- moneywiz-mcp, or "env": {"MONEYWIZ_LAUNCH": "1"} in a JSON config). MoneyWiz is then launched hidden: no window appears and focus stays where it is (click its Dock icon to show it). The first call waits for the ledger and returns in a few seconds. A MoneyWiz you already have open is left as it is, and a ledger behind a passcode still has to be unlocked by hand.

Tools

51 tools, all prefixed moneywiz_:

Area Tools
Status status
Accounts list_accounts, get_account, create_account, update_account, archive_account, delete_account, move_account
Account groups list_account_groups, create_account_group, update_account_group, delete_account_group
Transactions list_transactions, get_transaction, create_transaction, update_transaction, set_transaction_status, delete_transaction
Categories, payees, tags list_categories, list_payees, list_tags, create_category, update_category, reorder_categories, create_payee, create_tag, rename_payee, rename_tag, delete_catalog_object, merge_catalog_objects, catalog_usage
Currencies currency_settings, net_worth, set_default_currency, get_exchange_rate, set_exchange_rate, clear_exchange_rate, set_display_currencies
Investments list_holdings, trade, update_trade, delete_trade, create_holding, delete_holding, set_holding_price, set_holding_shares, set_holding_cost_basis
Loans list_loans, loan_schedule
Budgets, scheduled list_budgets, list_scheduled

What is and is not covered yet is listed in STATUS.md.

Conventions

  • Amounts are decimal strings ("12.50"). Pass positive amounts; the kind (expense, income, transfer, refund, buy/sell) decides the direction. MoneyWiz stores doubles, so output is the shortest exact decimal of the stored value (-26.6, not -26.600000000000001).
  • Dates accept YYYY-MM-DD (local noon, so the day never shifts) or a full ISO 8601 timestamp. Output is local time. List ranges are [start, end).
  • Accounts by id or exact name; categories by id or full path ("Food/Coffee").
  • Category splits are a list that must add up to the amount: [{"category": "Food/Coffee", "amount": "10.00"}, {"category": "Tips", "amount": "2.50"}]. Changing the amount of a single-category transaction moves the allocation with it; a split transaction needs a new list.
  • Foreign currency: give original_amount + original_currency alongside the amount in the account's currency; the rate is derived, or pass exchange_rate.
  • Transfers create, edit and delete both legs together. Across currencies, give transfer_amount (what arrives) or transfer_exchange_rate. MoneyWiz's "transfer between A and B succeeded" dialog is skipped for transfers made through the server; transfers entered in the app still show it.
  • Trades buy or sell by symbol; a first buy creates the holding, and MoneyWiz recalculates shares, cost basis and the account's cash.
  • Unknown payee and tag names are created, as in the app. Unknown categories are rejected.
  • Read balances from accounts. Never sum transaction rows: they include pending and void entries and both legs of each transfer.

Safety

  • Every input is validated before MoneyWiz is touched, because an exception raised inside the app would terminate it.
  • Writes are silent: no dialogs, notifications, sounds, progress overlays or window activation (traced across every write tool on build 466). The one dialog MoneyWiz raises in reaction, "transfer succeeded", is skipped.
  • Writes wait while MoneyWiz has unsaved changes of its own and are refused if they persist for 5 seconds (an open editor), so a half-finished entry is never committed for you.
  • Deleting an account deletes its transactions, so the tool refuses unless you pass the exact transaction count it reports. Archiving is usually better.
  • Categories, payees, tags and holdings that are still referenced cannot be deleted; merge them instead.
  • Each call saves on its own, like an edit in the app; several calls are not one transaction.
  • Saved locally is not synced: MoneyWiz uploads to iCloud on its own schedule.
  • Avoid editing the same records in MoneyWiz while a tool call runs.

How it works

MCP client ──stdio──▶ moneywiz-mcp (Python)
                        │ domain modules: accounts, transactions, catalog, …
                        ▼
                      Frida session ──▶ agent inside MoneyWiz (main queue)
                                           ├─ NSFetchRequest over the live context
                                           └─ MoneyWizManager business methods

One small, domain-free agent resolves classes, selectors and properties by name, checks each method's type encoding against a recorded signature table before calling it, and runs everything on the app's main queue. All business rules live in Python. See ARCHITECTURE.md.

Development

git clone https://github.com/kyledh/moneywiz-mcp && cd moneywiz-mcp
uv sync                                   # .venv with the package (editable) and pytest
uv run pytest -q                          # offline tests
MONEYWIZ_LIVE_TESTS=1 uv run pytest -q tests/test_live.py

The live suite writes to the real ledger: it creates everything under an MCP-TEST- prefix, removes it again (also after failures), and asserts that account, transaction, category, payee and tag counts, and the positions of your accounts, groups and categories, end where they started.

The compiled agent is checked in at src/moneywiz_mcp/agent.js. After editing agent/src/agent.js, rebuild it:

(cd agent && npm ci)                      # once: frida-objc-bridge
uv run scripts/build_agent.py

License

MIT, see LICENSE. The bundled agent includes frida-objc-bridge; see THIRD_PARTY_NOTICES.md.

Metadata

Release files for moneywiz-mcp 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for moneywiz-mcp 0.1.1
File Size Uploaded Provenance Actions
moneywiz_mcp-0.1.1.tar.gz 112.6 kB With provenance Details for moneywiz_mcp-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for moneywiz-mcp 0.1.1
File Interpreter ABI Platform Actions
moneywiz_mcp-0.1.1-py3-none-any.whl Python 3 none any Details for moneywiz_mcp-0.1.1-py3-none-any.whl

Total release size: 209.6 kB

Release files / moneywiz_mcp-0.1.1.tar.gz

Download URL moneywiz_mcp-0.1.1.tar.gz
Size 112.6 kB
Tags Source
SHA-256 checksum
How to use checksums
f29548f8a3a978f922d235b85e081437c1ec918603d3060b4b24dc0350d9e48c
BLAKE2b-256 checksum
How to use checksums
81947a1befc1f00840b8adf80c38779ae26662f5faddcf31ea8d4192ea1ce411
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / moneywiz_mcp-0.1.1-py3-none-any.whl

Download URL moneywiz_mcp-0.1.1-py3-none-any.whl
Size 97.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d6ad5ae9122f6def1f8423fde86f74e6f2082378af55315ad8a34ae69ddfbc93
BLAKE2b-256 checksum
How to use checksums
e7105b95256d357967d34abffbe7bbdcd92aa5fd7fb18d87b94694950953b570
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for moneywiz-mcp 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for moneywiz_mcp-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page