# Monarch Money MCP Server
A Model Context Protocol (MCP) server that provides seamless integration between [Monarch Money](https://monarchmoney.com) and Claude Desktop. This server enables you to query your financial data, analyze spending patterns, and get personalized financial insights directly through conversational AI.
## 🚀 Features
- **🏦 Account Management**: View all accounts with real-time balances and details
- **💳 Transaction Analysis**: Search and filter transactions with advanced criteria
- **📊 Spending Insights**: Analyze spending patterns by category, merchant, and time period
- **💰 Budget Tracking**: Monitor budget performance with planned vs. actual spending
- **📈 Net Worth Calculation**: Track your total net worth and asset allocation
- **📅 Monthly Reports**: Generate comprehensive monthly financial summaries
- **🏷️ Category Management**: Explore and analyze transaction categories
- **📉 Balance History**: View account balance trends over time
- **🔐 Secure Authentication**: Token-based authentication with MFA support
## 🛡️ Security & Privacy
- **Token-based authentication** - No need to store credentials long-term
- **Environment variable protection** - Credentials never hardcoded
- **Multi-factor authentication support** - Enhanced security for your financial data
- **GraphQL API integration** - Secure communication with Monarch Money
- **Local processing** - All analysis happens on your machine
## 📋 Prerequisites
Before you begin, ensure you have:
- **Node.js 18+** installed on your system
- **Claude Desktop** application installed
- **Monarch Money account** with valid credentials
- **npm** or **yarn** package manager
## 🔧 Installation
### 1. Clone the Repository
```bash
git clone https://github.com/whitebirchio/monarch-mcp.git
cd monarch-mcp
```
### 2. Install Dependencies
```bash
npm install
```
### 3. Authentication Setup
**🔑 Option A: Token Authentication (Recommended)**
1. Get your authentication token:
```bash
npm run login
```
2. Follow the prompts to enter your Monarch Money credentials and MFA code (if required)
3. Copy the generated token for use in Claude Desktop configuration
**📧 Option B: Direct Credentials**
Create a `.env` file with your credentials:
```bash
MONARCH_TOKEN=your-auth-token-here
```
### 4. Build the Project
```bash
npm run build
```
## ⚙️ Claude Desktop Configuration
### macOS Configuration
Edit your Claude Desktop config file:
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```
Add this configuration:
```json
{
"mcpServers": {
"monarch-money": {
"command": "node",
"args": ["/absolute/path/to/monarch-mcp/dist/index.js"],
"env": {
"MONARCH_TOKEN": "your-auth-token-here"
}
}
}
}
```
### Windows Configuration
Edit your Claude Desktop config file:
```
%APPDATA%/Claude/claude_desktop_config.json
```
Use the same JSON structure with Windows-style paths:
```json
{
"mcpServers": {
"monarch-money": {
"command": "node",
"args": ["C:\\path\\to\\monarch-mcp\\dist\\index.js"],
"env": {
"MONARCH_TOKEN": "your-auth-token-here"
}
}
}
}
```
**💡 Important**: Use the absolute path to your installation directory.
## 🎯 Usage Examples
After configuring Claude Desktop and restarting the application, you can ask questions like:
### 💰 Financial Overview
- _"What's my current net worth?"_
- _"Show me all my account balances"_
- _"What's my checking account balance?"_
### 📊 Spending Analysis
- _"How much did I spend on groceries last month?"_
- _"Show me my largest expenses from the past week"_
- _"Break down my spending by category for Q3"_
- _"Find all transactions over $500 this year"_
### 📈 Budget Insights
- _"How am I doing against my budget this month?"_
- _"Which budget categories am I overspending in?"_
- _"Show me my budget vs actual for each category"_
### 🔍 Transaction Search
- _"Find all Amazon purchases from last month"_
- _"Show me restaurant transactions over $50"_
- _"What did I spend at Costco this year?"_
### 📅 Historical Analysis
- _"Compare my spending this month vs last month"_
- _"Show my account balance trends for the past 6 months"_
- _"What was my net income last month?"_
## 🛠️ Available Tools
| Tool | Description | Parameters |
| -------------------------- | ---------------------------------- | -------------------------------------------- |
| `get_accounts` | List all financial accounts | None |
| `get_account_balance` | Get specific account balance | `accountId` |
| `get_transactions` | Retrieve transactions with filters | `limit`, `accountId`, `startDate`, `endDate` |
| `get_spending_by_category` | Spending breakdown by category | `startDate`, `endDate` |
| `get_budget_summary` | Current budget status | None |
| `search_transactions` | Search transactions by criteria | `query`, `minAmount`, `maxAmount`, `limit` |
| `get_net_worth` | Calculate total net worth | None |
| `get_monthly_summary` | Monthly financial summary | `year`, `month` |
| `get_categories` | List all transaction categories | None |
| `get_account_snapshots` | Account balance history | `accountId`, `startDate`, `endDate` |
## 🔧 Development
### Development Commands
```bash
# Run in development mode
npm run dev
# Build for production
npm run build
# Start production server
npm start
# Get authentication token
npm run login
```
### Project Structure
```
monarch-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── login.ts # Authentication helper
│ ├── monarch-api.ts # Monarch Money API client
│ └── tools.ts # MCP tool implementations
├── dist/ # Compiled JavaScript output
├── package.json # Project dependencies
├── tsconfig.json # TypeScript configuration
└── README.md # This file
```
### API Architecture
The server implements a three-layer architecture:
1. **MCP Layer** (`index.ts`) - Handles Model Context Protocol communication
2. **Tools Layer** (`tools.ts`) - Implements financial analysis tools
3. **API Layer** (`monarch-api.ts`) - Manages Monarch Money GraphQL API integration
## 🐛 Troubleshooting
### Authentication Issues
| Problem | Solution |
| ------------------- | ------------------------------------------------- |
| Invalid credentials | Verify your email/password in the login command |
| MFA required | Use the `npm run login` command which handles MFA |
| Token expired | Re-run `npm run login` to get a fresh token |
### Integration Issues
| Problem | Solution |
| ------------------- | ----------------------------------------- |
| Tools not appearing | Restart Claude Desktop completely |
| Server not starting | Verify the absolute path in config file |
| Permission errors | Check file permissions on `dist/index.js` |
### Common Error Messages
- **"MONARCH_TOKEN environment variable is required"** - Add your token to the Claude Desktop config
- **"Authentication failed"** - Check your token validity and regenerate if needed
- **"GraphQL Error (Code: 400)"** - API request format issue (usually handled automatically)
## 🤝 Contributing
We welcome contributions! Here's how to get started:
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Make** your changes
4. **Test** thoroughly with your own Monarch Money account
5. **Commit** your changes (`git commit -m 'Add amazing feature'`)
6. **Push** to your branch (`git push origin feature/amazing-feature`)
7. **Open** a Pull Request
### Development Guidelines
- Follow TypeScript best practices
- Add proper error handling
- Update documentation for new features
- Test with real Monarch Money data
- Maintain backwards compatibility
## 📄 License
This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.
## ⚠️ Disclaimer
This project is an independent integration and is not affiliated with, endorsed by, or sponsored by Monarch Money.
**Important Notes:**
- Use this software at your own risk
- Always verify financial data independently
- Never make financial decisions based solely on automated tools
- Keep your authentication credentials secure
- Review all transactions and calculations manually
## 🙋♂️ Support
- **Issues**: [GitHub Issues](https://github.com/whitebirchio/monarch-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/whitebirchio/monarch-mcp/discussions)
- **Documentation**: This README and inline code comments
---
Made with ❤️ for the Claude Desktop community
