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)

Get your authentication token:
```
npm run login
```
Follow the prompts to enter your Monarch Money credentials and MFA code (if required)
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

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

# 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:

MCP Layer (index.ts) - Handles Model Context Protocol communication
Tools Layer (tools.ts) - Implements financial analysis tools
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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Test thoroughly with your own Monarch Money account
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
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 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

Monarch Money MCP Server

🚀 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)

Get your authentication token:
```
npm run login
```
Follow the prompts to enter your Monarch Money credentials and MFA code (if required)
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

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

# 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:

MCP Layer (index.ts) - Handles Model Context Protocol communication
Tools Layer (tools.ts) - Implements financial analysis tools
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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Test thoroughly with your own Monarch Money account
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
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 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