lunchmoney-mcp

The definitive MCP server for Lunch Money -- manage your finances through any AI assistant that supports the Model Context Protocol.

37 tools covering every Lunch Money API endpoint. Runs locally via stdio or remotely over HTTP with OAuth 2.1. Credentials never touch disk in plain text.

Quick Start

npx lunchmoney-mcp setup          # Store your API token in the OS keychain
npx lunchmoney-mcp                # Start the MCP server (stdio)

Then add it to your MCP client. For Claude Desktop, add this to your config:

{
  "mcpServers": {
    "lunchmoney": {
      "command": "npx",
      "args": ["lunchmoney-mcp"]
    }
  }
}

That's it. Ask your AI assistant to "show my recent transactions" and you're off.

Features

• 37 tools -- full CRUD for transactions, categories, tags, budgets, recurring items, assets, and Plaid accounts

• Two transport modes -- stdio for local AI clients (Claude Desktop, Cursor) or HTTP for remote/multi-user deployments

• Secure credential storage -- API tokens in the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager); OAuth session tokens encrypted with AES-256-GCM

• 4 OAuth providers -- Google, GitHub, CyberArk Identity, or any custom OAuth 2.1 provider

• Deploy anywhere -- Docker, systemd, Railway, Render, Fly.io with one-click configs included

• 278 tests -- comprehensive test suite with >90% coverage

Setup

Local (stdio mode)

Best for single-user setups with Claude Desktop, Cursor, or other local MCP clients.

# Install globally (optional -- npx works too)
npm install -g lunchmoney-mcp

# Run the setup wizard to store your token securely
lunchmoney-mcp setup

# Start the server
lunchmoney-mcp

Your API token is stored in the OS keychain and never written to disk. Get a token at my.lunchmoney.app/developers.

Alternatively, you can configure the token from within your AI assistant using the configureLunchMoneyToken tool -- no terminal required.

Remote (HTTP mode)

Best for multi-user deployments, shared teams, or running on a server.

# Set required environment variables
export LUNCH_MONEY_API_TOKEN="your-token"
export AUTH_PROVIDER="google"  # or github, cyberark, custom
export GOOGLE_CLIENT_ID="..."
export GOOGLE_CLIENT_SECRET="..."
export BASE_URL="https://your-domain.com"

# Start the server
lunchmoney-mcp --http --port 8080

HTTP mode requires OAuth 2.1 for authentication. See Authentication below.

Environment Variable Fallback

For containers and CI where no OS keychain is available:

export LUNCH_MONEY_API_TOKEN="your-token"
lunchmoney-mcp

Authentication

HTTP mode supports four OAuth providers. Set AUTH_PROVIDER and the corresponding credentials:

Google

AUTH_PROVIDER=google
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

GitHub

AUTH_PROVIDER=github
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret

CyberArk Identity

AUTH_PROVIDER=cyberark
CYBERARK_TENANT_URL=https://abc1234.id.cyberark.cloud
CYBERARK_CLIENT_ID=your-client-id    # or OAUTH_CLIENT_ID
CYBERARK_CLIENT_SECRET=your-secret   # or OAUTH_CLIENT_SECRET

Custom OAuth

AUTH_PROVIDER=custom
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_AUTH_URL=https://provider.com/authorize
OAUTH_TOKEN_URL=https://provider.com/token
OAUTH_SCOPES=openid,email  # optional, defaults to openid,email

Deployment

Pre-built deployment configs are included in the repository.

Docker

docker build -t lunchmoney-mcp .
docker run -p 8080:8080 \
  -e LUNCH_MONEY_API_TOKEN="your-token" \
  -e AUTH_PROVIDER=google \
  -e GOOGLE_CLIENT_ID="..." \
  -e GOOGLE_CLIENT_SECRET="..." \
  -e BASE_URL="https://your-domain.com" \
  lunchmoney-mcp

Or with Docker Compose:

docker compose up

systemd

A systemd service file is included at deploy/lunchmoney-mcp.service. Copy it to /etc/systemd/system/ and configure the environment variables.

Railway

The included railway.json configures the build and start commands automatically. Set your environment variables in the Railway dashboard.

Render

The included render.yaml defines the service as a private worker. Set your environment variables in the Render dashboard.

Fly.io

fly launch
fly secrets set LUNCH_MONEY_API_TOKEN="your-token"
fly secrets set AUTH_PROVIDER=google GOOGLE_CLIENT_ID="..." GOOGLE_CLIENT_SECRET="..."
fly deploy

Tools Reference

Setup (1 tool)

User (1 tool)

Categories (7 tools)

Tags (4 tools)

Transactions (10 tools)

Recurring Items (4 tools)

Budgets (4 tools)

Assets (4 tools)

Plaid Accounts (2 tools)

CLI Reference

lunchmoney-mcp                  # Start in stdio mode (default)
lunchmoney-mcp --http           # Start in HTTP mode with OAuth
lunchmoney-mcp --http --port 3000  # HTTP mode on custom port
lunchmoney-mcp setup            # Run the interactive setup wizard
lunchmoney-mcp --version        # Print version

The server also reads the PORT environment variable when --port is not specified.

Security

Credentials are stored in your OS keychain and never written to disk in plain text. OAuth session tokens are encrypted with AES-256-GCM, with the encryption key stored in the keychain.

For full details on the two-tier credential architecture, threat model, and deployment security, see SECURITY.md.

Contributing

See CONTRIBUTING.md for development setup, testing guidelines, and pull request requirements.

License

MIT -- Copyright (c) 2026 Joe Garcia

Based on lunch-money-mcp by Gilbert Pellegrom, MIT License.