Best for
- Individuals using LunchMoney to manage finances and wanting to automate queries and operations via AI assistants
- Developers integrating financial data with AI workflows
- Users who want quick setup and use of an MCP server
L
LunchMoney MCP Server
Community
Manage LunchMoney personal finance: transactions, budgets, categories, and more via MCP.
GitHub source repository ↗
41FMRS · D
This server offers extensive LunchMoney API coverage but requires technical knowledge to set up. It suits personal finance automation, but users should be mindful of token security and operational risks.
This is a Model Context Protocol (MCP) server implementation for LunchMoney, offering programmatic access to personal finance management covering transactions, budgets, categories, tags, recurring items, manual accounts, Plaid accounts, cryptocurrency, and balance history. It targets the LunchMoney v2 API (alpha) and uses TOON encoding to reduce token usage. It supports stdio transport and can be installed as an npm package or MCP Bundle.
Tools
get_user
Retrieve current user details.
get_all_categories
List all categories with optional filters.
get_single_category
Get details for a specific category or group.
create_category
Create a category or category group.
update_category
Update category properties; replaces children list for groups.
delete_category
Delete a category, optionally force override dependency check.
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 option.
get_transactions
List transactions with extensive filtering.
get_single_transaction
Get full transaction details including splits/groups children.
create_transactions
Insert 1–500 transactions in one call.
update_transaction
Partially update a single transaction.
delete_transaction
Delete one transaction (not split/group).
update_transactions_bulk
Bulk update 1–500 transactions.
delete_transactions_bulk
Bulk delete transactions by ID.
create_transaction_group
Create a 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), verifying type.
get_transaction_attachment_url
Get signed download URL for an attachment.
delete_transaction_attachment
Delete a file attachment.
get_recurring_items
List recurring items for a date range, optionally include suggested.
get_single_recurring_item
Get a recurring item by ID.
get_budget_summary
Per-category budget summary with various options.
get_budget_settings
Get account-wide budget period and display settings.
upsert_budget
Create or update a budget for a category and period.
remove_budget
Remove a budget.
get_all_manual_accounts
List all manually-managed accounts.
get_single_manual_account
Get a manual account by ID.
create_manual_account
Create a new manual account.
update_manual_account
Update properties of a manual account.
delete_manual_account
Delete a manual account, optionally delete its transactions/history.
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.
get_supported_cryptocurrencies
List cryptocurrencies supported for manual tracking.
add_supported_cryptocurrency
Add a cryptocurrency to the supported list from a CoinGecko URL.
get_all_manual_crypto
List all manually-managed crypto balances.
get_single_manual_crypto
Get a single manual crypto balance by ID.
create_manual_crypto
Create a manually-managed crypto asset.
update_manual_crypto
Update a manual crypto balance's details.
delete_manual_crypto
Delete a manual crypto asset (irreversible).
get_all_synced_crypto
List synced crypto accounts and their nested balances.
get_single_synced_crypto
Get a single synced crypto account by ID.
get_synced_crypto_balance
Get one balance inside a synced crypto account by symbol.
refresh_synced_crypto
Trigger a balance refresh for a synced crypto account.
get_balance_history
Get monthly balance history across all accounts.
get_account_balance_history
Get monthly balance history for one account.
upsert_account_balance_history
Create or update monthly balance entries for an account.
delete_account_balance_history
Delete all historical balance entries for an account.
get_crypto_synced_balance_history
Get monthly balance history for a synced crypto holding.
upsert_crypto_synced_balance_history
Create or update monthly balance entries for a synced crypto holding.
delete_crypto_synced_balance_history
Delete all historical balance entries for a synced crypto holding.
delete_balance_history_entry
Delete a single historical balance entry by id.
update_deleted_account_details
Update display details for a deleted account's balance history.
Setup
- Obtain your LunchMoney API token from https://my.lunchmoney.app/settings/developer.
- Configure the server in your MCP client. You can use the MCP Bundle (.mcpb) for one-click installation in Claude Desktop, or add it via CLI:
- Claude Code CLI: claude mcp add lunchmoney --transport stdio -e LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcp
- Codex CLI: codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcp
- Manual: Edit your client's configuration file, add mcpServers as shown in install_config above.
- Restart your MCP client.
- Verify the tools are available.
claude_desktop_config.json
{
"mcpServers": {
"lunchmoney": {
"command": "npx",
"args": [
"@akutishevsky/lunchmoney-mcp"
],
"env": {
"LUNCHMONEY_API_TOKEN": "your-api-token-here",
"LUNCHMONEY_DEBUG": "true"
}
}
}
}
Fit and risk
Not for
- Users without a LunchMoney account or API token
- Scenarios requiring multi-user or centralized server-side management (current config is single-user)
- Users needing HTTP transport without self-deployment (can use Cloudflare Worker or self-hosted option)
Required permissions
- Requires LunchMoney API token; permissions depend on token scope, may include read/write access to transactions, accounts, budgets, etc.
- Can access the filesystem (only for attach_file_to_transaction, restricted to JPEG/PNG/HEIC/HEIF/PDF types)
- Can make network requests to LunchMoney API
Risks and side effects
- API token compromise could lead to unauthorized access and modification of financial data
- Tools can delete transactions, accounts, balance history; accidental use may cause data loss
- When deployed over HTTP remotely without LUNCHMONEY_ATTACHMENTS_DIR set, there is a risk of arbitrary file reads
- Uses v2 API (alpha), subject to changes
Troubleshooting
- Ensure LUNCHMONEY_API_TOKEN is set correctly and valid
- Check Node.js version is >=16
- If debug enabled, check stderr for logs
- Verify MCP client configuration format and mcpServers section
- For file attachments, ensure file extension and type are correct, size ≤10MB
Use cases
Get account overview and details
Manage categories and tags, create category groups
Query, create, update, delete transactions with bulk and split operations
Set and track budgets, view budget summaries
Manage manual accounts and balance history
View and sync Plaid bank accounts
Manage cryptocurrency holdings and synced accounts
Analyze spending patterns, find uncategorized transactions
Supported clients
Claude DesktopFull support
Claude CodeFull support
Codex CLIFull support