Lunch Money

You can use the Lunch Money MCP Server (HTTP) to access and manage your Lunch Money data through a standardized API. This server lets you work with user details, categories, tags, transactions, recurring items, budgets, and assets, making it easy to integrate Lunch Money data with AI assistants and automation tools.

How to use

You interact with the MCP server through an MCP client. Start by connecting to the remote server endpoint, then perform actions such as retrieving your user details, listing and managing categories and tags, creating and updating transactions, handling recurring items, budgeting, and asset tracking. The server exposes endpoints that align with common data operations you perform in Lunch Money, enabling seamless data access and manipulation for your workflows.

How to install

# Prerequisites
node -v
# Node.js 18+ is required

# Step 1: Clone or download the project
git clone https://example.com/ LunchMoneyMCP

# Step 2: Install dependencies
npm install

# Step 3: Create environment file from template
cp .env.example .env

# Step 4: Configure environment variables
# Open .env and set your Lunch Money API token and port
LUNCH_MONEY_API_TOKEN=your_api_token_here
PORT=8080

# Step 5: Run in development mode with hot reloading
npm run dev

# Step 6: Build for production and start
npm run build
npm start

The server will listen on port 8080 by default or the port you set in the .env file.

## Configuration and security

Environment variables you will configure include the Lunch Money API token and the server port. Optionally, you can set SERVER\_API\_KEY to require an API key for all requests. If SERVER\_API\_KEY is set, clients must include a valid Authorization header for every request.

Environment variables used by the server:
- LUNCH\_MONEY\_API\_TOKEN: Your Lunch Money API access token
- PORT: Server port (default 8080)
- SERVER\_API\_KEY: Optional API key for authenticating requests (Bearer token or plain key in the Authorization header)

## Deployment notes

You can deploy the MCP server to Fly.io with API key authentication. Use your own app name and secrets to secure access.

Health checks and public endpoints are available at the deployed URL. For example, the MCP endpoint is typically exposed at /mcp and a health check is available at /health.

## Testing and health checks

Test the MCP server with development tools to ensure the server is responding as expected. Use the provided test utilities to verify that you can list tools and call operations such as getUser, getCategories, getTransactions, and more.

## Available tools

### getUser

Retrieve the current user's account details including email, name, currency preferences, and settings

### getCategories

List all categories including category groups and parent categories

### createCategory

Create a new spending or income category

### updateCategory

Update properties of an existing category

### deleteCategory

Delete a category by ID

### getTags

List all transaction tags

### createTag

Create a new transaction tag

### updateTag

Update an existing tag's name

### deleteTag

Delete a tag by ID

### getTransactions

List transactions with advanced filtering options including date range, category, tags, account, status, and pagination

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

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

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

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