akutishevsky/lunchmoney-mcp

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 — v3.0.0 removes get_all_crypto.** The crypto tools now use LunchMoney's v2 crypto endpoints, which split manual and synced holdings into separate resources and offer no combined equivalent of v1's GET /crypto. Replace get_all_crypto with get_all_manual_crypto and get_all_synced_crypto, which together return everything it did and more. update_manual_crypto also drops its currency parameter. Nothing outside the crypto domain changed; if you don't use the crypto tools, upgrading from 2.x needs no action. See CHANGELOG.md. If you depend on get_all_crypto, pin @akutishevsky/lunchmoney-mcp@^2.2.0.
> **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.
Table of Contents
- Overview
- Features
- Usage
- Installation Options
- MCP Bundle
- Claude Code CLI
- Codex CLI
- Manual MCP Configuration
- Standalone Server
- Remote Deployments
- Example Prompts
- Available Tools
- Development
- API Reference
- Contributing
- License
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** - Full CRUD for manual crypto balances, read and refresh synced crypto accounts, and manage the supported-cryptocurrency list
- **Balance History** - Read, upsert, and delete monthly balance history for manual, Plaid, crypto, and deleted accounts
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:
1. Download the latest .mcpb file from the releases page
2. Open Claude Desktop and go to Extensions
3. Click "Install Extension" and select the downloaded .mcpb file
4. Enter your LunchMoney API token when prompted (get it from LunchMoney Developer Settings)
5. The LunchMoney tools will be immediately available
Claude Code CLI
Add the LunchMoney MCP server to Claude Code:
To enable debug logging:
Verify the server was added:
Codex CLI
Add the LunchMoney MCP server to Codex:
To enable debug logging:
Verify the server was added:
Manual MCP Configuration
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: