Skip to content
Back to search

monarch-mcp-server

MCP Server for use with Monarch Money

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/robcerda--monarch-mcp-server/badge.svg)](/listings/robcerda--monarch-mcp-server)

HTML

<a href="/listings/robcerda--monarch-mcp-server"><img src="/api/listings/robcerda--monarch-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

If you plan to use this MCP server locally / on the same computer as Claude Desktop or similar, start with the [`Local Installation` section](#1-local-installation).

For other deployment scenarios - like containerized deployment or cloud hosting - start with the [`Containerized Deployment` section](#containerized-deployment).

1. Local Installation

1. **Clone this repository**:

   git clone https://github.com/robcerda/monarch-mcp-server.git
   cd monarch-mcp-server

2. **Install dependencies**:

**Using `uv`** (recommended):

   uv sync --locked

`--locked` installs exactly what `uv.lock` pins, verified against the hashes it records, and refuses to re-resolve. Without it, `uv sync` is free to pick up whatever versions happen to satisfy the ranges today.

**Using `pip`**:

   pip install -r requirements-lock.txt --require-hashes
   pip install -e . --no-deps

`requirements-lock.txt` is generated from `uv.lock` and pins every transitive dependency with hashes, so `--require-hashes` gives the pip path the same guarantee as the uv one. `--no-deps` on the second command stops pip re-resolving what the first command just pinned.

`pip install -r requirements.txt` still works and installs exactly the same set. That file is now a one line include of `requirements-lock.txt`, kept so existing setups and scripts do not break. The pins moved out of it because a root `requirements.txt` gets resolved as an independent manifest, which had started producing a pinned set that disagreed with `uv.lock`.

3. **Configure Claude Desktop**: Add this to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

   {
     "mcpServers": {
       "Monarch Money": {
         "command": "/opt/homebrew/bin/uv",
         "args": [
           "run",
           "--locked",
           "--project",
           "/path/to/your/monarch-mcp-server",
           "monarch-mcp-server"
         ]
       }
     }
   }

**Important**: Replace `/path/to/your/monarch-mcp-server` with your actual path!

`uv run --locked --project` resolves dependencies from the repo's `uv.lock`, and `monarch-mcp-server` is the console script declared in `pyproject.toml`. `--locked` matters: without it, a lockfile that has drifted from `pyproject.toml` is silently re-resolved against PyPI and the recorded hashes stop being enforced. With it, drift is a startup error. Earlier versions of this README used `uv run --with 'mcp[cli]'`, which builds a fresh unpinned environment on every launch and silently picks up whatever the newest release happens to be. That is what broke every install when the MCP SDK published 2.0, and the client only reported it as the server disconnecting. Pinning the launch to the lockfile means a new upstream release cannot change what your server runs.

4. **Restart Claude Desktop**

**OR**

3. **Configure Claude Code** (CLI): Add this to your Claude Code configuration file:

**Global** (all projects):

**macOS/Linux**: `~/.claude.json`

**Windows**: `%USERPROFILE%\.claude.json`

   {
     "mcpServers": {
       "Monarch Money": {
         "command": "/opt/homebrew/bin/uv",
         "args": [
           "run",
           "--locked",
           "--project",
           "/path/to/your/monarch-mcp-server",
           "monarch-mcp-server"
         ]
       }
     }
   }

**Project-level** (specific directory):

Create `.mcp.json` in your project directory:

   {
     "Monarch Money": {
       "command": "/opt/homebrew/bin/uv",
       "args": [
         "run",
         "--locked",
         "--project",
         "/path/to/your/monarch-mcp-server",
         "monarch-mcp-server"
       ]
     }
   }

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 877 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/robcerda-monarch-mcp-server-badge.png)](https://mseep.ai/app/robcerda-monarch-mcp-server)
  2. # Monarch Money MCP Server
  3. A Model Context Protocol (MCP) server for integrating with the Monarch Money personal finance platform. This server provides seamless access to your financial accounts, transactions, budgets, and analytics through Claude Desktop and Claude Code.
  4. My MonarchMoney referral: https://www.monarchmoney.com/referral/ufmn0r83yf?r_source=share
  5. **Built with the [MonarchMoneyCommunity Python library](https://github.com/bradleyseanf/monarchmoneycommunity)** - An actively maintained community fork of the Monarch Money API with full MFA support.
  6. <a href="https://glama.ai/mcp/servers/@robcerda/monarch-mcp-server">
  7. <img width="380" height="200" src="https://glama.ai/mcp/servers/@robcerda/monarch-mcp-server/badge" alt="monarch-mcp-server MCP server" />
  8. </a>
  9. ## 🚀 Quick Start
  10. If you plan to use this MCP server locally / on the same computer as Claude Desktop or similar, start with the [`Local Installation` section](#1-local-installation).
  11. For other deployment scenarios - like containerized deployment or cloud hosting - start with the [`Containerized Deployment` section](#containerized-deployment).
  12. ### 1. Local Installation
  13. 1. **Clone this repository**:
  14. ```bash
  15. git clone https://github.com/robcerda/monarch-mcp-server.git
  16. cd monarch-mcp-server
  17. ```
  18. 2. **Install dependencies**:
  19. **Using `uv`** (recommended):
  20. ```bash
  21. uv sync --locked
  22. ```
  23. `--locked` installs exactly what `uv.lock` pins, verified against the
  24. hashes it records, and refuses to re-resolve. Without it, `uv sync` is free
  25. to pick up whatever versions happen to satisfy the ranges today.
  26. **Using `pip`**:
  27. ```bash
  28. pip install -r requirements-lock.txt --require-hashes
  29. pip install -e . --no-deps
  30. ```
  31. `requirements-lock.txt` is generated from `uv.lock` and pins every transitive
  32. dependency with hashes, so `--require-hashes` gives the pip path the same
  33. guarantee as the uv one. `--no-deps` on the second command stops pip
  34. re-resolving what the first command just pinned.
  35. `pip install -r requirements.txt` still works and installs exactly the same
  36. set. That file is now a one line include of `requirements-lock.txt`, kept so
  37. existing setups and scripts do not break. The pins moved out of it because a
  38. root `requirements.txt` gets resolved as an independent manifest, which had
  39. started producing a pinned set that disagreed with `uv.lock`.
  40. 3. **Configure Claude Desktop**:
  41. Add this to your Claude Desktop configuration file:
  42. **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  43. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  44. ```json
  45. {
  46. "mcpServers": {
  47. "Monarch Money": {
  48. "command": "/opt/homebrew/bin/uv",
  49. "args": [
  50. "run",
  51. "--locked",
  52. "--project",
  53. "/path/to/your/monarch-mcp-server",
  54. "monarch-mcp-server"
  55. ]
  56. }
  57. }
  58. }
  59. ```
  60. **Important**: Replace `/path/to/your/monarch-mcp-server` with your actual path!
  61. `uv run --locked --project` resolves dependencies from the repo's
  62. `uv.lock`, and `monarch-mcp-server` is the console script declared in
  63. `pyproject.toml`. `--locked` matters: without it, a lockfile that has
  64. drifted from `pyproject.toml` is silently re-resolved against PyPI and the
  65. recorded hashes stop being enforced. With it, drift is a startup error.
  66. Earlier versions of this README used `uv run --with 'mcp[cli]'`, which
  67. builds a fresh unpinned environment on every launch and silently picks up
  68. whatever the newest release happens to be. That is what broke every install
  69. when the MCP SDK published 2.0, and the client only reported it as the
  70. server disconnecting. Pinning the launch to the lockfile means a new
  71. upstream release cannot change what your server runs.
  72. 4. **Restart Claude Desktop**
  73. **OR**
  74. 3. **Configure Claude Code** (CLI):
  75. Add this to your Claude Code configuration file:
  76. **Global** (all projects):
  77. **macOS/Linux**: `~/.claude.json`
  78. **Windows**: `%USERPROFILE%\.claude.json`
  79. ```json
  80. {
  81. "mcpServers": {
  82. "Monarch Money": {
  83. "command": "/opt/homebrew/bin/uv",
  84. "args": [
  85. "run",
  86. "--locked",
  87. "--project",
  88. "/path/to/your/monarch-mcp-server",
  89. "monarch-mcp-server"
  90. ]
  91. }
  92. }
  93. }
  94. ```
  95. **Project-level** (specific directory):
  96. Create `.mcp.json` in your project directory:
  97. ```json
  98. {
  99. "Monarch Money": {
  100. "command": "/opt/homebrew/bin/uv",
  101. "args": [
  102. "run",
  103. "--locked",
  104. "--project",
  105. "/path/to/your/monarch-mcp-server",
  106. "monarch-mcp-server"
  107. ]
  108. }
  109. }
  110. ```
  111. **If installed via `pip`** instead of `uv`, use:
  112. ```json
  113. {
  114. "command": "python",
  115. "args": ["/path/to/your/monarch-mcp-server/src/monarch_mcp_server/server.py"]
  116. }
  117. ```
  118. **Important**: Replace `/path/to/your/monarch-mcp-server` with your actual path!
  119. 4. **Restart Claude Code**
  120. ### 2. One-Time Authentication Setup
  121. **Important**: For security and MFA support, authentication is done outside of Claude.
  122. Open a terminal and run:
  123. ```bash
  124. cd /path/to/your/monarch-mcp-server
  125. uv run python login_setup.py # or: python login_setup.py
  126. ```
  127. The script offers three login paths:
  128. #### Option 1 (recommended): Session cookies from your browser
  129. Long-lived sessions, supports SSO accounts, and sidesteps Cloudflare CAPTCHA gates on programmatic login. Steps:
  130. 1. Log in to https://app.monarch.com in Chrome or Firefox.
  131. 2. Open DevTools (F12) → Network tab.
  132. 3. Click any request whose Name starts with `graphql` (or any request to `api.monarch.com`).
  133. 4. Scroll to Request Headers, find the `cookie:` header, and copy the full value.
  134. 5. Save it to the cookie file for your platform (recommended), then re-run the script — it reads the file automatically:
  135. **macOS / Linux** — `~/.config/monarch-mcp/cookie.txt` (respects `$XDG_CONFIG_HOME`):
  136. ```bash
  137. mkdir -p ~/.config/monarch-mcp
  138. # paste the cookie value into the file with your editor, then:
  139. chmod 600 ~/.config/monarch-mcp/cookie.txt
  140. ```
  141. **Windows** — `%APPDATA%\monarch-mcp\cookie.txt`:
  142. ```powershell
  143. New-Item -ItemType Directory -Force "$env:APPDATA\monarch-mcp" | Out-Null
  144. notepad "$env:APPDATA\monarch-mcp\cookie.txt" # paste the cookie value, save, close
  145. ```
  146. Files under your user profile are already ACL-restricted to your account on Windows; no `chmod` equivalent is needed for typical single-user machines.
  147. To use a different location on any platform, set the `MONARCH_MCP_COOKIE_FILE` environment variable to the full path.
  148. Alternatively, paste the value at the interactive prompt — but note that
  149. POSIX terminals silently truncate pasted input at the canonical-mode
  150. buffer limit (`MAX_CANON`, 1024 bytes on macOS/Linux), and real Monarch
  151. cookie headers are usually longer than that, so the prompt path fails
  152. with a confusing auth error for most users. The cookie file has no
  153. length limit and survives repo updates.
  154. The script verifies the cookies against the live API before saving them to your system keyring. The cookie file is only read at setup time; the running MCP server uses the keyring session.
  155. #### Option 2: Email and password
  156. Standard interactive login. The script handles:
  157. - Email verification codes (Monarch may send one for a new device session even when MFA is off).
  158. - TOTP MFA codes if you have MFA enabled.
  159. - Cloudflare CAPTCHA detection: if Monarch blocks programmatic login, the script tells you to switch to option 1.
  160. The resulting long-lived session token is saved to your system keyring.
  161. #### Option 3: Legacy session token paste
  162. Kept for users with an existing token captured before the May 2026 API change. Monarch may no longer accept token-only auth on the GraphQL endpoint; if the verification call returns 401, fall back to option 1.
  163. ### 3. Start Using
  164. Once authenticated, use these tools directly in Claude Desktop or Claude Code:
  165. - `get_accounts` - View all your financial accounts
  166. - `get_transactions` - Recent transactions with filtering
  167. - `get_budgets` - Budget information and spending
  168. - `get_cashflow` - Income/expense analysis
  169. ## Containerized Deployment
  170. The Docker image uses Astral's uv/Python 3.12 slim base, installs from `uv.lock`,
  171. and defaults to HTTP on `0.0.0.0:8000` inside the container.
  172. ### Build the image
  173. ```bash
  174. docker build -t monarch-mcp-server .
  175. ```
  176. ### Authenticate
  177. Authenticate once using a persistent session volume:
  178. ```bash
  179. docker run --rm -it \
  180. -v monarch-session:/home/app/.monarch-mcp-server \
  181. monarch-mcp-server python login_setup.py
  182. ```
  183. The login script supports a cookie file for browser-cookie authentication.
  184. To use it, also mount your cookie file at `/tmp/monarch-cookie.txt:ro` and set `MONARCH_MCP_COOKIE_FILE=/tmp/monarch-cookie.txt` for the login container.
  185. The file must be readable by the container's uid `10001`, which conflicts with
  186. the `chmod 600` advised for the local flow: a 0600 file owned by your host user
  187. is not readable by uid 10001 inside the container. For the container login,
  188. either `chown 10001 cookie.txt` and keep it at 0600, or run the login container
  189. with `--user $(id -u)` so it reads the file as you. Do not widen it to 0644.
  190. Delete the file once the login has succeeded.
  191. Once saved, the session volume is sufficient for normal server launches.
  192. > [!IMPORTANT]
  193. > **The session is stored unencrypted in that volume.** This differs from a
  194. > local install, and the difference is easy to miss.
  195. >
  196. > On macOS and Windows the session goes to the system keyring. A container has
  197. > no keyring backend, so storage falls back to a file. That file is encrypted
  198. > at rest only on Windows, through DPAPI, so in a Linux container it holds your
  199. > Monarch session in plaintext. Permissions are as tight as a file can be, mode
  200. > 0600 inside a 0700 directory owned by uid 10001, but file permissions do not
  201. > help against anyone who can reach the volume from outside the container.
  202. >
  203. > Treat `monarch-session` as a secret. It can be read by root on the Docker
  204. > host, by any user in the `docker` group, by any other container that mounts
  205. > the same volume, by `docker cp` and `docker exec`, and by anything that backs
  206. > up `/var/lib/docker`. A Monarch session grants full read and write access to
  207. > your accounts and does not expire on its own, so a copy of this volume is a
  208. > lasting credential. Back it up only to somewhere you would keep a password,
  209. > and delete the volume with `docker volume rm monarch-session` when you are
  210. > done with it.
  211. >
  212. > The cookie file described below is the same kind of secret. Delete it once
  213. > the login has succeeded; it is only needed for that one run.
  214. ### Start the HTTP server
  215. Reuse the session volume when starting the server:
  216. ```bash
  217. $ docker run -d --name monarch-mcp --restart unless-stopped \
  218. -p 127.0.0.1:8000:8000 \
  219. -v monarch-session:/home/app/.monarch-mcp-server \
  220. monarch-mcp-server
  221. ```
  222. Connect your MCP client to `http://127.0.0.1:8000/mcp` using Streamable HTTP.
  223. See [HTTP transport configuration](#http-transport-configuration) for all settings.
  224. The image runs in [read only mode](#strongest-option-read-only-mode) by default,
  225. because the HTTP transport does not authenticate callers. Anything that can
  226. reach the port would otherwise be able to call `monarch_logout`, or
  227. `monarch_login_with_token` to swap your saved session for another Monarch
  228. account. Login happens in the separate `login_setup.py` container above, so the
  229. running server never needs those tools.
  230. To allow writes, add `-e MONARCH_MCP_READ_ONLY=0`. That registers every
  231. mutating tool, including the login and logout tools, on the listening socket,
  232. so only do it where every client that can reach the port is trusted.
  233. ### Connect from another machine
  234. > [!WARNING]
  235. > This MCP server is not multi-user or multi-account. All connected clients share the same session and permissions.
  236. > Ensure that you understand the security implications before exposing the server to a network.
  237. To connect from another machine, **put the container behind an authenticated HTTPS reverse proxy or a private network with access controls**, publish the port on the appropriate interface, and allow the hostname used by the client:
  238. ```bash
  239. docker run -d --name monarch-mcp --restart unless-stopped \
  240. -p 127.0.0.1:8000:8000 \
  241. -e MONARCH_MCP_ALLOWED_HOSTS=mcp.example.com \
  242. -v monarch-session:/home/app/.monarch-mcp-server \
  243. monarch-mcp-server
  244. ```
  245. Here a reverse proxy on the Docker host forwards `https://mcp.example.com/mcp` to `http://127.0.0.1:8000/mcp`, preserving the public Host header.
  246. The proxy must support streaming responses without buffering.
  247. For direct access on a private network, allow the client's Host value including the port, such as `server.lan:8000`.
  248. Let me stress this point: **This is a single-account server!**
  249. All connected clients share the *same* saved Monarch session and permissions, including enabled write tools.
  250. Basic Host/origin checks protect against DNS rebinding; they do not authenticate callers.
  251. Use one server and session volume per Monarch account if you need to.
  252. ### Use STDIO instead
  253. To run the Docker image over STDIO instead:
  254. ```bash
  255. docker run --rm -i \
  256. -e MONARCH_MCP_TRANSPORT=stdio \
  257. -v monarch-session:/home/app/.monarch-mcp-server \
  258. monarch-mcp-server
  259. ```
  260. ## HTTP Transport Configuration
  261. The server supports MCP Streamable HTTP at `/mcp` but only when explicitly selected:
  262. ```bash
  263. uv run --locked monarch-mcp-server --transport http --host 127.0.0.1 --port 8000
  264. ```
  265. Connect an MCP client using Streamable HTTP to `http://127.0.0.1:8000/mcp`.
  266. | Setting | CLI flag | Environment variable | Default outside Docker |
  267. | ---------------------------------- | ------------------------------- | ----------------------------------------------- | ---------------------------------------------- |
  268. | Transport | `--transport` | `MONARCH_MCP_TRANSPORT` | `stdio` (`http` aliases `streamable-http`) |
  269. | Listen address | `--host` | `MONARCH_MCP_HOST` | `127.0.0.1` |
  270. | Listen port | `--port` | `MONARCH_MCP_PORT` | `8000` |
  271. | Additional allowed Host headers | `--allowed-host` (repeatable) | `MONARCH_MCP_ALLOWED_HOSTS` (comma-separated) | None; loopback hosts are always allowed |
  272. | Additional allowed browser Origins | `--allowed-origin` (repeatable) | `MONARCH_MCP_ALLOWED_ORIGINS` (comma-separated) | None; HTTP loopback origins are always allowed |
  273. CLI flags override their environment settings.
  274. A Host given without a port also allows that host with any port, so
  275. `--allowed-host mcp.example.com` accepts both `mcp.example.com` and
  276. `mcp.example.com:8443`. Give a host with a port, such as
  277. `--allowed-host mcp.example.com:8443`, to allow only that port. Values are
  278. matched lowercased, with a trailing dot ignored.
  279. Host entries include the port when clients send one; `server.lan:*` allows any port.
  280. Origin entries include the scheme, for example `https://client.example.com`.
  281. Clients without an Origin header are supported.
  282. Browser clients may additionally require CORS handling at the reverse proxy.
  283. ## Meta Muse
  284. Works great with Meta Muse, Meta's AI assistant, alongside Claude Desktop and
  285. Claude Code. Muse speaks MCP, so it connects the same way as any other client:
  286. give it the stdio launch command from the installation section, or point it at
  287. the Streamable HTTP endpoint if you are running the container.
  288. Using Muse? Ask it to install this server from this repo. Muse can handle the
  289. install and register the server with itself, but authentication is a step only
  290. you can do: run login_setup.py once and paste a browser cookie, or enter your
  291. password and MFA. After that, ask Muse to list your Monarch accounts to confirm
  292. it is working.
  293. Check out Muse, your personal AI agent. Redeem my code in Settings within 48
  294. hours of joining and we'll both get 1 billion Muse tokens.
  295. Code: O63W0U
  296. https://muse.ai/join
  297. ## ✨ Features
  298. ### 📊 Account Management
  299. - **Get Accounts**: View all linked financial accounts with balances and institution info
  300. - **Get Account Holdings**: See securities and investments in investment accounts
  301. - **Refresh Accounts**: Request real-time data updates from financial institutions
  302. ### 💰 Transaction Access
  303. - **Get Transactions**: Fetch transaction data with filtering by date, account, and pagination
  304. - **Create Transaction**: Add new transactions to accounts
  305. - **Update Transaction**: Modify existing transactions (amount, description, category, date)
  306. ### 🏷️ Category Management
  307. - **Get Categories**: List all transaction categories with groups, icons, and metadata
  308. - **Get Category Groups**: View category groups with their associated categories
  309. ### 📋 Transaction Review
  310. - **Get Transactions Needing Review**: Find transactions that need attention (uncategorized, no notes, flagged)
  311. - **Set Transaction Category**: Assign a category to a transaction
  312. - **Update Transaction Notes**: Add or update notes on transactions (great for receipt links)
  313. - **Mark Transaction Reviewed**: Clear the needs_review flag on transactions
  314. ### 📦 Bulk Operations
  315. - **Bulk Categorize Transactions**: Apply a category to multiple transactions at once
  316. ### 🔖 Tag Management
  317. - **Get Tags**: List all available tags with colors and usage counts
  318. - **Set Transaction Tags**: Apply tags to a transaction
  319. - **Create Tag**: Create a new tag with custom name and color
  320. ### 🔍 Advanced Search
  321. - **Search Transactions**: Comprehensive search with filters for merchant, category, account, tags, date ranges, and amounts
  322. - **Get Transaction Details**: Retrieve complete details for a single transaction
  323. - **Delete Transaction**: Remove a transaction
  324. - **Get Recurring Transactions**: View upcoming recurring transactions
  325. ### 🤖 Transaction Rules (Auto-Categorization)
  326. - **Get Transaction Rules**: List all auto-categorization rules
  327. - **Create Transaction Rule**: Create rules with merchant/amount conditions to auto-categorize
  328. - **Update Transaction Rule**: Modify existing rules
  329. - **Delete Transaction Rule**: Remove a rule
  330. ### Recurring forecasts and synced bills
  331. `get_recurring_transactions()` includes merchant forecasts **and synced liability
  332. bills** (such as credit cards and loans). Set `include_liabilities=False` to
  333. request only merchant recurring items. Omit both dates for the current calendar
  334. month, or provide both `start_date` and `end_date` in `YYYY-MM-DD` format.
  335. The default response remains a JSON list with the existing merchant fields.
  336. Each item also exposes `account_id`, `category_id`, `amount_diff`, and the stream's
  337. `name` and `merchant_id`. A liability item can have a null merchant. Its
  338. `stream.credit_report_liability_account` contains the liability `id`, linked
  339. `account_id`/`account` name, and `last_statement` with `id`, `due_date`,
  340. `bill_amount`, `minimum_payment_amount`, `payment_status`, and `remaining_balance`.
  341. Missing statements and unknown balances stay null; paid balances stay zero.
  342. **These are not interchangeable amounts.** The item's `amount` and stream's
  343. `amount` are recurring forecasts. `last_statement.bill_amount` is the original
  344. synced statement amount; `remaining_balance` is the remaining synced statement
  345. balance. The latest statement's due date can differ from the forecast item's
  346. `date`. Payment status is returned as supplied by Monarch, not inferred. These
  347. values reflect the latest sync, not a guaranteed real-time amount owed.
  348. Merchant forecasts and liability bills can describe the same payment. The tool
  349. preserves both with their identities: it does not sum, deduplicate, or substitute
  350. forecast amounts for unknown statement balances.
  351. With `limit` omitted, the tool reads every page itself and returns the complete
  352. range, so the default list is the whole month. Pass `limit` to read a single page
  353. instead, and use `include_metadata=True` to opt into the standard envelope
  354. (`data`, `args`, `count`, `total_count`, `truncated`, `tool`, `search`):
  355. ```python
  356. get_recurring_transactions(
  357. start_date="2026-02-01", end_date="2026-02-28",
  358. include_liabilities=True, limit=100, offset=0, include_metadata=True,
  359. )
  360. ```
  361. The API supplies no total, so `total_count` is null. With an explicit `limit`, a
  362. full page is conservatively marked `truncated=True` (more rows may exist). Keep
  363. the dates and filters fixed, advance `offset` by `count`, and continue until
  364. `truncated=False`. An exactly full final page requires one more request, which
  365. may return an empty page.
  366. Synced bills require bill sync to be available and configured in Monarch; the
  367. tool does not enable it or refresh institutions.
  368. ### 🔄 Merchant & Recurring Stream Management
  369. - **Get Merchant**: View a merchant's details including recurring transaction stream configuration
  370. - **Update Merchant**: Modify a merchant's name and/or recurring stream settings (frequency, amount, base date)
  371. - **Merge Merchants**: Move one merchant's transactions to another and delete the source, which cannot be undone
  372. - **Review Recurring Stream**: Accept, ignore, or reset recurring transaction streams detected by Monarch
  373. ### ✂️ Transaction Splits
  374. - **Get Transaction Splits**: View how a transaction has been split into parts
  375. - **Split Transaction**: Divide a single transaction into multiple parts with different categories or merchants
  376. ### 💵 Budget Management
  377. - **Get Budgets**: Access budget information including spent amounts and remaining balances by category
  378. - **Set Budget Amount**: Create or modify budget amounts for any category or category group
  379. ### 📈 Net Worth Tracking
  380. - **Get Net Worth**: Track total net worth over time with daily snapshots and trend analysis
  381. - **Get Account Balance History**: View historical balance data for any account
  382. - **Get Net Worth by Account Type**: See net worth breakdown across account types (checking, savings, investments, etc.)
  383. ### 📊 Financial Analysis
  384. - **Get Cashflow**: Analyze financial cashflow over specified date ranges with income/expense breakdowns
  385. - **Get Transactions Summary**: Quick high-level statistics about your transactions
  386. - **Get Spending Summary**: Spending breakdown by category with totals
  387. ### 🔐 Secure Authentication
  388. - **One-Time Setup**: Authenticate once, use for weeks/months
  389. - **Email OTP Support**: Handles Monarch's email verification flow for new devices/sessions
  390. - **MFA Support**: Full support for two-factor authentication
  391. - **SSO/Google sign-in**: Use `monarch_login_with_token` to paste a session token from your browser
  392. - **Session Persistence**: No need to re-authenticate frequently
  393. - **Secure**: Credentials never pass through Claude
  394. ## 🛠️ Available Tools
  395. All 68 registered tools. Required parameters are listed first, optional ones
  396. are marked with a trailing question mark. This table is generated from the
  397. live tool registry and the functions' signatures, so it does not drift.
  398. | Tool | Description | Parameters |
  399. |------|-------------|------------|
  400. | `add_transaction_tag` | Add a tag to a transaction, preserving any tags already on it | `transaction_id`, `tag_id` |
  401. | `bulk_categorize_transactions` | Apply the same category to multiple transactions at once | `transaction_ids`, `category_id`, `mark_reviewed`?, `dry_run`? |
  402. | `bulk_update_transactions` | Apply the same edit to many transactions in one request | `transaction_ids`, `category_id`?, `merchant_name`?, `notes`?, `goal_id`?, `needs_review`?, `business_entity_id`?, `dry_run`? |
  403. | `categorize_transaction` | Assign a category to a transaction | `transaction_id`, `category_id` |
  404. | `check_auth_status` | Report the stored session and its auth mode | None |
  405. | `create_transaction` | Create a new transaction in Monarch Money | `date`, `account_id`, `amount`, `merchant_name`, `category_id`, `notes`?, `update_balance`? |
  406. | `create_transaction_category` | Create a new transaction category | `group_id`, `transaction_category_name`, `icon`?, `rollover_enabled`?, `rollover_type`? |
  407. | `create_transaction_category_group` | Create an income/expense group and verify it with a fresh read | `name`, `group_type`?, `dry_run`? |
  408. | `create_transaction_rule` | Create a new transaction auto-categorization rule | `merchant_criteria_operator`?, `merchant_criteria_value`?, `merchant_criteria_values`?, `merchant_criteria`?, `original_statement_operator`?, `original_statement_values`?, `original_statement_criteria`?, `use_original_statement`?, `amount_operator`?, `amount_value`?, `amount_lower`?, `amount_upper`?, `amount_is_expense`?, `set_category_id`?, `set_merchant_name`?, `add_tag_ids`?, `link_goal_id`?, `hide_from_reports`?, `review_status`?, `set_business_entity_id`?, `account_ids`?, `category_ids`?, `apply_to_existing`? |
  409. | `create_transaction_tag` | Create a new transaction tag | `name`, `color` |
  410. | `debug_session_loading` | Diagnose session loading problems | None |
  411. | `delete_transaction` | Delete a transaction from Monarch Money | `transaction_id` |
  412. | `delete_transaction_rule` | Delete a transaction rule | `rule_id` |
  413. | `get_account_balance_history` | Get historical balance data for a specific account | `account_id` |
  414. | `get_account_holdings` | Get investment holdings for a specific account | `account_id` |
  415. | `get_account_sync_health` | Report the health of each linked institution connection | `stale_after_days`? |
  416. | `get_accounts` | Get all financial accounts from Monarch Money | None |
  417. | `get_budget_summary` | Read category budgets, group budgets, and authoritative monthly totals | `start_date`?, `end_date`? |
  418. | `get_budgets` | Get budget information from Monarch Money | `start_date`?, `end_date`? |
  419. | `get_business_entities` | List the business entities on the Monarch account (id and name) | None |
  420. | `get_cashflow` | Get cashflow analysis from Monarch Money | `start_date`?, `end_date`?, `limit`? |
  421. | `get_cashflow_by_month` | Get spending trends over time, broken down by category and month | `start_date`, `end_date` |
  422. | `get_category_details` | Get a single category's details including budget amounts for a month | `category_id`, `month`? |
  423. | `get_category_group_details` | Read one group's name, categories and group/category budgeting mode | `group_id` |
  424. | `get_debt_paydown` | Get the debt paydown plan and the accounts feeding it | `method`? |
  425. | `get_goal_contributions` | Show a goal's budgeted contributions, broken down by funding account | `goal_id`, `month`? |
  426. | `get_goals` | List Monarch savings and debt-paydown goals | None |
  427. | `get_household_members` | Get household member IDs, names, display names, and roles | None |
  428. | `get_merchant` | Get a merchant's details including recurring transaction stream configuration | `merchant_id` |
  429. | `get_net_worth` | Get net worth history over time | `start_date`?, `end_date`?, `account_type`? |
  430. | `get_net_worth_by_account_type` | Get net worth breakdown by account type over time | `start_date`, `timeframe`? |
  431. | `get_recurring_transactions` | Get recurring merchant forecasts and synced liability bills | `start_date`?, `end_date`?, `include_liabilities`?, `limit`?, `offset`?, `include_metadata`? |
  432. | `get_savings_goal_history` | Show how savings goal balances have changed, up to today | `goal_name`?, `granularity`?, `periods`?, `breakdown`? |
  433. | `get_spending_summary` | Get a spending summary broken down by category, category group, and merchant | `start_date`?, `end_date`?, `limit`? |
  434. | `get_transaction_categories` | Get all available transaction categories from Monarch Money | None |
  435. | `get_transaction_category_groups` | Get all transaction category groups (parent groupings for categories) | None |
  436. | `get_transaction_details` | Get full details for a specific transaction | `transaction_id` |
  437. | `get_transaction_rules` | Get all transaction auto-categorization rules from Monarch Money | None |
  438. | `get_transaction_splits` | Get the splits for a transaction | `transaction_id` |
  439. | `get_transaction_tags` | Get all available transaction tags from Monarch Money | None |
  440. | `get_transactions` | Get transactions from Monarch Money | `limit`?, `offset`?, `start_date`?, `end_date`?, `account_id`?, `search`?, `category_ids`?, `category_group_ids`?, `account_ids`?, `tag_ids`?, `has_notes`?, `is_split`?, `is_recurring`?, `wide_search`?, `search_scan_limit`?, `include_hidden`? |
  441. | `get_transactions_needing_review` | Get transactions that need review based on various criteria | `needs_review`?, `days`?, `uncategorized_only`?, `without_notes_only`?, `limit`?, `offset`?, `account_id`?, `include_hidden`? |
  442. | `get_transactions_summary` | Get a high-level summary of transactions | None |
  443. | `mark_transaction_reviewed` | Mark a transaction as reviewed (clears the needs_review flag) | `transaction_id` |
  444. | `merge_merchants` | Merge one merchant into another, deleting the source. Cannot be undone | `source_merchant_id`, `target_merchant_id` |
  445. | `monarch_login` | Sign in via a secure form in the client UI | None |
  446. | `monarch_login_with_token` | Sign in with a browser copied session token | None |
  447. | `monarch_logout` | Clear the stored session and drop the cached client | None |
  448. | `monarch_whoami` | Report who is signed in and what the account's plan entitles it to | None |
  449. | `refresh_accounts` | Request account data refresh from financial institutions | `account_ids`? |
  450. | `reorder_transaction_rule` | Move a transaction rule to a new position in the evaluation order | `rule_id`, `new_order` |
  451. | `review_recurring_stream` | Set the review status of a recurring transaction stream | `stream_id`, `review_status` |
  452. | `search_transactions` | Search and filter transactions with comprehensive filtering options | `search`?, `limit`?, `offset`?, `start_date`?, `end_date`?, `category_ids`?, `account_ids`?, `tag_ids`?, `has_attachments`?, `has_notes`?, `hidden_from_reports`?, `is_split`?, `is_recurring`? |
  453. | `set_budget_amount` | Set or update a budget amount for a category or category group | `amount`, `category_id`?, `category_group_id`?, `start_date`?, `apply_to_future`? |
  454. | `set_business_entity` | Set (or clear) the business entity on one transaction | `transaction_id`, `business_entity_id` |
  455. | `set_goal_contribution` | Set the budgeted monthly contribution to a goal from one funding account | `goal_id`, `account_id`, `amount` |
  456. | `set_transaction_tags` | Set tags on a transaction | `transaction_id`, `tag_ids` |
  457. | `setup_authentication` | Get setup instructions | None |
  458. | `split_transaction` | Split a transaction into multiple parts with different categories/merchants | `transaction_id`, `splits` |
  459. | `update_account` | Update an account's name, balance, type or visibility settings | `account_id`, `name`?, `balance`?, `account_type`?, `account_sub_type`?, `include_in_net_worth`?, `hide_from_summary_list`?, `hide_transactions_from_reports`?, `dry_run`? |
  460. | `update_category` | Update an existing category's settings | `category_id`, `name`?, `icon`?, `group_id`?, `category_type`?, `exclude_from_budget`?, `budget_variability`?, `rollover_enabled`?, `rollover_start_month`?, `rollover_starting_balance`?, `rollover_frequency`?, `rollover_target_amount`?, `rollover_type`?, `confirm_rollover_reset`?, `dry_run`? |
  461. | `update_merchant` | Update a merchant's name and/or recurring transaction stream settings | `merchant_id`, `name`?, `is_recurring`?, `frequency`?, `base_date`?, `amount`?, `is_active`? |
  462. | `update_savings_goal` | Update a savings goal's target or monthly contribution | `goal_id`, `target_amount`?, `target_date`?, `name`?, `priority`?, `goal_type`?, `is_sinking_fund`? |
  463. | `update_transaction` | Update an existing transaction in Monarch Money | `transaction_id`, `category_id`?, `merchant_name`?, `goal_id`?, `amount`?, `date`?, `hide_from_reports`?, `needs_review`?, `notes`?, `owner_user_id`? |
  464. | `update_transaction_category_group` | Rename a group and/or switch its group/category budgeting mode | `group_id`, `name`?, `group_level_budgeting_enabled`?, `dry_run`? |
  465. | `update_transaction_notes` | Update the notes/memo for a transaction | `transaction_id`, `notes`, `receipt_url`? |
  466. | `update_transaction_rule` | Update an existing transaction rule | `rule_id`, `merchant_criteria_operator`?, `merchant_criteria_value`?, `merchant_criteria_values`?, `merchant_criteria`?, `original_statement_operator`?, `original_statement_values`?, `original_statement_criteria`?, `use_original_statement`?, `amount_operator`?, `amount_value`?, `amount_lower`?, `amount_upper`?, `amount_is_expense`?, `set_category_id`?, `set_merchant_name`?, `add_tag_ids`?, `link_goal_id`?, `hide_from_reports`?, `review_status`?, `set_business_entity_id`?, `account_ids`?, `category_ids`?, `clear_category`?, `clear_merchant`?, `clear_tags`?, `clear_goal_link`?, `clear_review_status`?, `clear_business_entity`?, `apply_to_existing`? |
  467. | `upload_account_balance_history` | Upload corrected balance snapshots for an account | `account_id`, `corrections`, `dry_run`? |
  468. ## 📝 Usage Examples
  469. ### View Your Accounts
  470. ```
  471. Use get_accounts to show me all my financial accounts
  472. ```
  473. ### Get Recent Transactions
  474. ```
  475. Show me my last 50 transactions using get_transactions with limit 50
  476. ```
  477. `get_transactions` returns a JSON object with `tool`, `args`, `count`, `total_count`, `truncated`, `search`, and `data` so large `agent-tools/<uuid>.txt` responses are self-describing. Transaction rows live in `data` and include `original_statement` / `plaid_description` when Monarch provides the underlying Plaid statement text, plus `currency`, `direction`, `direction_source`, `transaction_type`, `category_group`, and `category_group_id` when those values can be derived from Monarch response data. When Monarch's server-side `search` errors or returns no rows, `wide_search` scans recent transactions locally across merchant, original statement, description, notes, category, account, and tags. Transactions hidden from reports are included by default and carry `hide_from_reports: true`; Monarch's API leaves them out unless asked, so pass `include_hidden=false` only when you want just the transactions Monarch's reports count. `get_transactions_needing_review` takes the same `include_hidden` flag, and `search_transactions` returns both kinds when `hidden_from_reports` is left unset.
  478. ### Check Spending vs Budget
  479. ```
  480. Use get_budgets to show my current budget status
  481. ```
  482. ### Set a Budget Amount
  483. ```
  484. Set my grocery budget to $600 for this month using set_budget_amount
  485. ```
  486. ### Apply Budget to All Future Months
  487. ```
  488. Set my entertainment budget to $150 and apply it to all future months using set_budget_amount with apply_to_future=true
  489. ```
  490. ### Track Net Worth Over Time
  491. ```
  492. Show my net worth trend for the past year using get_net_worth
  493. ```
  494. ### View Account Balance History
  495. ```
  496. Show me how my savings account balance has changed over time using get_account_balance_history
  497. ```
  498. ### Net Worth Breakdown by Account Type
  499. ```
  500. Show my net worth breakdown by account type using get_net_worth_by_account_type
  501. ```
  502. ### Analyze Cash Flow
  503. ```
  504. Get my cashflow for the last 3 months using get_cashflow
  505. ```
  506. ### List Available Categories
  507. ```
  508. Show me all available categories using get_transaction_categories
  509. ```
  510. ### Review Uncategorized Transactions
  511. ```
  512. Show me transactions from the last 7 days that need review using get_transactions_needing_review
  513. ```
  514. ### Bulk Categorize Transactions
  515. ```
  516. Categorize these three transactions as "Groceries" using bulk_categorize_transactions
  517. ```
  518. ### Tag a Transaction
  519. ```
  520. Add the "Tax Deductible" tag to this transaction using set_transaction_tags
  521. ```
  522. ### Search for Transactions
  523. ```
  524. Find all Amazon transactions from the last month using search_transactions
  525. ```
  526. ### View Recurring Bills
  527. ```
  528. Show me my upcoming recurring transactions using get_recurring_transactions
  529. ```
  530. ### Create Auto-Categorization Rule
  531. ```
  532. Create a rule to automatically categorize Amazon transactions as "Shopping" using create_transaction_rule
  533. ```
  534. ### Split a Transaction
  535. ```
  536. Split this $100 Costco transaction into $60 for Groceries and $40 for Household using split_transaction
  537. ```
  538. ### Get Transaction Statistics
  539. ```
  540. Give me a quick summary of my transactions using get_transactions_summary
  541. ```
  542. ### View Spending by Category
  543. ```
  544. Show my spending breakdown by category for last month using get_spending_summary
  545. ```
  546. ### Update a Recurring Bill Amount
  547. ```
  548. Update PennyMac's recurring stream to $1,460.93 monthly using update_merchant
  549. ```
  550. ### Review Recurring Streams
  551. ```
  552. Approve the Netflix recurring stream using review_recurring_stream
  553. ```
  554. ## 📅 Date Formats
  555. - All dates should be in `YYYY-MM-DD` format (e.g., "2024-01-15")
  556. - Transaction amounts: **positive** for income, **negative** for expenses
  557. ## 🔧 Troubleshooting
  558. ### Authentication Issues
  559. If you see "Authentication needed" errors:
  560. 1. Run the setup command: `cd /path/to/your/monarch-mcp-server && python login_setup.py` (or `uv run python login_setup.py`)
  561. 2. Restart Claude Desktop or Claude Code
  562. 3. Try using a tool like `get_accounts`
  563. ### Email Verification Required
  564. Monarch may require an email one-time code for a new device or session, even if MFA is not enabled. If you see an email-code prompt:
  565. 1. Check the email address on your Monarch account
  566. 2. Enter the one-time code in `login_setup.py`
  567. 3. Let the script finish so it can save the reusable token to your system keyring
  568. ### Session Expired or 401 within an hour
  569. If your session dies quickly (under a couple of hours), the most common cause is that Monarch returned a short-lived token. The login script now requests `trusted_device=True` and rejects any short-lived token, so a fresh login produces a long-lived session. If you re-run `login_setup.py` and the issue persists, switch to option 1 (browser cookies); cookie sessions track the lifetime of the underlying browser login.
  570. ### Cloudflare CAPTCHA on login
  571. If `login_setup.py` reports "Programmatic login is blocked by Cloudflare CAPTCHA", choose option 1 (browser cookies) instead. Email/password POSTs to Monarch's login endpoint are sometimes gated by Cloudflare for unfamiliar IPs or rapid retries; cookie-based auth bypasses that endpoint entirely.
  572. ### `'Context' object has no attribute 'elicit'`
  573. The `monarch_login` and `monarch_login_with_token` tools require the MCP Python SDK 1.10.0 or newer (released June 2025). If your environment cached an older `mcp` install, refresh it:
  574. ```bash
  575. uv cache clean mcp
  576. ```
  577. Then fully quit and reopen Claude Desktop or Claude Code so it relaunches the server with a fresh resolution. As a fallback while you upgrade, run `python login_setup.py` from the repo to authenticate via the terminal.
  578. ### Common Error Messages
  579. - **"No valid session found"**: Run `python login_setup.py` (or `uv run python login_setup.py`)
  580. - **"Monarch sent a one-time code to your email"**: Run `python login_setup.py` and complete email verification
  581. - **"Invalid account ID"**: Use `get_accounts` to see valid account IDs
  582. - **"Date format error"**: Use YYYY-MM-DD format for dates
  583. ## 🏗️ Technical Details
  584. ### Project Structure
  585. ```
  586. monarch-mcp-server/
  587. ├── src/monarch_mcp_server/
  588. │ ├── __init__.py
  589. │ ├── app.py # FastMCP app instance and entry point
  590. │ ├── client.py # Cached MonarchMoney client factory
  591. │ ├── monarch_auth.py # Current Monarch auth compatibility (host, email OTP, device-uuid)
  592. │ ├── secure_session.py # Keyring-backed token storage (file fallback)
  593. │ ├── server.py # Backward-compatibility shim re-exporting the tools
  594. │ └── tools/ # MCP tools grouped by domain (accounts, transactions, budgets, …)
  595. ├── login_setup.py # Terminal authentication script
  596. ├── pyproject.toml # Project configuration
  597. ├── requirements-lock.txt # Generated from uv.lock, hash pinned
  598. └── README.md # This documentation
  599. ```
  600. ### Session Management
  601. - Session tokens are stored securely in the system keyring (with an automatic file fallback for environments without a keyring backend)
  602. - The `device-uuid` captured at login is stored alongside the token so it reloads cleanly
  603. - Sessions persist across Claude Desktop and Claude Code restarts
  604. - No need for frequent re-authentication
  605. ### Security Features
  606. - Credentials never transmitted through Claude Desktop or Claude Code
  607. - MFA/2FA fully supported
  608. - Email verification codes are handled only in the terminal setup script
  609. - Session tokens are stored in the system keyring
  610. - Authentication handled in secure terminal environment
  611. ### Strongest option: read only mode
  612. Set `MONARCH_MCP_READ_ONLY=1` in the server's environment and the mutating
  613. tools are never registered. They do not appear in the tool list and cannot be
  614. called at all, which is stronger than an approval prompt: a model that was
  615. talked into a write by a merchant name or memo it read back cannot invoke a
  616. tool that is not there.
  617. ```json
  618. {
  619. "mcpServers": {
  620. "Monarch Money": {
  621. "command": "/opt/homebrew/bin/uv",
  622. "args": ["run", "--project", "/path/to/your/monarch-mcp-server", "monarch-mcp-server"],
  623. "env": { "MONARCH_MCP_READ_ONLY": "1" }
  624. }
  625. }
  626. }
  627. ```
  628. This leaves 35 of the 68 tools available, covering everything that reads.
  629. Read only is off by default outside Docker, so existing setups are unaffected;
  630. the Docker image turns it on (see [Start the HTTP server](#start-the-http-server)). Note that it
  631. also removes the login and logout tools, since those change durable state, so
  632. authenticate with `login_setup.py` before enabling it.
  633. ### Recommended: require approval for mutating tools
  634. These tools mutate your Monarch data. The list is every registered tool that writes, checked against the source rather than maintained by hand:
  635. **Accounts**: `update_account`
  636. **Transactions**: `create_transaction`, `update_transaction`, `delete_transaction`, `categorize_transaction`, `update_transaction_notes`, `mark_transaction_reviewed`, `bulk_categorize_transactions`, `bulk_update_transactions`, `split_transaction`, `set_business_entity`, `upload_account_balance_history`
  637. **Tags**: `set_transaction_tags`, `add_transaction_tag`, `create_transaction_tag`
  638. **Rules**: `create_transaction_rule`, `update_transaction_rule`, `delete_transaction_rule`, `reorder_transaction_rule`
  639. **Categories and budgets**: `create_transaction_category`, `create_transaction_category_group`, `update_transaction_category_group`, `update_category`, `set_budget_amount`
  640. **Goals**: `update_savings_goal`, `set_goal_contribution`
  641. **Merchants**: `update_merchant`, `merge_merchants`, `review_recurring_stream`
  642. **Session**: `monarch_login`, `monarch_login_with_token`, `monarch_logout`
  643. `refresh_accounts` is side effecting too, since it posts a refresh request to your institutions, though it does not change your ledger.
  644. Because the LLM can be influenced by data it reads back (a malicious-looking memo or merchant name in a transaction), the safest setup is to configure your MCP client to require manual approval before any mutating tool runs. In Claude Desktop and Claude Code this is the default behavior for unknown tools; keep it that way for the tools listed above rather than allow-listing them.
  645. `bulk_categorize_transactions`, `bulk_update_transactions`, `upload_account_balance_history`, `update_account` and `update_category` accept a `dry_run=True` argument that returns the planned changes without executing them, useful for previewing before approving.
  646. `update_category` additionally requires `confirm_rollover_reset=True` before `rollover_start_month` or `rollover_starting_balance` will be applied. Those two restart a category's rollover period and discard the balance accumulated in it, which cannot be undone, so they cannot ride along unnoticed in a call that otherwise reads like a rename.
  647. ## 🙏 Acknowledgments
  648. This MCP server is built on top of the [MonarchMoneyCommunity Python library](https://github.com/bradleyseanf/monarchmoneycommunity), an actively maintained community fork of the original [MonarchMoney library](https://github.com/hammem/monarchmoney) by [@hammem](https://github.com/hammem). The community fork provides:
  649. - Updated API endpoints for Monarch Money's current domain
  650. - Secure authentication with MFA support
  651. - Comprehensive API coverage for Monarch Money
  652. - Session management and persistence
  653. Thank you to [@hammem](https://github.com/hammem) for creating and maintaining this essential library!
  654. ## 📄 License
  655. MIT License
  656. ## 🆘 Support
  657. For issues:
  658. 1. Check authentication with `check_auth_status`
  659. 2. Run the setup command again: `cd /path/to/your/monarch-mcp-server && python login_setup.py`
  660. 3. Check error logs for detailed messages
  661. 4. Ensure Monarch Money service is accessible
  662. ## 🔄 Updates
  663. To update the server:
  664. 1. Pull latest changes from repository
  665. 2. Restart Claude Desktop or Claude Code
  666. 3. Re-run authentication if needed: `python login_setup.py`
  667. ### Managing budget groups
  668. Use `get_category_group_details` and `get_budget_summary` before changing a
  669. group. `create_transaction_category_group(name="Family", dry_run=True)` previews
  670. creation; an existing same-name, same-type group is reused.
  671. `update_transaction_category_group(group_id="...", name="Core bills",
  672. group_level_budgeting_enabled=False, dry_run=True)` previews a rename and a switch
  673. to category-level budgeting. Set `dry_run=False` to apply. Group writes confirm
  674. the returned entity against a fresh read; after an error, inspect current groups
  675. before retrying because a write can succeed before verification fails.
  676. Switching budgeting mode does not migrate existing budget amounts. Reconcile
  677. old group targets and category targets with `set_budget_amount`, then verify
  678. `get_budget_summary.totals_by_month`. Category and group budget rows overlap;
  679. never sum both. These tools do not delete groups, move categories or reset
  680. rollovers. Use `update_category` for category moves. Income and expense groups
  681. are supported; transfer-group creation is intentionally not exposed.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.