@akutishevsky/lunchmoney-mcp

v2.0.1

Published

3 days ago

Model Context Protocol server for LunchMoney personal finance management

Downloads

921

0High
0Medium
0Low

akutishevsky

mcp lunchmoney finance model-context-protocol ai assistant

LunchMoney MCP Server

A Model Context Protocol (MCP) server implementation for LunchMoney, providing programmatic access to personal finance management through LunchMoney's API. Also available as an MCP Bundle (.mcpb) for easy installation in Claude Desktop.

Heads up — v2.0.0 is a breaking release. This server now targets LunchMoney's v2 API (https://api.lunchmoney.dev/v2, currently in alpha). It is not backwards-compatible with v1.x of this server: tool names, fields, and endpoint shapes have changed (for example, assets is now manual_accounts, tags arrays are now tag_ids, transaction asset_id is now manual_account_id, the debit_as_negative toggle is gone, and the budget summary moved to a new /summary endpoint). See CHANGELOG.md for the full list. If you depend on v1.x, pin @akutishevsky/lunchmoney-mcp@^1.4.3.

Overview

This MCP server enables AI assistants and other MCP clients to interact with LunchMoney data, allowing for automated financial insights, transaction management, budgeting, and more.

Features

Comprehensive Tool Coverage

User Management - Access user account details
Categories - Full CRUD on categories and category groups
Tags - Full CRUD for transaction tags
Transactions - Full CRUD with advanced filtering, bulk update, bulk delete, splits, groups, and file attachments
Recurring Items - Track and manage recurring expenses, including system-suggested items
Budgets - Per-period budget summary, account-wide budget settings, upsert, and delete
Manual Accounts - Full CRUD for manually-managed accounts (formerly known as "assets")
Plaid Accounts - List, retrieve, and trigger sync of connected bank accounts
Cryptocurrency - Track synced and manual crypto holdings through LunchMoney's v1 crypto endpoints

Key Capabilities

Full integration with LunchMoney API v2 (alpha)
Type-safe implementation with TypeScript and Zod validation
Token-efficient responses using TOON encoding instead of JSON, reducing token usage in AI conversations
Modular architecture for easy extension
Standard MCP server implementation using stdio transport

Usage

Installation Options

MCP Bundle (.mcpb) - Recommended

The easiest way to install this server is as an MCP Bundle in Claude Desktop:

Download the latest .mcpb file from the releases page
Open Claude Desktop and go to Extensions
Click "Install Extension" and select the downloaded .mcpb file
Enter your LunchMoney API token when prompted (get it from LunchMoney Developer Settings)
The LunchMoney tools will be immediately available

Add the LunchMoney MCP server to Claude Code:

claude mcp add --transport stdio --env LUNCHMONEY_API_TOKEN=your-api-token-here lunchmoney -- npx -y @akutishevsky/lunchmoney-mcp

To enable debug logging:

claude mcp add --transport stdio --env LUNCHMONEY_API_TOKEN=your-api-token-here --env LUNCHMONEY_DEBUG=true lunchmoney -- npx -y @akutishevsky/lunchmoney-mcp

Verify the server was added:

claude mcp list
claude mcp get lunchmoney

Add the LunchMoney MCP server to Codex:

codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcp

To enable debug logging:

codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here --env LUNCHMONEY_DEBUG=true -- npx -y @akutishevsky/lunchmoney-mcp

Verify the server was added:

codex mcp list
codex mcp get lunchmoney

To use this MCP server with any MCP-compatible client (such as Claude Desktop), you need to add it to the client's configuration.

Configuration

The server can be configured in your MCP client's configuration file. The exact location and format may vary by client, but typically follows this pattern:

{
    "mcpServers": {
        "lunchmoney": {
            "command": "npx",
            "args": ["@akutishevsky/lunchmoney-mcp"],
            "env": {
                "LUNCHMONEY_API_TOKEN": "your-api-token-here",
                "LUNCHMONEY_DEBUG": "true"
            }
        }
    }
}

Note: LUNCHMONEY_DEBUG is optional. Set it to "true" to enable debug logging of API requests and responses to stderr. Useful for troubleshooting.

Replace "your-api-token-here" with your actual LunchMoney API token from LunchMoney Developer Settings.

Common MCP Client Configuration Locations

Different MCP clients store their configuration in different locations:

Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Other MCP Clients: Check your client's documentation for the configuration file location.

Setup Steps

Locate your MCP client's configuration file (create it if it doesn't exist).
Add the LunchMoney server configuration to the mcpServers section.
Save the file and restart your MCP client.
The LunchMoney tools should now be available in your client.

Requirements

Node.js 16+ installed on your system
npx available in your system PATH
Valid LunchMoney API token with appropriate permissions

Standalone Server

# Run with npx
LUNCHMONEY_API_TOKEN="your-api-token" npx @akutishevsky/lunchmoney-mcp

Example Prompts

Here are some example prompts you can use with the LunchMoney MCP server:

Account Overview

"Show me my LunchMoney account details"
"What's my current account status?"

Category Management

"List all my spending categories"
"Create a new category called 'Subscriptions' with a monthly budget of $100"
"Show me details for my 'Food & Dining' category"
"Create a category group for all my entertainment expenses"
"Delete the 'Unused Category' and reassign its transactions to 'Miscellaneous'"

Transaction Management

"Show me all transactions from last month"
"Find all transactions over $100 in the past week"
"Create a new expense for $45.99 at Amazon in the Shopping category"
"Update transaction #12345 to change the amount to $50"
"Show me all pending transactions"
"Group these coffee shop transactions together"

Budgeting

"Show me my budget summary for this month"
"Set a budget of $500 for Groceries this month"
"Remove the budget for Entertainment category"
"How much have I spent vs budgeted in each category?"

Manual Account Tracking

"List all my manual accounts"
"Create a new manual account for my savings account with a balance of $10,000"
"Update my investment account balance to $25,000"
"Close my old credit card account"

Recurring Expenses

"Show me all my recurring expenses"
"What subscriptions do I have?"
"List recurring items for the next 3 months"

Banking Integration

"Show me all my connected Plaid accounts"
"Refresh my bank account data"
"Trigger a sync for my checking account"

Cryptocurrency

"Show me all my crypto holdings"
"Update my Bitcoin balance to 0.5 BTC"
"List all my manually tracked crypto assets"

Analysis & Insights

"What are my top spending categories this month?"
"Show me all transactions tagged as 'vacation'"
"Find all transactions at coffee shops"
"List all transactions that need to be categorized"

Available Tools

Category Tools

get_all_categories - List all categories (supports format and is_group filters)
get_single_category - Get details for a specific category or category group
create_category - Create a category or category group (set is_group=true plus children)
update_category - Update properties; replaces the children list on category groups
delete_category - Delete a category; pass force=true to override dependency check

Tag Tools

get_all_tags - List all tags
get_single_tag - Get a tag by ID
create_tag - Create a new tag
update_tag - Update tag properties
delete_tag - Delete a tag (with force to override dependents)

Transaction Tools

get_transactions - List transactions with extensive filtering options (date range, account, category, tag, status, pending, metadata, files, etc)
get_single_transaction - Get full transaction details (always includes plaid_metadata, custom_metadata, files, and children for split/group parents)
create_transactions - Insert 1–500 transactions in one call
update_transaction - Partial update of one transaction
delete_transaction - Delete one transaction (cannot be split/group)
update_transactions_bulk - Bulk update 1–500 transactions
delete_transactions_bulk - Bulk delete 1–500 transactions by ID
create_transaction_group - Create a transaction group from existing transactions
delete_transaction_group - Ungroup a transaction group
split_transaction - Split a transaction into 2–500 children
unsplit_transaction - Undo a previous split
attach_file_to_transaction - Upload a local file (jpeg/png/heic/heif/pdf, ≤10MB)
get_transaction_attachment_url - Get a signed download URL for a file attachment
delete_transaction_attachment - Delete a file attachment

Recurring Items Tools

get_recurring_items - List recurring items for a date range (include_suggested for system suggestions)
get_single_recurring_item - Get a recurring item by ID

Budget Tools

get_budget_summary - Per-category budget summary (backed by /summary); supports occurrences, totals, rollover-pool toggles
get_budget_settings - Account-wide budget period and display settings
upsert_budget - Create or update a budget for a category and period
remove_budget - Remove a budget for a category and period

Manual Account Tools

get_all_manual_accounts - List all manually-managed accounts (formerly "assets")
get_single_manual_account - Get a manual account by ID
create_manual_account - Create a new manually-managed account
update_manual_account - Update properties of a manual account
delete_manual_account - Delete a manual account; optionally also delete its transactions / balance history

Plaid Account Tools

get_all_plaid_accounts - List all connected Plaid accounts
get_single_plaid_account - Get a Plaid account by ID
trigger_plaid_fetch - Trigger fetch of latest data from Plaid (optionally scoped to a date range or account)

Crypto Tools

get_all_crypto - List synced and manual cryptocurrency holdings from /v1/crypto
update_manual_crypto - Update a manually-managed cryptocurrency asset via /v1/crypto/manual/:id

Development

Project Structure

lunchmoney-mcp/
├── src/
│   ├── index.ts           # Server entry point
│   ├── config.ts          # Configuration management
│   ├── types.ts           # TypeScript type definitions
│   └── tools/             # Tool implementations
│       ├── user.ts
│       ├── categories.ts
│       ├── tags.ts
│       ├── transactions.ts
│       ├── recurring-items.ts
│       ├── budgets.ts
│       ├── manual-accounts.ts
│       ├── plaid-accounts.ts
│       └── crypto.ts
├── build/                 # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

Building

# Build the MCP server
npm run build

# Build MCPB package for distribution
npm run build:mcpb

Adding New Tools

Create a new file in src/tools/
Implement tool handlers using the MCP SDK
Register tools in src/index.ts
Add types to src/types.ts if needed

API Reference

The server implements the full LunchMoney API v2. For detailed API documentation, see:

Contributing

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

License

MIT License