lunchmoney-mcp-v2
Interact with the Lunch Money API v2 through 14 MCP tools for reviewing, organizing, and managing personal finances.
Read user info, transactions, categories, tags, accounts, budget summaries, and recurring items.
Create, update, and delete transactions, categories, tags, and manual accounts.
Bulk-update up to 500 transactions at once.
Split/unsplit transactions and group/ungroup transactions.
Filter transactions by dates, category/tag/account, status, and pagination.
Get hydrated responses with category, tag, and account names instead of raw IDs.
Use cached categories, tags, and accounts with auto-refresh after mutations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lunchmoney-mcp-v2 Show me this month's spending by category"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
lunchmoney-mcp-v2
MCP server for the Lunch Money API v2. First MCP server built on the v2 API.
Features
14 tools covering read, CRUD, and advanced operations
Hydrated responses: category, tag, and account names instead of raw IDs
Smart caching: categories, tags, and accounts cached at startup, auto-refreshed after mutations
Type-safe: generated from the official OpenAPI spec via
openapi-typescript
Related MCP server: LunchMoney MCP Server
Setup
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"lunchmoney": {
"command": "npx",
"args": ["-y", "lunchmoney-mcp-v2"],
"env": {
"LUNCHMONEY_TOKEN": "your-api-token-here"
}
}
}
}Claude Code
claude mcp add lunchmoney -e LUNCHMONEY_TOKEN=your-api-token-here -- npx -y lunchmoney-mcp-v2Add --scope user to make it available in all projects. --scope project writes the config, including the token, to .mcp.json in the project; don't commit that file with a real token.
Get your API token from Lunch Money Developer settings.
Tools
Read
Tool | Description |
| Account info (name, email, currency) |
| List/search transactions with filters, or look up by ID |
| All categories (nested or flat view) |
| All tags |
| Manual + synced accounts with balances |
| Budget summary with income/spending/per-category breakdown |
| Recurring items (subscriptions, bills, income) |
CRUD
Tool | Actions | Description |
| create, update, delete | Single transaction operations |
| create, update, delete | Category management (force delete with dependency info) |
| create, update, delete | Tag management (force delete with dependency info) |
| create, update, delete | Manual account management (Plaid accounts are read-only) |
Advanced
Tool | Actions | Description |
| — | Batch update up to 500 transactions at once |
| split, unsplit | Split a transaction into parts or restore the original |
| group, ungroup | Combine transactions into a group or restore originals |
Example prompts
Once connected, just ask your LLM naturally:
Reviewing & organizing
"Show me all unreviewed transactions from this month"
"Categorize all my Amazon transactions as Shopping"
"What did I spend on groceries last week?"
"Mark these 5 transactions as reviewed"
Budget overview
"Give me a spending summary for January"
"What are my recurring expenses?"
"How much do I have in each account?"
Managing transactions
"Add a $45 transaction for dinner at Nobu yesterday"
"Split that $120 Costco transaction into $80 groceries and $40 household"
"Group these three Uber transactions into one"
"Delete the duplicate transaction I just created"
Organizing
"Create a new category called Side Projects"
"Tag these transactions with travel"
"Show me all my categories with their IDs"
"Rename the Dining Out category to Restaurants"
Development
npm install
npm run build
npm startRegenerate types from the OpenAPI spec:
npm run generate:typesArchitecture
src/
index.ts Entry point — registers tools, initializes cache
client.ts openapi-fetch client + error handling
cache.ts In-memory cache for categories, tags, accounts
format.ts Text formatters for all response types
dates.ts Date helpers for default date ranges
types.ts Generated from @lunch-money/v2-api-spec
tools/
user.ts get_user
transactions.ts list_transactions, manage_transaction, bulk_update, split, group
categories.ts list_categories, manage_category
tags.ts list_tags, manage_tag
accounts.ts get_accounts, manage_account
summary.ts get_summary
recurring.ts get_recurringLicense
MIT
Available Tools
14 toolsbulk_update_transactionsA
Update multiple transactions at once (max 500). Each item needs an id plus the fields to change.
Common uses: batch-categorize transactions, bulk mark as reviewed, assign tags to multiple transactions. Fields per transaction: category_id, payee, notes, tag_ids, status, date, amount, currency.
Inputs: transactions (required).
get_accountsA
Get all Lunch Money accounts — both manual accounts and synced (Plaid) accounts. Shows balances, types, and status.
Inputs: no named parameters.
get_recurringA
Get recurring items (subscriptions, bills, income). Shows expected amounts, frequency, and match status for the given period. Without dates, uses the current month.
Inputs: end_date, start_date.
get_summaryA
Get a budget summary for a date range. Shows income, spending, and per-category breakdown with budget vs actual. If the date range aligns with budget periods, budget amounts and availability are included.
Tip: Use the first and last day of a month for a monthly overview (e.g. 2026-02-01 to 2026-02-28).
Inputs: end_date (required), start_date (required), include_totals.
get_userA
Get the current Lunch Money user's account info: name, email, budget name, and primary currency.
Inputs: no named parameters.
group_transactionsA
Group or ungroup Lunch Money transactions.
action="group": Combine multiple transactions into one grouped transaction. Provide ids (array of transaction IDs), date (YYYY-MM-DD), and payee (required). Optionally set category_id, notes, tag_ids. The grouped transaction amount equals the sum of the original amounts. action="ungroup": Provide id of the group parent to restore original transactions.
Inputs: action (required), id, ids, date, +4 more.
list_categoriesA
List all Lunch Money categories. Use format="nested" to see category groups with their children, or format="flat" (default) for a flat list.
Inputs: format.
list_tagsA
List all Lunch Money tags. Tags can be assigned to transactions for additional organization beyond categories.
Inputs: no named parameters.
list_transactionsA
List or look up Lunch Money transactions. Without an id, returns filtered transactions (defaults to last 30 days if no dates given). With an id, returns that single transaction.
Filters: start_date/end_date (YYYY-MM-DD), category_id, tag_id, status (reviewed/unreviewed), account_id. Use limit/offset for pagination.
Returns hydrated output with category names, tag names, and account names instead of raw IDs.
Inputs: id, limit, offset, status, +6 more.
manage_accountA
Create, update, or delete a manual Lunch Money account. Synced (Plaid) accounts are read-only.
action="create": Provide name, type (cash/credit/cryptocurrency/employee compensation/investment/loan/other liability/other asset/real estate/vehicle), and balance (required). Optionally set institution_name, currency, subtype. action="update": Provide id and any fields to change (name, balance, institution_name, display_name, status, subtype). action="delete": Provide id. WARNING: this permanently deletes the account. Transactions are NOT deleted by default.
Inputs: action (required), id, name, type, +6 more.
manage_categoryA
Create, update, or delete a Lunch Money category.
action="create": Provide name (required). Optionally set description, is_income, exclude_from_budget, exclude_from_totals, is_group, group_id. action="update": Provide id and any fields to change (name, description, is_income, exclude_from_budget, exclude_from_totals, archived, group_id). action="delete": Provide id. Use force=true to delete even if the category has dependent transactions/rules.
Inputs: action (required), id, name, force, +7 more.
manage_tagA
Create, update, or delete a Lunch Money tag.
action="create": Provide name (required). Optionally set description. action="update": Provide id and any fields to change (name, description, archived). action="delete": Provide id. Use force=true to delete even if the tag is used on transactions.
Inputs: action (required), id, name, force, +2 more.
manage_transactionA
Create, update, or delete a single Lunch Money transaction.
action="create": Provide date (YYYY-MM-DD), amount (positive=debit, negative=credit), and optionally payee, category_id, notes, account_id, tag_ids, currency. action="update": Provide id and any fields to change (payee, amount, date, category_id, notes, tag_ids, status). action="delete": Provide only the id of the transaction to delete.
Inputs: action (required), id, date, notes, +7 more.
split_transactionA
Split or unsplit a Lunch Money transaction.
action="split": Provide id of the transaction to split, plus a splits array. Each split has amount (required) and optionally payee, date, category_id, notes. The split amounts MUST add up to the parent transaction amount. action="unsplit": Provide id of the split parent to restore it to normal.
Inputs: id (required), action (required), splits.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct resource or operation. Read (list/get), write (manage), batch (bulk_update), and structural operations (split/group) are clearly separated, minimizing the chance of misselection.
The naming follows a verb_noun convention with intuitive prefixes like get_/list_, manage_, bulk_update_, split_, and group_. The only minor inconsistency is mixing get_ and list_ for read operations (e.g., get_accounts vs list_transactions), but the pattern is still predictable.
With 14 tools, the server covers user info, transactions, categories, tags, accounts, recurring items, and budget summaries—each earning its place. This is within the ideal 3-15 range and feels well-scoped.
The tool set provides solid coverage for core CRUD on transactions, categories, tags, and accounts, plus advanced transaction operations (split/group/bulk update). Minor gaps exist, such as recurring items being read-only and no bulk delete, but agents can work around these.
Maintenance
Related MCP Connectors
Read-only Lunch Money accounts, transactions, categories and budgets. Unofficial connector.
Log, query, and edit expenses, budgets, and accounts in Manilo (formerly Ledgy) from any MCP-compatible AI assistant.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
Log, query, and edit expenses, budgets, and accounts in Ledgy from any MCP-compatible AI assistant.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to interact with your Lunch Money personal finance data, providing tools for managing transactions, categories, budgets, assets, and accounts.15ISC
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants and other MCP clients to manage personal finances through the LunchMoney API, covering transactions, budgets, categories, tags, recurring items, accounts, crypto, and balance history.41 npm-
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants and MCP clients to manage personal finance data through LunchMoney's API, including transactions, budgets, categories, tags, accounts, and balances.41 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants and MCP clients to manage personal finance data through the LunchMoney API, including transactions, budgets, categories, tags, accounts, recurring items, and crypto balances.41 npmMIT