LunchMoney MCP Server

# LunchMoney MCP Server A Model Context Protocol (MCP) server implementation for [LunchMoney](https://lunchmoney.app/), providing programmatic access to personal finance management through LunchMoney's API. Also available as a Desktop Extension Tool (DXT) for easy installation in Claude Desktop. ## 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** - 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 - **Plaid Accounts** - Manage connected bank accounts - **Cryptocurrency** - Track crypto holdings ### Key Capabilities - Full integration with LunchMoney API v1 - Type-safe implementation with TypeScript and Zod validation - Modular architecture for easy extension - Standard MCP server implementation using stdio transport ## Usage ### Installation Options #### Option 1: Desktop Extension Tool (DXT) - Recommended The easiest way to install this server is as a Desktop Extension Tool in Claude Desktop: 1. Download the latest `.dxt` file from the [releases page](https://github.com/akutishevsky/lunchmoney-mcp/releases) 2. Open Claude Desktop and go to Extensions 3. Click "Install Extension" and select the downloaded `.dxt` file 4. Enter your LunchMoney API token when prompted (get it from [LunchMoney Developer Settings](https://my.lunchmoney.app/developers)) 5. The LunchMoney tools will be immediately available #### Option 2: 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: ```json { "mcpServers": { "lunchmoney": { "command": "npx", "args": ["@akutishevsky/lunchmoney-mcp"], "env": { "LUNCHMONEY_API_TOKEN": "your-api-token-here" } } } } ``` Replace `"your-api-token-here"` with your actual LunchMoney API token from [LunchMoney Developer Settings](https://my.lunchmoney.app/developers). #### 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 1. Locate your MCP client's configuration file (create it if it doesn't exist). 2. Add the LunchMoney server configuration to the `mcpServers` section. 3. Save the file and restart your MCP client. 4. 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 ### As a standalone MCP server ```bash # 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?" ### Asset Tracking - "List all my assets" - "Create a new asset for my savings account with a balance of $10,000" - "Update my investment account balance to $25,000" ### 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 ### User Tools - `get_user` - Retrieve current user details ### Category Tools - `get_all_categories` - List all spending categories - `get_single_category` - Get details for a specific category - `create_category` - Create a new category - `create_category_group` - Create a category group - `update_category` - Update category properties - `add_to_category_group` - Add categories to a group - `delete_category` - Delete a category - `force_delete_category` - Force delete with data cleanup ### Tag Tools - `get_all_tags` - List all available tags ### Transaction Tools - `get_transactions` - List transactions with extensive filtering options - `get_single_transaction` - Get detailed transaction information - `create_transactions` - Create new transactions - `update_transaction` - Update existing transaction - `unsplit_transactions` - Remove transactions from split groups - `get_transaction_group` - Get transaction group details - `create_transaction_group` - Create a transaction group - `delete_transaction_group` - Delete a transaction group ### Recurring Items Tools - `get_recurring_items` - List recurring items for a date range ### Budget Tools - `get_budget_summary` - Get budget summary by date range - `upsert_budget` - Create or update budget amounts - `remove_budget` - Remove budget for a category ### Asset Tools - `get_all_assets` - List all manually-managed assets - `create_asset` - Create a new asset - `update_asset` - Update asset properties ### Plaid Account Tools - `get_all_plaid_accounts` - List all connected Plaid accounts - `trigger_plaid_fetch` - Trigger fetch of latest data from Plaid ### Crypto Tools - `get_all_crypto` - List all cryptocurrency assets - `update_manual_crypto` - Update balance for manually-managed crypto ## 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 │ ├── assets.ts │ ├── plaid-accounts.ts │ └── crypto.ts ├── build/ # Compiled JavaScript output ├── package.json ├── tsconfig.json └── README.md ``` ### Building ```bash # Build the MCP server npm run build # Build DXT package for distribution npm run build:dxt ``` ### Adding New Tools 1. Create a new file in `src/tools/` 2. Implement tool handlers using the MCP SDK 3. Register tools in `src/index.ts` 4. Add types to `src/types.ts` if needed ## API Reference The server implements the full LunchMoney API v1. For detailed API documentation, see: - [LunchMoney API Documentation](https://lunchmoney.dev/) - [Model Context Protocol Specification](https://modelcontextprotocol.io/) ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## License MIT License