Monarch MCP Server

🚀 Monarch Money MCP Server

A Model Context Protocol (MCP) server for seamless integration with the Monarch Money personal finance platform, enabling access to financial accounts, transactions, budgets, and analytics via Claude Desktop.

My MonarchMoney referral: https://www.monarchmoney.com/referral/ufmn0r83yf?r_source=share

Built with the MonarchMoney Python library by @hammem - A fantastic unofficial API for Monarch Money with full MFA support.

🚀 Quick Start

1. Installation

1. Clone this repository:

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

2. Install dependencies:

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

3. Configure Claude Desktop: Add the following 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",
           "--with",
           "mcp[cli]",
           "--with-editable",
           "/path/to/your/monarch-mcp-server",
           "mcp",
           "run",
           "/path/to/your/monarch-mcp-server/src/monarch_mcp_server/server.py"
         ]
       }
     }
   }
   

   ⚠️ Important Note

   Replace /path/to/your/monarch-mcp-server with your actual path!

4. Restart Claude Desktop

2. One-Time Authentication Setup

⚠️ Important Note

For security and MFA support, authentication is done outside of Claude Desktop.

Open Terminal and run:

cd /path/to/your/monarch-mcp-server
python login_setup.py

Follow the prompts:

• Enter your Monarch Money email and password
• Provide 2FA code if you have MFA enabled
• Session will be saved automatically

3. Start Using in Claude Desktop

Once authenticated, use these tools directly in Claude Desktop:

• get_accounts - View all your financial accounts
• get_transactions - Recent transactions with filtering
• get_budgets - Budget information and spending
• get_cashflow - Income/expense analysis

✨ Features

📊 Account Management

• Get Accounts: View all linked financial accounts with balances and institution info
• Get Account Holdings: See securities and investments in investment accounts
• Refresh Accounts: Request real-time data updates from financial institutions

💰 Transaction Access

• Get Transactions: Fetch transaction data with filtering by date, account, and pagination
• Create Transaction: Add new transactions to accounts
• Update Transaction: Modify existing transactions (amount, description, category, date)

📈 Financial Analysis

• Get Budgets: Access budget information including spent amounts and remaining balances
• Get Cashflow: Analyze financial cashflow over specified date ranges with income/expense breakdowns

🔐 Secure Authentication

• One-Time Setup: Authenticate once, use for weeks/months
• MFA Support: Full support for two-factor authentication
• Session Persistence: No need to re-authenticate frequently
• Secure: Credentials never pass through Claude Desktop

🛠️ Available Tools

💻 Usage Examples

Basic Usage

Use get_accounts to show me all my financial accounts

Advanced Usage

Show me my last 50 transactions using get_transactions with limit 50

Analyze Budgets

Use get_budgets to show my current budget status

Analyze Cash Flow

Get my cashflow for the last 3 months using get_cashflow

📅 Date Formats

⚠️ Important Note

• All dates should be in YYYY-MM-DD format (e.g., "2024-01-15")
• Transaction amounts: positive for income, negative for expenses

🔧 Troubleshooting

Authentication Issues

If you see "Authentication needed" errors:

1. Run the setup command: cd /path/to/your/monarch-mcp-server && python login_setup.py
2. Restart Claude Desktop
3. Try using a tool like get_accounts

Session Expired

Sessions last for weeks, but if expired:

1. Run the same setup command again
2. Enter your credentials and 2FA code
3. Session will be refreshed automatically

Common Error Messages

• "No valid session found": Run login_setup.py
• "Invalid account ID": Use get_accounts to see valid account IDs
• "Date format error": Use YYYY-MM-DD format for dates

🏗️ Technical Details

Project Structure

monarch-mcp-server/
├── src/monarch_mcp_server/
│   ├── __init__.py
│   └── server.py          # Main server implementation
├── login_setup.py         # Authentication setup script
├── pyproject.toml         # Project configuration
├── requirements.txt       # Dependencies
└── README.md             # This documentation

Session Management

• Sessions are stored securely in .mm/mm_session.pickle
• Automatic session discovery and loading
• Sessions persist across Claude Desktop restarts
• No need for frequent re-authentication

Security Features

• Credentials never transmitted through Claude Desktop
• MFA/2FA fully supported
• Session files are encrypted
• Authentication handled in secure terminal environment

🙏 Acknowledgments

This MCP server is built on top of the excellent MonarchMoney Python library created by @hammem. Their library provides the robust foundation that makes this integration possible, including:

• Secure authentication with MFA support
• Comprehensive API coverage for Monarch Money
• Session management and persistence
• Well-documented and maintained codebase

Thank you to @hammem for creating and maintaining this essential library!

📄 License

MIT License

🆘 Support

For issues:

1. Check authentication with check_auth_status
2. Run the setup command again: cd /path/to/your/monarch-mcp-server && python login_setup.py
3. Check error logs for detailed messages
4. Ensure Monarch Money service is accessible

🔄 Updates

To update the server:

1. Pull latest changes from repository
2. Restart Claude Desktop
3. Re-run authentication if needed: python login_setup.py