Lunch Money MCP Server (HTTP)

A MCP (HTTP) server providing full integration with the Lunch Money API. This server enables AI assistants to interact with your Lunch Money financial data through a standardized interface.

Note: This is designed to be used as a streamable HTTP server. If you're looking for local MCP support (stdio transport), see akutishevsky/lunchmoney-mcp.

Features

• 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

Prerequisites

• Node.js 18+ (for native fetch support)
• A Lunch Money API access token (Get one here)

Installation

1. Clone or download this repository
2. Install dependencies:

npm install

3. Copy .env.example to .env and add your API token:

cp .env.example .env

Edit .env and add your Lunch Money API token:

LUNCH_MONEY_API_TOKEN=your_api_token_here
PORT=8080

Usage

Development Mode

Run the server in development mode with hot reload:

npm run dev

Production Mode

Build and run:

npm run build
npm start

The server will start on port 8080 (or the port specified in your .env file).

Testing with FastMCP CLI

You can test the server using the FastMCP development tools:

npx fastmcp dev src/index.ts

Or use the MCP Inspector:

npx fastmcp inspect src/index.ts

Testing with MCP Test Client

This project includes a test client script that connects to your MCP server and allows you to test tools programmatically.

First, make sure your server is running:

npm run dev

Then in another terminal, install dependencies (if not already installed) and run the test client:

npm install
npm run test:client

Available test client commands:

• List all available tools:

  npm run test:client -- --list
  

• Call a specific tool (defaults to getUser):

  npm run test:client -- --tool getUser
  npm run test:client -- --tool getCategories
  npm run test:client -- --tool getTransactions
  

• Call a tool with arguments:

  npm run test:client -- --tool getTransactions --args '{"start_date":"2024-01-01","end_date":"2024-12-31"}'
  

• Show help:

  npm run test:client -- --help
  

Environment Variables:

You can configure the test client using environment variables:

• MCP_SERVER_URL - Server URL (default: http://localhost:8080)
• MCP_ENDPOINT - MCP endpoint path (default: /mcp - FastMCP's httpStream default)

Available Tools

User Management

• getUser - Get the current user's account details including email, name, currency preferences, and settings

Categories

• getCategories - List all categories including category groups and parent categories
• createCategory - Create a new spending or income category
• updateCategory - Update an existing category's properties
• deleteCategory - Delete a category by ID

Tags

• getTags - List all transaction tags
• createTag - Create a new tag for categorizing transactions
• updateTag - Update an existing tag's name
• deleteTag - Delete a tag by ID

Transactions

• getTransactions - List transactions with advanced filtering options including:
  • Date range (start_date, end_date)
  • Category (category_id)
  • Tags (tag_id)
  • Account (account_id)
  • Status (cleared, uncleared, recurring, recurring_suggested)
  • Pagination (offset, limit)
• createTransaction - Create a new transaction (expense, income, or transfer)
• updateTransaction - Update an existing transaction's properties
• deleteTransaction - Delete a transaction by ID
• bulkUpdateTransactions - Bulk update multiple transactions with the same changes

Recurring Items

• getRecurringItems - List all recurring expense and income items
• createRecurringItem - Create a new recurring expense or income item
• updateRecurringItem - Update an existing recurring item's properties
• deleteRecurringItem - Delete a recurring item by ID

Budgets

• getBudgets - List all budgets with their category assignments and date ranges
• createBudget - Create a new budget for a category with amount and date range
• updateBudget - Update an existing budget's amount, category, or date range
• deleteBudget - Delete a budget by ID

Assets

• getAssets - List all manually-managed assets
• createAsset - Create a new manually-managed asset
• updateAsset - Update an existing asset's properties including balance and metadata
• deleteAsset - Delete an asset by ID

Configuration

Environment Variables

• LUNCH_MONEY_API_TOKEN (required) - Your Lunch Money API access token
• PORT (optional) - Server port, defaults to 8080
• SERVER_API_KEY (optional) - API key for server authentication. If set, all requests must include this key in the Authorization header (format: Bearer <key> or just <key>)

Using with Claude Desktop

Add the following to your Claude Desktop configuration file:

{
  "mcpServers": {
    "lunch-money": {
      "command": "node",
      "args": ["/path/to/lunch-money-mcp/dist/index.js"],
      "env": {
        "LUNCH_MONEY_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Or for development:

{
  "mcpServers": {
    "lunch-money": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/lunch-money-mcp",
      "env": {
        "LUNCH_MONEY_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Deployment

Deploying to Fly.io

This MCP server can be deployed to Fly.io with API key authentication.

Prerequisites

1. Install the Fly.io CLI:

   curl -L https://fly.io/install.sh | sh
   

2. Authenticate with Fly.io:

   fly auth login
   

Initial Setup

1. Launch your app (this will create fly.toml if it doesn't exist):

   fly launch --no-deploy
   

   During setup:

   • Choose a unique app name (or use the default)
   • Select your preferred region
   • Decline adding a database (not needed)
   • Don't deploy yet (we'll set secrets first)

2. Set your secrets (API keys):

   fly secrets set LUNCH_MONEY_API_TOKEN=your_lunch_money_token
   fly secrets set SERVER_API_KEY=your_secure_api_key_here
   

   Important: Generate a strong, random API key for SERVER_API_KEY. This will be used to authenticate requests to your MCP server.

3. Deploy your application:

   fly deploy
   

4. Verify deployment:

   fly status
   

Using Your Deployed Server

Once deployed, your server will be available at https://your-app-name.fly.dev/mcp.

With API Key Authentication:

All requests must include the API key in the Authorization header:

curl -H "Authorization: Bearer your_secure_api_key_here" \
     https://your-app-name.fly.dev/mcp

Health Check:

The server includes a health check endpoint using FastMCP's built-in /health endpoint (no authentication required):

curl https://your-app-name.fly.dev/health

Managing Secrets

• View secrets: fly secrets list
• Update a secret: fly secrets set SERVER_API_KEY=new_key
• Remove a secret: fly secrets unset SERVER_API_KEY

Updating Your Deployment

After making code changes:

fly deploy

Viewing Logs

fly logs

API Reference

This MCP server integrates with the Lunch Money API v1. All endpoints follow the official API documentation.

License

MIT

Contributing

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