# 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](https://github.com/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](https://my.lunchmoney.app/developers))

## Installation

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

```bash
npm install
```

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

```bash
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:

```bash
npm run dev
```

### Production Mode

Build and run:

```bash
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:

```bash
npx fastmcp dev src/index.ts
```

Or use the MCP Inspector:

```bash
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:

```bash
npm run dev
```

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

```bash
npm install
npm run test:client
```

**Available test client commands:**

- List all available tools:
  ```bash
  npm run test:client -- --list
  ```

- Call a specific tool (defaults to `getUser`):
  ```bash
  npm run test:client -- --tool getUser
  npm run test:client -- --tool getCategories
  npm run test:client -- --tool getTransactions
  ```

- Call a tool with arguments:
  ```bash
  npm run test:client -- --tool getTransactions --args '{"start_date":"2024-01-01","end_date":"2024-12-31"}'
  ```

- Show help:
  ```bash
  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:

```json
{
  "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:

```json
{
  "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:
   ```bash
   curl -L https://fly.io/install.sh | sh
   ```

2. Authenticate with Fly.io:
   ```bash
   fly auth login
   ```

#### Initial Setup

1. Launch your app (this will create `fly.toml` if it doesn't exist):
   ```bash
   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):
   ```bash
   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:
   ```bash
   fly deploy
   ```

4. Verify deployment:
   ```bash
   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:

```bash
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):

```bash
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:

```bash
fly deploy
```

#### Viewing Logs

```bash
fly logs
```

## API Reference

This MCP server integrates with the [Lunch Money API v1](https://lunchmoney.dev/). All endpoints follow the official API documentation.

## License

MIT

## Contributing

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