Monarch Money MCP Server

1# Monarch Money MCP Server
2 
3A Model Context Protocol (MCP) server that provides read-only access to Monarch Money financial data. This allows AI assistants like Claude Desktop to analyze your financial information, transactions, budgets, and cashflow data.
4 
5Note: I've created this for personal fun and is not affiated with Monarch Money. I mostly created it for learning about my spending, using it for projections. Since I don't have any need to mutate any data it's currently READONLY.
6 
7Shout out to 
8 
9## Features
10 
11- **Read-only access** to Monarch Money accounts
12- **Transaction analysis** with date filtering and search
13- **Budget tracking** and cashflow analysis
14- **Account details** including investment holdings
15- **Secure authentication** with MFA support
16- **Session persistence** to minimize re-authentication
17 
18## Installation
19 
20### Prerequisites
21 
22- Python 3.13+
23- [uv](https://docs.astral.sh/uv/) package manager (recommended)
24- A Monarch Money account
25 
26### Setup
27 
281. **Clone the repository:**
29 
302. **Install dependencies:**
31   ```bash
32   uv add mcp monarchmoney python-dotenv
33   ```
34 
353. **Configure environment variables:**
36   ```bash
37   cp .env.example .env
38   ```
39   
40   Edit `.env` with your Monarch Money credentials:
41   ```
42   MONARCH_EMAIL=your-email@example.com
43   MONARCH_PASSWORD=your-monarch-password
44   MONARCH_MFA_SECRET=your-mfa-secret-key  # Optional but recommended
45   ```
46 
474. **Test the connection:**
48   ```bash
49   python test_api.py
50   ```
51 
52## Usage
53 
54### Running the Server
55 
56Start the MCP server:
57```bash
58python run_server.py
59```
60 
61### Claude Desktop Integration
62 
63Add to your Claude Desktop configuration (`claude_desktop_config.json`):
64 
65```json
66{
67  "mcpServers": {
68    "monarch-money": {
69      "command": "python",
70      "args": ["/path/to/monarch-mcp-server/run_server.py"],
71      "env": {
72        "MONARCH_EMAIL": "your-email@example.com",
73        "MONARCH_PASSWORD": "your-password",
74        "MONARCH_MFA_SECRET": "your-mfa-secret"
75      }
76    }
77  }
78}
79```
80 
81## Available Resources
82 
83- `monarch://accounts` - All linked accounts
84- `monarch://transactions/recent` - Last 100 transactions  
85- `monarch://budgets` - Budget information with actual vs target
86- `monarch://cashflow/summary` - Income, expenses, and savings summary
87 
88## Available Tools
89 
90- **get_transactions** - Get transactions with date range filtering
91- **get_account_details** - Detailed account information including holdings
92- **get_cashflow_analysis** - Cashflow analysis by category and time period
93- **search_transactions** - Search transactions by description or merchant
94- **get_categories** - All transaction categories
95- **get_institutions** - Linked financial institutions
96 
97## Example Prompts
98 
99Once configured with Claude Desktop, you can ask:
100 
101- "Show me my recent transactions from last month"
102- "What's my current budget status?"
103- "Analyze my spending patterns by category"
104- "How much did I spend on groceries this year?"
105- "What are my investment account balances?"
106 
107## Security
108 
109- **No write operations** - Server is read-only for safety
110- **Local credentials** - Your login details stay on your machine
111- **Session caching** - Reduces authentication frequency
112- **MFA support** - Two-factor authentication recommended
113 
114## Troubleshooting
115 
116### Authentication Issues
117 
1181. **Run the debug script:**
119   ```bash
120   python debug_server.py
121   ```
122 
1232. **Check environment variables:**
124   ```bash
125   python -c "import os; print('Email:', bool(os.getenv('MONARCH_EMAIL'))); print('Password:', bool(os.getenv('MONARCH_PASSWORD')))"
126   ```
127 
1283. **Clear session cache:**
129   ```bash
130   rm -rf .mm/
131   ```
132 
133### Common Issues
134 
135- **MFA required**: Set `MONARCH_MFA_SECRET` environment variable
136- **Session expired**: Delete `.mm/` directory to force fresh login
137- **Import errors**: Ensure all dependencies installed with `uv add`
138 
139## Development
140 
141### Project Structure
142 
143```
144monarch-mcp-server/
145├── monarch_mcp_server.py     # Main MCP server implementation
146├── run_server.py             # Server launcher script
147├── debug_server.py           # Authentication debugging
148├── test_api.py              # API connection testing
149├── tests/                   # Unit tests
150│   ├── __init__.py
151│   └── test_monarch_mcp_server.py
152├── pyproject.toml           # Project dependencies
153├── .github/workflows/       # CI/CD workflows
154└── .env.example             # Environment template
155```
156 
157### Testing
158 
159Install test dependencies:
160```bash
161uv sync --extra test
162```
163 
164Run the unit test suite:
165```bash
166uv run pytest tests/ -v
167```
168 
169Run tests with coverage:
170```bash
171uv run pytest tests/ --cov=monarch_mcp_server --cov-report=term
172```
173 
174Run manual API test:
175```bash
176python test_api.py
177```
178 
179## Contributing
180 
1811. Fork the repository
1822. Create a feature branch
1833. Make your changes
1844. Test thoroughly
1855. Submit a pull request
186 
187## License
188 
189MIT License - see [LICENSE](LICENSE) file for details.
190 
191## Disclaimer
192 
193This project is not affiliated with Monarch Money. Use at your own risk and ensure compliance with Monarch Money's terms of service.
194