Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Monarch Money MCP Server show my recent transactions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Read-only access to Monarch Money financial data via two interfaces:
MCP Server — stdio-based, for local use with Claude Desktop / Claude Code
HTTP Proxy — FastAPI REST API, for remote access over Tailscale or any network
Note: This is a personal project, not affiliated with Monarch Money. Built for learning about spending patterns and projections. All access is read-only.
The original monarchmoney Python package (by hammem) is abandoned and broken — Monarch rebranded their API from api.monarchmoney.com to api.monarch.com, causing HTTP 525 errors. This project uses monarchmoneycommunity, the maintained community fork.
Related MCP server: Monarch Money MCP Server
Read-only access to all Monarch Money accounts
Transaction analysis with date filtering and search
Budget tracking and cashflow analysis
Account details including investment holdings
Secure authentication with MFA/TOTP support
Session persistence to minimize re-authentication
HTTP proxy for remote access from any device on your network
Python 3.13+
uv package manager
A Monarch Money account
Clone the repository:
git clone https://github.com/rmarji/monarch-mcp-server.git
cd monarch-mcp-serverInstall dependencies:
uv syncConfigure credentials:
cp .env.example .envEdit .env:
MONARCH_EMAIL=your-email@example.com
MONARCH_PASSWORD=your-monarch-password
MONARCH_MFA_SECRET=your-totp-secret-keyThe MONARCH_MFA_SECRET is the base32 TOTP secret from your authenticator app setup. This is required if your account has 2FA enabled (Monarch may require it by default).
Start the FastAPI proxy:
uv run python monarch_http_proxy.pyThis binds to 0.0.0.0:8765 and is accessible from any device on your network (e.g., over Tailscale).
Method | Path | Query Params | Description |
GET |
| — | Status and auth check |
GET |
| — | All linked accounts |
GET |
| — | Account details (includes holdings for investment accounts) |
GET |
|
| Filtered transactions |
GET |
|
| Search by description/merchant |
GET |
|
| Cashflow summary and details |
GET |
| — | Transaction categories |
curl http://localhost:8765/health
curl http://localhost:8765/accounts
curl http://localhost:8765/transactions?limit=5
curl http://localhost:8765/transactions?start_date=2026-01-01&end_date=2026-01-31
curl "http://localhost:8765/transactions/search?q=grocery"
curl http://localhost:8765/cashflow?start_date=2026-01-01&end_date=2026-03-01The port can be changed via MONARCH_PROXY_PORT in .env (default: 8765).
Start the MCP server:
uv run python run_server.pyAdd to your claude_desktop_config.json:
{
"mcpServers": {
"monarch-money": {
"command": "uv",
"args": ["run", "--directory", "/path/to/monarch-mcp-server", "python", "run_server.py"],
"env": {
"MONARCH_EMAIL": "your-email@example.com",
"MONARCH_PASSWORD": "your-password",
"MONARCH_MFA_SECRET": "your-totp-secret"
}
}
}
}monarch://accounts — All linked accounts
monarch://transactions/recent — Last 100 transactions
monarch://budgets — Budget information with actual vs target
monarch://cashflow/summary — Income, expenses, and savings summary
get_transactions — Transactions with date range filtering
get_account_details — Detailed account info including holdings
get_cashflow_analysis — Cashflow analysis by category and time period
search_transactions — Search by description or merchant
get_categories — All transaction categories
get_institutions — Linked financial institutions
monarch-mcp-server/
├── monarch_http_proxy.py # FastAPI HTTP proxy for remote access
├── monarch_mcp_server.py # MCP server implementation
├── run_server.py # MCP server launcher
├── debug_server.py # Authentication debugging
├── test_api.py # API connection testing
├── tests/
│ └── test_monarch_mcp_server.py
├── pyproject.toml
├── .env.example
└── .gitignoreNo write operations — entirely read-only
Credentials stay local — .env and session files are gitignored
Session caching — authenticates once, reuses session via .mm/mm_session.pickle
MFA/TOTP support — auto-generates 2FA codes from your secret key
No auth on HTTP proxy — relies on network isolation (Tailscale, private network, etc.)
If you see HTTP Code 525, you're likely using the abandoned monarchmoney package. This project requires monarchmoneycommunity:
uv remove monarchmoney
uv add monarchmoneycommunityMonarch Money may require 2FA even if you didn't explicitly enable it. Add MONARCH_MFA_SECRET to your .env.
Delete the cached session to force a fresh login:
rm -rf .mm/uv sync --extra test
uv run pytest tests/ -vMIT License — see LICENSE for details.
This project is not affiliated with Monarch Money. Use at your own risk and ensure compliance with Monarch Money's terms of service.
Get detailed information about specific accounts
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | No | Specific account ID to get details for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says it retrieves details; it does not mention read-only behavior, potential errors, permissions, response format, or any caveats about the returned information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant wording, making it concise and easy to parse. It could be slightly more informative without becoming verbose, but it is appropriately short for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description plus schema cover the essential invocation needs. However, no output schema or return-value details are provided, and the description does not clarify what 'detailed information' includes, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single account_id parameter with a clear description, so the description adds little semantic value. Baseline 3 is appropriate when schema coverage is high and no additional parameter meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get) and resource (specific accounts), making the tool's basic purpose understandable. It is also implicitly distinct from siblings like get_transactions and get_categories, though it does not explicitly differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the tool name and description: use this when detailed information about a specific account is needed. However, there is no explicit guidance about when to prefer it over alternatives or what conditions make it the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed cashflow analysis by category and time period
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | End date for analysis (YYYY-MM-DD) | |
| start_date | No | Start date for analysis (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'get,' which implies a read operation, but it does not disclose what the analysis returns, how dates are handled when omitted, or how category grouping behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary bulk. 'Detailed' adds little value, but overall the structure is clean and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description does not fully explain what the agent should expect back or how optional parameters behave. It lacks the behavioral detail needed for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented with their date format and purpose. The description adds only high-level context about category and time period without deepening parameter semantics, matching the baseline for well-covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: retrieving cashflow analysis, scoped by category and time period. This distinguishes it from sibling tools like get_transactions or get_categories, though it does not explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus the sibling tools. There are no exclusion criteria, alternatives, or context clues beyond the implied purpose of getting cashflow analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all transaction categories configured in the account
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly communicates a read-only retrieval of all configured categories, but it does not disclose return shape, ordering, pagination, or empty-result behavior. The read intent is clear and nothing contradicts the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. It immediately communicates the purpose and necessary scope without wasting tokens.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list call, the description states what is returned (all transaction categories) and the scope (the account). It does not describe the response structure, but there is no output schema and the operation is simple enough that the core details are covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with zero parameters, so there are no parameter semantics to document. The 0-parameter baseline applies, and the description does not need to compensate for missing schema detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a concrete verb ('Get') plus a specific resource ('transaction categories') and states the scope ('configured in the account'). This clearly distinguishes it from siblings like get_transactions or get_institutions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives or when not to use it. The description does not reference any sibling tool or exclusion condition, leaving selection entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all financial institutions linked to Monarch Money
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description serves as the sole behavioral disclosure. It conveys a read-only operation and the scope ('all institutions linked to monarch money'), but offers no details about output format, pagination, ordering, or other runtime behaviors. Sufficient for a simple zero-param read, but nothing beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no wasted words. Every piece of it ('all', 'financial institutions', 'linked to Monarch Money') contributes directly to understanding the tool's scope and behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool, the description covers the essential purpose and scope. The main gap is the lack of an output schema or return-format note, so an agent must infer the response shape; the low complexity makes this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is trivially complete. There are no param semantics to explain, and the description need not add anything; the baseline for zero-param tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('all financial institutions linked to Monarch Money'), clearly distinguishing it from sibling tools that handle transactions, accounts, cashflow, and categories. An agent can immediately identify what this tool does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_account_details or get_transactions. It is clear what the tool retrieves, but not when it is the appropriate choise over it siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get transactions with optional date range filtering
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of transactions to return (default: 100) | |
| end_date | No | End date for transaction search (YYYY-MM-DD) | |
| account_id | No | Optional account ID to filter transactions | |
| start_date | No | Start date for transaction search (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It only says 'Get transactions' without mentioning ordering, pagination, result limits, or whether it returns only summary or full transaction details. The schema mentions a default limit of 100, but the description itself adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. It front-loads the core purpose and the most notable capability, making it easy to scan. For a simple retrieval tool, this is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given four parameters, no output schema, and no annotations, this description is too thin to be complete. It lacks guidance on when to use this over 'search_transactions', what the response looks like, and how parameters like limit and account_id behave. An agent would need to infer too much.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters. The description's mention of 'date range filtering' aligns with start_date and end_date but does not add meaning beyond that, and it remains silent on limit and account_id. The parameter semantics are adequate because the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Get transactions') and highlights a key feature (optional date range filtering). However, it does not distinguish this tool from the sibling 'search_transactions', so an agent cannot tell which one is more appropriate without opening the sibling schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_transactions' or 'get_account_details'. It only mentions optional date range filtering, giving no context about use cases, exclusions, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search transactions by description or merchant
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search term for transaction description or merchant | |
| end_date | No | End date for search (YYYY-MM-DD) | |
| start_date | No | Start date for search (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It only states what is searched and does not mention whether the search is case-insensitive, how date filters interact, whether pagination exists, what result limits apply, or what the response shape looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It is appropriately front-loaded with the key action and target. However, the terseness contributes to the lack of usage guidance and behavioral context, so it does not merit a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with full schema coverage and no output schema, the description is minimally sufficient for basic invocation: the required query term and optional date range are documented. But with no annotations, it lacks enough behavioral context about result expectations and search semantics to be considered complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description restates the query concept from the schema ('description or merchant') but adds no new parameter-level meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') with a clear resource ('transactions') and the exact search dimensions ('description or merchant'). It is immediately distinguishable from sibling tools like get_transactions, get_account_details, and get_categories because it defines the filtering basis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as get_transactions. The description implies 'search by term' but does not state exclusions, prerequisites, or a preferred alternative for listing all transactions without a search term.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_account_detailsget_cashflow_analysisget_categoriesget_institutionsget_transactionssearch_transactionsScored across 6 tools
Most tools target distinct resources: transactions, accounts, categories, institutions, and cashflow are clearly separated. The main ambiguity is between get_transactions and search_transactions, since both retrieve transactions, though one filters by date and the other by merchant/description.
All tools use lowercase snake_case with a clear verb_noun pattern, almost uniformly using get_ for retrieval. The one search_ exception still follows the same verb_noun style, making the naming predictable and consistent.
Six tools is a well-scoped size for a read-only personal finance server. Each tool serves a clear purpose and does not feel padded or sparse.
The tool set covers transaction, account, category, institution, and cashflow data, but significant Monarch Money domains are missing, such as budgets, goals, net worth, or investment holdings. It handles core read-only workflows but leaves notable gaps for broader financial management.
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
Read-only bank access for your AI agent. Connects Claude, ChatGPT, Cursor, Gemini, Codex.
MCP server for Modern Treasury — payment orders, transactions, counterparties and ledgers.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
