https://github.com/akutishevsky/lunchmoney-mcp
A Model Context Protocol (MCP) server implementation for LunchMoney, providing programmatic access to personal finance management through LunchMoney's API.
https://github.com/akutishevsky/lunchmoney-mcp
lunchmoney lunchmoney-api mcp mcp-server model-context-protocol
Last synced: 2 months ago
JSON representation
A Model Context Protocol (MCP) server implementation for LunchMoney, providing programmatic access to personal finance management through LunchMoney's API.
- Host: GitHub
- URL: https://github.com/akutishevsky/lunchmoney-mcp
- Owner: akutishevsky
- License: mit
- Created: 2025-07-27T04:25:40.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-07-30T07:19:17.000Z (3 months ago)
- Last Synced: 2025-08-30T23:17:38.712Z (2 months ago)
- Topics: lunchmoney, lunchmoney-api, mcp, mcp-server, model-context-protocol
- Language: TypeScript
- Homepage:
- Size: 51.8 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-lunchmoney - lunchmoney-mcp - A Model Context Protocol server that covers 100% of the Lunch Money API functionality - (by akutishevsky). (AI Powered Virtual Financial Coach)
- awesome-mcp-servers - **LunchMoney** - MCP server for LunchMoney personal finance and budgeting tool. `http` `git` `github` (📦 Other)
- awesome-mcp-servers - LunchMoney - MCP server for LunchMoney personal finance and budgeting tool. (Community Servers)
README
# 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.
## 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
### With MCP Clients
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
npm run build
```
### 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