Lunch Money MCP Server

A Model Context Protocol (MCP) server for the Lunch Money API v2, designed with minimal response sizes to prevent context window bloat.

Features

• Optimized responses: Concise, formatted output to minimize token usage

• Simple authentication: Uses environment variable for API token

• Type-safe: Built with modern Python type hints

• Easy to extend: Add more endpoints one at a time

Related MCP server: LunchMoney MCP Server

Currently Supported Endpoints

• add_numbers - Helper tool for arithmetic operations

• get_current_user - Get information about the authenticated user (GET /me)

• get_transaction - Get details about a specific transaction by ID (GET /transactions/{id})

• get_transactions - List transactions for a date range (GET /transactions)

Installation

1. Clone this repository:

git clone <your-repo-url>
cd lunchmoney-mcp-mini

2. Install dependencies using uv:

uv sync

Configuration

Get Your API Token

1. Log in to Lunch Money

2. Go to the Developers page

3. Create a new API token or use an existing one

Set Environment Variable

export LUNCHMONEY_API_TOKEN="your-api-token-here"

Or create a .env file (not committed to git):

LUNCHMONEY_API_TOKEN=your-api-token-here

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "lunchmoney-mini": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/lunchmoney-mcp-mini",
        "run",
        "lunchmoney_mcp_mini/main.py"
      ],
      "env": {
        "LUNCHMONEY_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Standalone Testing

# Make sure LUNCHMONEY_API_TOKEN is set
uv run lunchmoney_mcp_mini/main.py

Available Tools

add_numbers

Helper tool for performing arithmetic operations with precise decimal handling to avoid floating-point precision issues.

Parameters:

• numbers (required): List of numbers to add together. Can include negative values for subtraction.

Returns:

• sum: Sum rounded to 2 decimal places

• input_count: Number of values provided

Example output:

{
  "sum": 123.45,
  "input_count": 3
}

get_current_user

Get details about the authenticated Lunch Money user.

Returns:

• name: User's full name

• email: User's email address

• user_id: Unique user identifier

• account_id: Unique account identifier

• budget_name: Name of the budget

• primary_currency: Primary currency code (e.g., 'usd')

• api_key_label: Label for the API key being used

Example output:

{
  "name": "John Doe",
  "email": "john@example.com",
  "user_id": 12345,
  "account_id": 67890,
  "budget_name": "Family budget",
  "primary_currency": "usd",
  "api_key_label": "Development key"
}

get_transaction

Get full details about a specific transaction by its ID.

Parameters:

• transaction_id (required): ID of the transaction to retrieve

Returns: Complete transaction object with all available fields including:

• Core data: id, date, amount, currency, payee, original_name

• Category/accounts: category_id, manual_account_id, plaid_account_id, recurring_id

• Metadata: plaid_metadata, custom_metadata, files (if any)

• Grouping/splitting: is_split_parent, split_parent_id, is_group_parent, group_parent_id, children

• Timestamps: created_at, updated_at

• Status: status, is_pending, source, external_id, tag_ids, notes

Example output:

{
  "id": 2112150655,
  "date": "2024-07-28",
  "amount": -45.50,
  "currency": "USD",
  "payee": "Whole Foods",
  "original_name": "WHOLE FOODS #1234",
  "category_id": 82,
  "status": "reviewed",
  "is_pending": false,
  "created_at": "2024-07-28T12:34:56.789Z",
  "updated_at": "2024-07-28T12:34:56.789Z"
}

get_transactions

List transactions within a specified date range.

Parameters:

• start_date (required): Start date in YYYY-MM-DD format

• end_date (optional): End date in YYYY-MM-DD format. Defaults to last day of start_date's month

• category_id (optional): Filter by category ID

• tag_id (optional): Filter by tag ID

• status (optional): Filter by status ("reviewed", "unreviewed", "delete_pending")

• is_pending (optional): Filter by pending status

• manual_account_id (optional): Filter by manual account ID

• plaid_account_id (optional): Filter by plaid account ID

• recurring_id (optional): Filter by recurring item ID

• include_pending (optional): Include pending transactions

• limit (optional): Maximum number of transactions (1-2000, default 100)

• offset (optional): Pagination offset

• include_aggregates (optional): If True, calculates totals per category for full date range (respects all filters)

Returns:

• transactions: Array of transaction objects

• has_more: Boolean indicating if more transactions are available

• aggregates (optional): Category totals and counts when include_aggregates=True

Transaction fields:

• id: Transaction ID

• date: Transaction date (YYYY-MM-DD)

• amount: Transaction amount (numeric string)

• payee: Payee name

• category_id: Category ID

• status: Transaction status

• is_pending: Pending status

Aggregates fields (when include_aggregates=True):

• by_category: Array sorted by total_amount descending, each with:

  • category_id: Category ID (or null for uncategorized)

  • category_name: Category name

  • count: Number of transactions in this category

  • total_amount: Sum of transaction amounts (numeric string)

• total_count: Total number of transactions

• total_amount: Sum of all transaction amounts (numeric string)

Example output (without aggregates):

{
  "transactions": [
    {
      "id": 2112150655,
      "date": "2024-07-28",
      "amount": "1250.8400",
      "payee": "Paycheck",
      "category_id": 88,
      "status": "reviewed",
      "is_pending": false
    }
  ],
  "has_more": false
}

Example output (with aggregates):

{
  "transactions": [...],
  "has_more": false,
  "aggregates": {
    "by_category": [
      {"category_id": 88, "category_name": "Rent", "count": 2, "total_amount": "2500.00"},
      {"category_id": 82, "category_name": "Groceries", "count": 5, "total_amount": "245.50"},
      {"category_id": null, "category_name": "Uncategorized", "count": 3, "total_amount": "45.00"}
    ],
    "total_count": 10,
    "total_amount": "2790.50"
  }
}

Design Philosophy

This MCP server is intentionally designed to return minimal, focused responses to avoid filling up the context window. Each tool:

• Returns only essential information

• Uses concise formatting

• Avoids verbose JSON dumps

• Provides human-readable output

Technical Details

This server uses:

• FastMCP: A high-level Python framework for building MCP servers

• requests-openapi: Automatically generates API client from OpenAPI spec

• OpenAPI 3.0 spec: Ensures type safety and accurate API calls

The combination of FastMCP and requests-openapi means:

• Less boilerplate code

• Automatic request/response validation

• Easy to add new endpoints from the spec

• Type-safe API calls

Resources

• Lunch Money API Documentation

• Model Context Protocol

• FastMCP Documentation

• requests-openapi

License

MIT