Lunch Money MCP Server

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.

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