whitebirchio/monarch-mcp

Monarch Money MCP Server

A Model Context Protocol (MCP) server that provides seamless integration between Monarch Money 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

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

2. Install Dependencies

npm install

3. Authentication Setup

🔑 Option A: Token Authentication (Recommended)

1. Get your authentication token:

   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:

MONARCH_TOKEN=your-auth-token-here

4. Build the Project

npm run build

⚙️ Claude Desktop Configuration

macOS Configuration

Edit your Claude Desktop config file:

~/Library/Application Support/Claude/claude_desktop_config.json

Add this configuration:

{
  "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:

{
  "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

🔧 Development

Development Commands

# 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

Integration Issues

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 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
• Discussions: GitHub Discussions
• Documentation: This README and inline code comments

Made with ❤️ for the Claude Desktop community