Monarch Money MCP Server
Use an AI assistant to read and update your Monarch Money accounts, transactions, and budgets through MCP.
Why this fork?
This rewrite adds these tools to colvint's original server:
- Search and bulk edits:
search_transactions finds merchants or keywords; update_transactions_bulk edits up to 100 transactions per call, five at a time, with per-item results.
- Spending analysis:
get_spending_summary groups totals by category, account, or month; analyze_spending_patterns compares months.
- One-call overview:
get_complete_financial_overview combines accounts, budgets, cashflow, transactions, and categories.
- Splits and recurring schedules: read and replace transaction splits, list every recurring stream with its next forecast, view scheduled occurrences, and edit merchant-wide recurrence.
- Cleanup tools: find possible duplicates, delete transactions, merge merchants, and tag transactions.
- Net worth and goals: daily net worth or monthly balances by account type, credit score history, and savings goals.
Unlike the original and keithah's enhanced Python fork, this server also provides:
- Typed results: structured output with
outputSchema, plus a text fallback.
- MCP resources and prompts: account/category/institution resources, per-account holdings/history templates, and guided prompts with argument completion.
- Assistant-friendly calls: compact transaction/category records, natural-language dates, read/write labels, and progress on batch analysis.
Comparison checked September 14, 2026. Other forks overlap on financial tools; the enhanced Python fork exposes a broader library API. This project focuses on analysis workflows and MCP integration, not exposing every API method. See the tool catalog.
Monarch also relaunched its own official MCP connector on October 21, 2026. It uses OAuth instead of your password, has weekly usage limits, and skips Finicity-connected accounts. Try it first if it covers what you need; this server runs locally and covers more write and analysis tools.
Setup
Install uv, then configure your MCP client to run uvx monarch-mcp-jamiew. You'll need your Monarch email and password, plus an MFA secret for TOTP-based 2FA.
The latest release is on PyPI. Changes listed under Unreleased in the changelog need a source install until the next release.
Standard config
For clients with an mcpServers config:
{
"mcpServers": {
"monarch-money": {
"command": "uvx",
"args": ["monarch-mcp-jamiew"],
"env": {
"MONARCH_EMAIL": "your-email@example.com",
"MONARCH_PASSWORD": "your-password",
"MONARCH_MFA_SECRET": "your-mfa-secret-key"
}
}
}
}
Claude Desktop
Add the monarch-money entry from the standard config to your config file's mcpServers object (create the file if needed):
- macOS:
~/Library/Application\ Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
Then fully quit and reopen Claude Desktop.
Claude Code
claude mcp add monarch-money \
-e MONARCH_EMAIL=your-email@example.com \
-e MONARCH_PASSWORD=your-password \
-e MONARCH_MFA_SECRET=your-mfa-secret-key \
-- uvx monarch-mcp-jamiew
Add -s user to make it available across all your projects. Verify with claude mcp list.
Codex CLI
codex mcp add monarch-money \
--env MONARCH_EMAIL=your-email@example.com \
--env MONARCH_PASSWORD=your-password \
--env MONARCH_MFA_SECRET=your-mfa-secret-key \
-- uvx monarch-mcp-jamiew
Or add the equivalent block to ~/.codex/config.toml:
[mcp_servers.monarch-money]
command = "uvx"
args = ["monarch-mcp-jamiew"]
env = { MONARCH_EMAIL = "your-email@example.com", MONARCH_PASSWORD = "your-password", MONARCH_MFA_SECRET = "your-mfa-secret-key" }
.mcp.json (project-scoped)
For Claude Code's project scope, save the standard config as .mcp.json in your project root. Keep credential-bearing files out of version control.
Hermes
Add to ~/.hermes/config.yaml under mcp_servers:, then /reload-mcp (or restart Hermes):
mcp_servers:
monarch-money:
command: uvx
args: ["monarch-mcp-jamiew"]
env:
MONARCH_EMAIL: "your-email@example.com"
MONARCH_PASSWORD: "your-password"
MONARCH_MFA_SECRET: "your-mfa-secret-key"
OpenClaw
Add the standard config to ~/.openclaw/openclaw.json under mcpServers, then restart the gateway.
Any other MCP client (Cursor, VS Code, Windsurf, Cline, Zed, …)
Set up a local stdio MCP server with command uvx, argument monarch-mcp-jamiew, and the credentials above. Follow your client's config format.
Not sure how? Tell your agent:
Install the Monarch Money MCP server from https://github.com/jamiew/monarch-mcp. The PyPI package is monarch-mcp-jamiew, run via uvx monarch-mcp-jamiew. It needs MONARCH_EMAIL, MONARCH_PASSWORD, and MONARCH_MFA_SECRET for TOTP-based 2FA.
From source (development)
Source installs use a pinned monarchmoneycommunity commit:
git clone https://github.com/jamiew/monarch-mcp
cd monarch-mcp
uv sync --locked
Then point your client at the local copy with absolute paths (find them with which uv and pwd):
{
"mcpServers": {
"monarch-money": {
"command": "/abs/path/to/uv",
"args": ["--directory", "/abs/path/to/monarch-mcp", "run", "python", "server.py"],
"env": {
"MONARCH_EMAIL": "your-email@example.com",
"MONARCH_PASSWORD": "your-password",
"MONARCH_MFA_SECRET": "your-mfa-secret-key"
}
}
}
}
NOTE
The claude mcp add and codex mcp add commands can save credentials in shell history. Edit the client's config directly to avoid that, and protect the config file.
Getting your MFA secret
- Go to Monarch Money settings and enable 2FA
- When shown the QR code, look for "Can't scan?" or "Enter manually"
- Copy the TOTP secret key, not the rotating six-digit code
- Use this as your
MONARCH_MFA_SECRET
The server exposes these 42 tools.
| Tool | Description |
|---|
get_accounts | List accounts with balances |
get_transactions | Transactions with date/account/category, pending/posted, and needs-review filtering; returns total_count and next_offset |
search_transactions | Search by merchant name or keyword, with the same filters and paging |
get_transaction_categories | Category list (compact by default) |
get_transaction_rules | Page through compact automation rules in priority order |
create_transaction_rule | Create a rule that matches merchant, statement text, or amount |
update_transaction_rule | Edit a rule, and optionally run it on past transactions |
delete_transaction_rule | Delete a rule; transactions it already changed stay as they are |
get_household_members | Household members and IDs for ownership updates |
create_transaction | Create a manual transaction |
delete_transaction | Permanently delete a transaction |
update_transaction | Update transaction fields or assign ownership |
update_transactions_bulk | Update fields or owners with per-item success/failure |
get_transaction_splits | Read a transaction's splits |
get_transaction_details | Resolve split parent and leg IDs; return split flags, category ID, and resolved transaction ID |
update_transaction_splits | Replace all splits; an empty list removes them |
get_budgets | Budget data and spending analysis |
get_cashflow | Income and expense analysis |
get_account_holdings | Investment holdings for an account (requires account_id) |
get_all_holdings | Holdings grouped by brokerage account; excludes other account types |
get_account_history | Paginated balance history with inclusive, locally applied ISO date bounds |
get_institutions | Linked financial institutions |
get_recurring_transactions | Scheduled occurrences within a date range |
get_recurring_streams | Every recurring stream with its merchant ID and next forecast |
update_recurring_transaction | Change a merchant's recurring schedule |
get_merchants | Page through merchants with transaction and rule counts |
delete_merchant | Delete a merchant, optionally moving its transactions to another merchant |
get_transaction_tags | List household tags |
create_transaction_tag | Create a tag |
set_transaction_tags | Replace a transaction's tags; an empty list removes them |
set_budget_amount | Set a category's monthly budget, optionally for future months too |
get_savings_goals | Savings goals with targets, balances, and progress |
set_savings_goal_budget_amount | Set a goal's planned monthly contribution |
create_manual_account | Create a manually tracked account; valid types are in the accounts://types resource |
update_account | Rename an account, set its balance, or change net worth and visibility settings |
refresh_accounts | Trigger account data refresh |
get_net_worth_history | Daily net worth, or monthly balances by account type |
get_credit_score_history | Household credit score snapshots |
find_duplicate_transactions | Possible duplicates: same date, amount, statement name, and account |
get_spending_summary | Spending aggregated by category, account, or month, excluding transfers |
get_complete_financial_overview | Compact account, transaction, budget, and cashflow summaries; full sections opt-in |
analyze_spending_patterns | Monthly trends and a forecast from the last three complete months |
Spending totals skip transfers, such as credit card payments, so money moving between your own accounts isn't counted twice. Each result reports transfers_excluded.
Dates accept ISO dates or natural language. A month or year, such as 2024-02 or last month, covers the whole period: as an end_date it means the period's last day.
Use is_pending=True for pending transactions or False for posted ones; omit it
for both. Single and bulk updates accept owner_user_id from get_household_members.
An empty string sets Shared ownership; omitted/null leaves ownership unchanged.
Assignments override inherited ownership. Inspect ownedByUser with verbose=True;
the update response does not include it.
Rules default to 25 per page (maximum 100); history defaults to 100 (maximum 1,000).
Use limit, offset, and returned next_offset to continue; total_count covers all
matching records. Rule details remain available with verbose=True.
A rule can set a category, merchant name, tags, or review status. It can also hide
transactions from reports. Each rule must look for a merchant name, statement text, or
amount. Monarch ignores edits to rules that don't.
When you edit a rule, anything you leave out stays the same. To clear a value, pass
[] or "". Monarch replaces the whole rule on every edit, so the server sends back
the full rule with your changes. That keeps settings the tools can't edit, such as
owners, goals, and splits.
apply_to_existing_transactions=True also changes past transactions that match. That
is hard to undo, so check what matches with search_transactions first.
Overviews and spending analysis default to compact summaries; verbose=True restores
full sections. Transaction samples are capped at 500 and 2,000 respectively, even
in verbose mode. Check batch_metadata.transactions_truncated before treating
totals as complete; null means the upstream count was unavailable.
Recurring transactions
get_recurring_transactions(start_date, end_date) returns a forecast, not posted history.
Dates accept ISO or natural language. No dates selects this month; one date fills
the missing bound from that month. For the full list of recurring streams with each
merchant ID, use get_recurring_streams; active_only=False adds inactive ones.
Occurrences include stream, account, category, and a matched transactionId when
available. isPast does not mean paid. Use get_transactions(is_recurring=True)
for recorded transactions; do not count forecasts and posted matches twice.
update_recurring_transaction changes a merchant-wide schedule, not one occurrence.
Use stream.merchant.id, not stream.id or transactionId, and the current merchant
name to avoid renaming it. Pass only settings to change: frequency, base_date,
amount, is_recurring, or is_active. Omitted settings stay unchanged.
Use Monarch's frequency and signed amount. This does not cancel subscriptions,
move money, or create posted transactions.
get_transactions and search_transactions return compact records by default:
{
"id": "txn_123",
"date": "2025-03-15",
"amount": -12.50,
"merchant": "Corner Deli",
"plaidName": "CORNER DELI NYC",
"category": "Restaurants & Bars",
"categoryId": "cat_001",
"account": "Main Credit Card",
"needsReview": true
}
pending appears only when true; notes appears only when nonempty. Set verbose=True on get_transactions or search_transactions for full transaction details, or on get_transaction_categories for full category details.
Session management
Sessions are cached in ~/.monarch-mcp/ for faster subsequent logins (override the location with the MONARCH_SESSION_DIR env var). If you hit auth issues:
- Delete
~/.monarch-mcp/session.pickle to clear the cached session
- Set
MONARCH_FORCE_LOGIN=true in your env config to force a fresh login
- Make sure your system clock is accurate (required for TOTP)
Development
Local setup
For live checks, create a .env file (git-ignored) and load it explicitly with uv --env-file:
MONARCH_EMAIL="your-email@example.com"
MONARCH_PASSWORD="your-password"
MONARCH_MFA_SECRET="YOUR_TOTP_SECRET_KEY"
Tests
uv run pytest tests/ -v
MONARCH_RUN_INTEGRATION=true uv run --env-file .env pytest tests/test_integration.py -v
uv run --env-file .env scripts/health_check.py
Integration tests share one fresh login to avoid MFA reuse and login throttling. They never load .env themselves or read/write saved sessions.
CI checks
Run the same checks as CI:
uv run python scripts/ci.py
Releasing
Use /release to bump pyproject.toml, commit, tag vX.Y.Z, push, and create a GitHub release. The publish workflow publishes to PyPI and the MCP Registry through OIDC, setting server.json versions from the tag.
Log analysis
Measure tool calls and timing. Output sizes need MONARCH_LOG_RESULT_SIZE=true in the server's env, since measuring serializes each result a second time.
uv run scripts/analyze_logs.py
uv run scripts/analyze_logs.py --json
uv run scripts/eval_session.py snapshot
uv run scripts/eval_session.py analyze
Security
Warning: This server uses unofficial Monarch Money API access. Your credentials grant full account access, including writes.
- The server runs locally and returns requested financial data to your MCP client. Review the client's privacy settings and tool approvals.
- Protect your password and MFA secret. The TOTP secret enables ongoing code generation.
- Session files in
~/.monarch-mcp/ contain auth tokens. Protect them and any custom MONARCH_SESSION_DIR.
- Logs can include financial input values and error details. Review them before sharing.
- Never commit credential-bearing
.env, .mcp.json, or client config files.
- Monarch Money may change or restrict unofficial API access at any time.
Credits
Forked from colvint/monarch-money-mcp. API access uses bradleyseanf/monarchmoneycommunity, based on hammem/monarchmoney. Source installs pin a commit; PyPI installs use the published library.
Contributors: @caseypugh (transaction splits), @seanperkins (spending summary pagination), @rajatbhagat (setup docs), @samyk (transaction rules), and @prerak-proof (transaction details).