Lunchmoney MCP Server

🚀 Lunch Money MCP Server

A Model Context Protocol (MCP) server that allows you to interact with Lunchmoney (https://lunchmoney.app) transactions and budgets through Claude and other AI assistants.

🚀 Quick Start

This tool enables you to connect your Lunchmoney financial data to Claude AI. You can then inquire about expenses, analyze budgets, and gain financial insights through natural conversations.

✨ Features

This server offers four main features:

1. Get Recent Transactions: View recent transactions from the past N days.
2. Search Transactions: Search for transactions by the payer's name or keywords in the notes.
3. Expenses by Category: Analyze the spending in specific categories.
4. Budget Overview: Obtain detailed budget information, including expenses, remaining amounts, and recurring items.

📄 Privacy and Data Handling

⚠️ Important Note

MCP provides a structured way for Claude to interact with your Lunchmoney data while maintaining privacy boundaries. Here's what you need to note:

• Claude (host) creates a client to connect to your local MCP server.
• Your Lunchmoney API token remains on your local machine.
• The MCP server runs locally and fetches data from Lunchmoney's API.
• You'll be prompted to approve each request to access your Lunchmoney data.
• When you ask financial questions, Claude requests specific information from the MCP server.
• The MCP server processes your requests locally and only returns relevant results.
• Claude never directly accesses your full financial data or API token.
• Only the specific requested information (such as transaction summaries or budget status) is shared with Claude.
• Anthropic's data retention policy applies to these summary results as part of your conversation.
• Each server connection is isolated, maintaining clear security boundaries.

You can find more information about MCP in the documentation: https://modelcontextprotocol.io/introduction

📦 Installation

Please also refer to the official Claude documentation: https://modelcontextprotocol.io/quickstart/user

Using npx

Node.js is a software platform that allows you to run JavaScript code on your computer (not in a web browser).

Install Node.js:

• Windows/Mac: Download and run the installer from the official Node.js website.
• Mac with Homebrew: Run brew install node in the terminal.
• Linux: Use your package manager (e.g., sudo apt install nodejs for Ubuntu).

After installation, you can run the server directly without downloading anything:

1. Obtain your Lunchmoney API token from your Lunchmoney developer settings.
2. Open Claude Desktop.
3. Go to Settings → Developers → Edit Configuration.
4. Add the following configuration:

{
  "mcpServers": {
    "lunchmoney": {
      "command": "npx",
      "args": ["-y", "lunchmoney-mcp-server"],
      "env": {
        "LUNCHMONEY_TOKEN": "your_token_here"
      }
    }
  }
}

Replace your_token_here with your actual Lunchmoney API token.

⚠️ Important Note

You may need to restart Claude for the changes to take effect after modifying the configuration.

💻 Usage Examples

Basic Usage

• Get Recent Transactions: Send a request to the MCP server to get transaction records from the past 7 days.
• Search Transactions: Filter specific transactions by specifying keywords or categories.
• Expenses by Category: Analyze the total expenditure in different categories.
• Budget Overview: Check the current remaining amount and usage of each budget item.

📚 Documentation

The Model Context Protocol (MCP) is a standardized interface for connecting different AI services and data sources. Through MCP, more efficient data interaction and task processing can be achieved.

🔧 Troubleshooting

If you encounter issues, follow these steps:

1. Ensure that Node.js is installed correctly.
2. Check if your Lunchmoney API token is valid.
3. Confirm that your network connection is normal.
4. Check the MCP server logs for more information.

📄 API Documentation

• Date Range: Budgets use the YYYY-MM-DD format (e.g., from 2024-01-01 to 2024-01-31).
• Transaction Range: Any date range can be used.
• Currency Values: All amounts are returned in the original currency.

📄 License

MIT

Contribution Guidelines

Contributions are welcome! Please feel free to submit pull requests.