Lunchmoney MCP

🚀 LunchMoney MCP Server

A Model Context Protocol (MCP) server implementation for LunchMoney, enabling programmatic access to personal finance management via LunchMoney's API.

🚀 Quick Start

This MCP server allows AI assistants and other MCP clients to interact with LunchMoney data, facilitating automated financial insights, transaction management, budgeting, and more.

✨ Features

Comprehensive Tool Coverage

• User Management - Access user account details
• Categories - Create, update, and organize spending categories
• Tags - Manage transaction tags
• Transactions - Full CRUD operations on transactions with advanced filtering
• Recurring Items - Track and manage recurring expenses
• Budgets - Create and monitor budgets by category
• Assets - Track manually-managed assets
• Plaid Accounts - Manage connected bank accounts
• Cryptocurrency - Track crypto holdings

Key Capabilities

• Full integration with LunchMoney API v1
• Type-safe implementation with TypeScript and Zod validation
• Modular architecture for easy extension
• Standard MCP server implementation using stdio transport

💻 Usage Examples

With MCP Clients

To use this MCP server with any MCP-compatible client (such as Claude Desktop), you need to add it to the client's configuration.

Configuration

The server can be configured in your MCP client's configuration file. The exact location and format may vary by client, but typically follows this pattern:

{
  "mcpServers": {
    "lunchmoney": {
      "command": "npx",
      "args": ["@akutishevsky/lunchmoney-mcp"],
      "env": {
        "LUNCHMONEY_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Replace "your-api-token-here" with your actual LunchMoney API token from LunchMoney Developer Settings.

Common MCP Client Configuration Locations

Different MCP clients store their configuration in different locations:

• Claude Desktop:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

• Other MCP Clients: Check your client's documentation for the configuration file location.

Setup Steps

1. Locate your MCP client's configuration file (create it if it doesn't exist).
2. Add the LunchMoney server configuration to the mcpServers section.
3. Save the file and restart your MCP client.
4. The LunchMoney tools should now be available in your client.

Requirements

• Node.js 16+ installed on your system
• npx available in your system PATH
• Valid LunchMoney API token with appropriate permissions

As a standalone MCP server

# Run with npx
LUNCHMONEY_API_TOKEN="your-api-token" npx @akutishevsky/lunchmoney-mcp

Example Prompts

Here are some example prompts you can use with the LunchMoney MCP server:

Basic Usage

• Account Overview:
  • "Show me my LunchMoney account details"
  • "What's my current account status?"
• Category Management:
  • "List all my spending categories"
  • "Create a new category called 'Subscriptions' with a monthly budget of $100"
  • "Show me details for my 'Food & Dining' category"
  • "Create a category group for all my entertainment expenses"
  • "Delete the 'Unused Category' and reassign its transactions to 'Miscellaneous'"
• Transaction Management:
  • "Show me all transactions from last month"
  • "Find all transactions over $100 in the past week"
  • "Create a new expense for $45.99 at Amazon in the Shopping category"
  • "Update transaction #12345 to change the amount to $50"
  • "Show me all pending transactions"
  • "Group these coffee shop transactions together"
• Budgeting:
  • "Show me my budget summary for this month"
  • "Set a budget of $500 for Groceries this month"
  • "Remove the budget for Entertainment category"
  • "How much have I spent vs budgeted in each category?"
• Asset Tracking:
  • "List all my assets"
  • "Create a new asset for my savings account with a balance of $10,000"
  • "Update my investment account balance to $25,000"
• Recurring Expenses:
  • "Show me all my recurring expenses"
  • "What subscriptions do I have?"
  • "List recurring items for the next 3 months"
• Banking Integration:
  • "Show me all my connected Plaid accounts"
  • "Refresh my bank account data"
  • "Trigger a sync for my checking account"
• Cryptocurrency:
  • "Show me all my crypto holdings"
  • "Update my Bitcoin balance to 0.5 BTC"
  • "List all my manually tracked crypto assets"
• Analysis & Insights:
  • "What are my top spending categories this month?"
  • "Show me all transactions tagged as 'vacation'"
  • "Find all transactions at coffee shops"
  • "List all transactions that need to be categorized"

📚 Documentation

Available Tools

Development

Project Structure

lunchmoney-mcp/
├── src/
│   ├── index.ts           # Server entry point
│   ├── config.ts          # Configuration management
│   ├── types.ts           # TypeScript type definitions
│   └── tools/             # Tool implementations
│       ├── user.ts
│       ├── categories.ts
│       ├── tags.ts
│       ├── transactions.ts
│       ├── recurring-items.ts
│       ├── budgets.ts
│       ├── assets.ts
│       ├── plaid-accounts.ts
│       └── crypto.ts
├── build/                 # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Adding New Tools

1. Create a new file in src/tools/
2. Implement tool handlers using the MCP SDK
3. Register tools in src/index.ts
4. Add types to src/types.ts if needed

API Reference

The server implements the full LunchMoney API v1. For detailed API documentation, see:

• LunchMoney API Documentation
• Model Context Protocol Specification

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License