monarch

Monarch Money MCP Server provides a Python-based MCP interface to access Monarch Money data through Claude Desktop. It exposes tools to fetch accounts, transactions, budgets, and cashflow, with support for MFA-protected authentication and session persistence. After the initial one-time setup and authentication, you can invoke tools like get_accounts, get_transactions, get_budgets, get_cashflow, and more to retrieve and manipulate your financial data within Claude Desktop. The server handles secure MFA flows outside Claude Desktop, ensuring your credentials stay local and sessions persist across restarts.

To use the server, first ensure you have completed the authentication setup (login_setup.py). Once authenticated, Claude Desktop can communicate with the MCP server via the configured mcp tools. You can query your accounts to see balances and institutions, pull recent transactions with filters, review budget status, and analyze cashflow over a date range. The available tools include: setup_authentication, check_auth_status, get_accounts, get_account_holdings, get_transactions, create_transaction, update_transaction, refresh_accounts, get_budgets, and get_cashflow. Each tool accepts its own set of parameters (e.g., get_transactions supports limit, offset, start_date, end_date, account_id), allowing precise data retrieval and updates as needed.

Prerequisites:

• Python 3.8+ and pip
• Access to install dependencies from requirements.txt
• A copy of this Monarch Money MCP Server repository

Step-by-step installation:

1. Clone the repository and navigate to it:

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

2. Create and (optional) activate a virtual environment:

python -m venv venv
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows

3. Install dependencies and install the package in editable mode:

pip install -r requirements.txt
pip install -e .

4. Perform one-time authentication setup:

cd /path/to/your/monarch-mcp-server  # replace with actual path
python login_setup.py

5. Configure Claude Desktop to point to the MCP server. Use the example config in Claude Desktop settings, replacing the path placeholders with your actual server path. For the uvx-based Python setup you would typically specify the command as uvx and provide paths to your server script as shown in the Quick Start example. Restart Claude Desktop after configuration.

Notes:

• Ensure Monarch Money service is accessible and MFA flow is completed during login_setup.py.
• The server script path should point to /path/to/your/monarch-mcp-server/src/monarch_mcp_server/server.py.
• If you update the server, reinstall or reload credentials if needed, and restart Claude Desktop.

Tips and common considerations:

• MFA is handled outside Claude Desktop via login_setup.py; this keeps credentials secure.
• Sessions are stored securely and persist across Claude Desktop restarts (look for session files in the project as described in the docs).
• The MCP server uses the Monarch Money Python library for API access, so ensure you have network access to Monarch Money services.
• If you encounter issues like 'Authentication needed' or 'No valid session', re-run python login_setup.py and re-launch Claude Desktop.
• When configuring Claude Desktop, provide the correct path to your local monarch-mcp-server source and ensure the mcp server is running when you start Claude Desktop.
• The tools support standard date formats (YYYY-MM-DD) and typical data types (amounts with positive/negative semantics for income/expenses).
• If you modify paths, remember to update the Claude Desktop config accordingly.