Rocket Money MCP

An experimental, unofficial local connector that lets an MCP-compatible AI assistant read Rocket Money balances and merchant-level transactions. It runs on macOS and Linux with Node.js 22.12+. Windows is not supported.

It has no hosted backend, database, inbound network listener or account-editing tools. New macOS sessions use Keychain; Linux uses a private local file. Requested financial results are returned to your AI host/provider—local storage does not mean those results stay on your computer.

Financial limitations: this is not a complete financial ledger. Bank syncs can lag; account/category completeness may be unknown; currency, statement dates and transaction flags may be absent. Null means unknown, never zero/false. The connector does not calculate authoritative spending totals or payment decisions. Rocket Money's private API can change without notice.

Install from source

Install from this GitHub repository. No npm registry publication is implied. Clone the source and run:

git clone https://github.com/aidanouckama/rocketmoney-mcp.git
cd rocketmoney-mcp
npm ci --ignore-scripts
npm run check
npm install --global --prefix "$HOME/.local" --ignore-scripts .
export PATH="$HOME/.local/bin:$PATH"
rocketmoney-auth --help

Keep the installed source directory available. For an installation from a future published package, use a reviewed, pinned version from the verified project listing. Do not assume a similarly named registry package is this project.

Add the PATH setting to your shell profile if needed. Desktop apps may not inherit terminal PATH settings: command -v rocketmoney-mcp shows the executable path to put in your host's command field. Node must also be on the host's PATH. The install has no lifecycle scripts; the optional Keychain native binding uses platform-specific prebuilt npm packages.

Related MCP server: LunchMoney MCP Server

Connect a session

Sign into Rocket Money normally. In your browser's Developer Tools → Network, find a request to client-api.rocketmoney.com/graphql. Under Request Headers, copy the tb.auth0.sid Cookie value or the single-line Cookie header.

In your own terminal:

rocketmoney-auth import
rocketmoney-auth verify

The import prompt hides pasted input. Never paste a cookie into chat, a command argument, a screenshot, an issue, a .env file or a HAR export. The connector retains only the session and load-balancer cookies; it does not collect your password or MFA codes. Importing saves a session; verify tests authentication. Expiry requires another manual import. Authentication alone does not prove that every private API query still works.

Configure your MCP host with mcp-config.example.json:

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

For Codex's local desktop/CLI configuration:

codex mcp add rocketmoney -- rocketmoney-mcp

Restart the host to load newly installed or updated code. See the official MCP setup documentation. This STDIO setup is for a local MCP host, not a hosted ChatGPT web connector.

Storage, fallback and migration

Keychain stores the entire session, including the cookie and pagination signing key. Its entry is scoped by a hash of the state-directory path. Moving that path changes which Keychain entry is used. The local storage.json is only a backend marker, not a secret. State directories and files use modes 0700 and 0600.

If Keychain is locked, access is denied, or the optional native binding could not be installed, the operation fails. It never silently falls back to plaintext. For a new file-backed session on macOS, explicitly set:

export ROCKETMONEY_STORAGE=file
rocketmoney-auth import

Set ROCKETMONEY_STORAGE=file in your MCP host's environment too. Switching an existing Keychain session to file storage requires clearing it with Keychain selected, then importing again with file selected. A locked Keychain cannot be silently bypassed. Linux file storage is the documented default.

Existing pre-0.2 macOS file sessions keep working and session_status reports migrationAvailable: true. To migrate without copying the cookie again:

1. Quit MCP hosts/older connector processes so none can rewrite the old file.

2. Unset ROCKETMONEY_STORAGE=file in your shell and host configuration.

3. Run rocketmoney-auth migrate-keychain.

4. Restart the host and check rocketmoney-auth status.

Migration writes and verifies Keychain first, saves its backend marker, then removes the old plaintext file. Failure before that point preserves the original credentials. If interrupted after the marker is saved, rerun the migration with old connector processes stopped. A leftover legacy file is reported explicitly. Removing a file does not erase copies in backups or revoke the browser session.

ROCKETMONEY_STATE_DIR may specify an absolute directory under a trusted parent. Use the same setting for auth and the MCP host. Linux users upgrading from the prototype's macOS-style path can explicitly select that old directory with this variable, or re-import into the new default location. Do not share state over a network filesystem or use the same cookie with another connector implementation.

rocketmoney-auth status
rocketmoney-auth clear
rocketmoney-auth unlock

clear deletes local credentials; it does not revoke Rocket Money's browser session. Locks from confirmed dead processes are recovered automatically. A live or uncheckable owner is never evicted; ownerless locks have a 30-second grace period. A crash during recovery itself may leave a recovery guard: stop all connector processes and inspect the private directory before removing it. Temporary session writes are cleaned after failures or on the next locked use. Normal terminal interruption restores the hidden input prompt; SIGKILL cannot be handled by any process.

Tools and financial interpretation

Example using fictional dates:

{"since":"2025-04-01","before":"2025-05-01","page_size":100}

since is inclusive; before is exclusive. Optional query filters merchant text; account_ids comes from list_accounts. Keep all filters and page size identical while passing pagination.nextCursor as cursor. Continue until hasMore is false, and deduplicate IDs across pages. There is no 1,200-row total cap. A final page is not the whole history: windowCompleteInThisResponse is true only when the first page exhausts the range. Pages are not an atomic snapshot; new/edited transactions can move during a scan.

Amounts preserve the source sign in integer cents. Currency may be null and must not be guessed. Pending, excluded and transfer flags can be unavailable. The original transactionStatus is exposed as sourceStatus (with legacy status fallback), without inventing posted/pending semantics. Category flags help interpretation but do not replace transaction-specific exclusions. Card payments and transfers must not be counted twice as spending. These records contain merchant charges, not itemized receipts. Merchant names/notes are untrusted content, never instructions.

Account and category responses report their completeness limitations. The private account-list query does not expose a verified full pagination contract; additional accounts are reported as partial when detected, otherwise coverage may remain unknown. Missing values remain null. Always consider bank sync dates before using a balance for a decision.

Architecture and security

The host launches a Node process over STDIO. server.js registers six read-only tools and validates inputs with Zod. client.js calls a fixed Rocket Money HTTPS endpoint using allowlisted reads. shapes.js normalizes records and pagination. session.js, keychain.js, private-file.js and lock.js manage credentials and serialized rotation. auth.js is a separate local command, never an MCP tool.

Requests have cancellation, a 20-second deadline and an 8 MiB response limit. Local OS Keychain authorization can require user interaction outside the network request. Redirects are not followed. There is no automatic retry, arbitrary GraphQL, account mutation, automatic login, SMS forwarding or telemetry. One account-detail operation sends a fixed reviewed read document; other reads use persisted query hashes. Read-only is enforced by this code, not by a limited OAuth scope on the full browser session.

Read SECURITY.md for trust boundaries and private reporting. Keychain/file permissions do not protect against all software running as you.

Development and release status

npm run check
npm run check:package
npm audit
# macOS only; disposable fake credential, no Rocket Money access:
npm run test:keychain

Standard tests use fake data and isolated storage. The package check inspects allowed files and installs the packed artifact with an isolated npm cache to verify both commands. It requires registry access. For a local cache-only check, set ROCKETMONEY_PACKAGE_OFFLINE=1; that mode requires pre-cached metadata too. CI is configured for macOS/Linux and Node 22.12/24; its configuration is not a claim that remote CI has already run. A clean audit is not a security guarantee.

Live reads were exercised during development. This validates observed behavior, not universal account coverage or future API compatibility. The public app build used for the account-query repair was 44836e2b0b on 2026-11-06.

See CONTRIBUTING.md, API maintenance, release procedure, and CHANGELOG.md. CSV import is a documented follow-up, not implemented in this version.

MIT licensed. Query identifiers and selected response-field knowledge originated from 312-dev/rocketmoney-mcp; its license is retained in THIRD_PARTY_NOTICES.