LunchMoney MCP Server
LunchMoney MCP Server lets AI/MCP clients read and manage LunchMoney personal-finance data through LunchMoney API v2 tools.
Retrieve user details and browse categories, tags, manual accounts, Plaid accounts, and recurring items.
Perform CRUD on categories and tags, including category groups, child reassignment, and forced deletion with dependency handling.
Query, create, update, and delete transactions; run bulk updates/deletes; split/unsplit, group/ungroup, and manage file attachments.
View recurring expenses and system-suggested recurring items for date ranges.
Get budget summaries/settings and upsert or remove budgets by category and period.
Manage manual accounts and trigger Plaid account data fetches.
Manage supported cryptocurrencies, manual crypto balances, and synced crypto accounts/balances.
Read, upsert, and delete monthly balance history across manual, Plaid, manual crypto, synced crypto, and deleted accounts.
Allows tracking of Bitcoin and other cryptocurrency holdings, including viewing balances and updating manually tracked crypto assets.
Required runtime environment for the LunchMoney MCP server, with Node.js 16+ needed for operation.
Used for type-safe implementation of the LunchMoney MCP server.
Employed for data validation within the LunchMoney MCP server implementation.
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 Server show me my budget summary for this month"
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 Server
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 — v4.0.1 validates inputs against the LunchMoney v2 spec. Tool names and parameters are unchanged, and six settings tools are added. Inputs the API would reject are now refused before any request is sent: unknown currency codes,
nullor empty amounts, unpaired date ranges, updates with no fields, and conflicting fields such asmanual_account_idwithplaid_account_id.delete_taganddelete_categorynow report a 422 as an error, and a split child withcategory_id: nullis sent as uncategorized instead of0. See CHANGELOG.md for the full list. If you depend on the old behaviour, pin@akutishevsky/lunchmoney-mcp@^3.0.0.
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'sGET /crypto. Replaceget_all_cryptowithget_all_manual_cryptoandget_all_synced_crypto, which together return everything it did and more.update_manual_cryptoalso drops itscurrencyparameter. 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 onget_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,assetsis nowmanual_accounts,tagsarrays are nowtag_ids, transactionasset_idis nowmanual_account_id, thedebit_as_negativetoggle is gone, and the budget summary moved to a new/summaryendpoint). See CHANGELOG.md for the full list. If you depend on v1.x, pin@akutishevsky/lunchmoney-mcp@^1.4.3.
Table of Contents
Related MCP server: Lunch Money MCP Server
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:
Download the latest
.mcpbfile from the releases pageOpen Claude Desktop and go to Extensions
Click "Install Extension" and select the downloaded
.mcpbfileEnter your LunchMoney API token when prompted (get it from LunchMoney Developer Settings)
The LunchMoney tools will be immediately available
Add the LunchMoney MCP server to Claude Code:
claude mcp add lunchmoney --transport stdio -e LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcpTo enable debug logging:
claude mcp add lunchmoney --transport stdio -e LUNCHMONEY_API_TOKEN=your-api-token-here -e LUNCHMONEY_DEBUG=true -- npx -y @akutishevsky/lunchmoney-mcpVerify the server was added:
claude mcp list
claude mcp get lunchmoneyAdd the LunchMoney MCP server to Codex:
codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcpTo enable debug logging:
codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here --env LUNCHMONEY_DEBUG=true -- npx -y @akutishevsky/lunchmoney-mcpVerify the server was added:
codex mcp list
codex mcp get lunchmoneyTo 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:
{
"mcpServers": {
"lunchmoney": {
"command": "npx",
"args": ["@akutishevsky/lunchmoney-mcp"],
"env": {
"LUNCHMONEY_API_TOKEN": "your-api-token-here",
"LUNCHMONEY_DEBUG": "true"
}
}
}
}Note:
LUNCHMONEY_DEBUGis optional. Set it to"true"to enable debug logging of API requests and responses to stderr. Useful for troubleshooting.
Note:
LUNCHMONEY_ATTACHMENTS_DIRis optional.attach_file_to_transactionis the only tool that reads from your filesystem, and it always verifies that a file really is a JPEG, PNG, HEIC, HEIF, or PDF before uploading it. Set this variable to a directory (say, a~/Receiptsfolder) to additionally restrict it to files inside that directory —..and symlinks that point outside are rejected. Leave it unset and any path the server can read is fair game, which is usually fine for a local stdio server but not for remote deployments.
Replace "your-api-token-here" with your actual LunchMoney API token from LunchMoney Developer Settings.
Common MCP Client Configuration Locations
Different MCP clients store their configuration in different locations:
Claude Desktop:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
Other MCP Clients: Check your client's documentation for the configuration file location.
Setup Steps
Locate your MCP client's configuration file (create it if it doesn't exist).
Add the LunchMoney server configuration to the
mcpServerssection.Save the file and restart your MCP client.
The LunchMoney tools should now be available in your client.
Requirements
Node.js 16+ installed on your system
npxavailable in your system PATHValid LunchMoney API token with appropriate permissions
Standalone Server
# Run with npx
LUNCHMONEY_API_TOKEN="your-api-token" npx @akutishevsky/lunchmoney-mcpRemote Deployments
The bundled stdio binary covers desktop MCP clients, but Claude on mobile and the custom connectors feature in claude.ai only speak HTTP. There are two ways to expose this server remotely.
Turnkey: Cloudflare Workers
lunchmoney-mcp-cloudflare wraps this package as a Cloudflare Worker with Google sign-in and an email allowlist in front of the MCP endpoint. The whole stack fits inside Cloudflare's and Google Cloud's free tiers, and a setup.sh wizard handles KV creation, OAuth client setup, secrets, and deploy in one walkthrough. Each authenticated user runs in their own Durable Object, so the config singleton stays per-user.
Self-hosted: HTTP transport on your own host
For a single-user deployment, wire createServer() into StreamableHTTPServerTransport and serve it from any Node HTTP framework. Example with Express:
import express from "express";
import { createServer } from "@akutishevsky/lunchmoney-mcp/server";
import { initializeConfig } from "@akutishevsky/lunchmoney-mcp/config";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
initializeConfig(process.env.LUNCHMONEY_API_TOKEN!);
const server = createServer("1.0.0");
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: () => crypto.randomUUID(),
});
await server.connect(transport);
const app = express();
app.use(express.json());
app.all("/mcp", (req, res) => transport.handleRequest(req, res, req.body));
app.listen(3000);Swap Express for Hono (via @hono/node-server) or Fastify if you prefer — the transport only needs Node's IncomingMessage and ServerResponse. Add your own auth in front of /mcp — the package ships no transport-level auth.
Set
LUNCHMONEY_ATTACHMENTS_DIRon any remote deployment.attach_file_to_transactionreads a path supplied by the caller off the host's filesystem. On a desktop stdio server the caller and the file owner are the same person, so that is unremarkable. Once the server is reachable over HTTP they are different principals, and an unconfined read is a way for a remote caller — or a prompt-injected model — to pull files off your host. Point the variable at a dedicated directory and keep nothing else in it. The content-type check (only real JPEG/PNG/HEIC/HEIF/PDF files upload) applies either way, but it is a backstop, not a substitute.
Multi-tenant warning. This pattern serves one user from one process with one shared API token. To serve multiple users from a single Node process you'd hit the single-tenant config singleton; fork the process per user or use the Cloudflare option above (each user gets their own isolate).
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?"
Manual Account Tracking
"List all my manual accounts"
"Create a new manual account for my savings account with a balance of $10,000"
"Update my investment account balance to $25,000"
"Close my old credit card account"
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"
"Add a cold wallet holding 0.85 BTC called Ledger Cold Storage"
"Refresh my Coinbase account and show the updated balances"
"Which cryptocurrencies can I track manually?"
Net Worth & Balance History
"Show me how my net worth changed over the last 12 months"
"What was my savings account balance in March 2026?"
"Set my car's value to $18,000 for June 2026"
"Clear the balance history for my old brokerage account"
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 detailsget_account_settings- Get account-wide settings (currencies, locale, display name, rule automation)update_account_settings- Update account-wide settings (at least one field required)get_user_settings- Get user-wide display and formatting preferencesupdate_user_settings- Update user-wide display and formatting preferences (at least one field required)get_user_account_settings- Get user-specific settings within the budget accountupdate_user_account_settings- Update user-specific account settings, such as the default manual account (at least one field required)
Category Tools
get_all_categories- List all categories (supportsformatandis_groupfilters)get_single_category- Get details for a specific category or category groupcreate_category- Create a category or category group (setis_group=truepluschildren)update_category- Update properties; replaces the children list on category groupsdelete_category- Delete a category; passforce=trueto override dependency check
Tag Tools
get_all_tags- List all tagsget_single_tag- Get a tag by IDcreate_tag- Create a new tagupdate_tag- Update tag propertiesdelete_tag- Delete a tag (withforceto override dependents)
Transaction Tools
get_transactions- List transactions with extensive filtering options (date range, account, category, tag, status, pending, metadata, files, etc)get_single_transaction- Get full transaction details (always includes plaid_metadata, custom_metadata, files, and children for split/group parents)create_transactions- Insert 1–500 transactions in one callupdate_transaction- Partial update of one transactiondelete_transaction- Delete one transaction (cannot be split/group)update_transactions_bulk- Bulk update 1–500 transactionsdelete_transactions_bulk- Bulk delete 1–500 transactions by IDcreate_transaction_group- Create a transaction group from existing transactionsdelete_transaction_group- Ungroup a transaction groupsplit_transaction- Split a transaction into 2–500 childrenunsplit_transaction- Undo a previous splitattach_file_to_transaction- Upload a local file (jpeg/png/heic/heif/pdf, ≤10MB), type verified from its contentsget_transaction_attachment_url- Get a signed download URL for a file attachmentdelete_transaction_attachment- Delete a file attachment
Recurring Items Tools
get_recurring_items- List recurring items for a date range (include_suggestedfor system suggestions)get_single_recurring_item- Get a recurring item by ID
Budget Tools
get_budget_summary- Per-category budget summary (backed by/summary); supports occurrences, totals, rollover-pool togglesget_budget_settings- Account-wide budget period and display settingsupsert_budget- Create or update a budget for a category and periodremove_budget- Remove a budget for a category and period
Manual Account Tools
get_all_manual_accounts- List all manually-managed accounts (formerly "assets")get_single_manual_account- Get a manual account by IDcreate_manual_account- Create a new manually-managed accountupdate_manual_account- Update properties of a manual accountdelete_manual_account- Delete a manual account; optionally also delete its transactions / balance history
Plaid Account Tools
get_all_plaid_accounts- List all connected Plaid accountsget_single_plaid_account- Get a Plaid account by IDtrigger_plaid_fetch- Trigger fetch of latest data from Plaid (optionally scoped to a date range or account)
Crypto Tools
get_supported_cryptocurrencies- List the cryptocurrencies supported for manual tracking (optionalsearchfilter)add_supported_cryptocurrency- Add a cryptocurrency to the supported list from its CoinGecko coin-page URLget_all_manual_crypto- List all manually-managed crypto balancesget_single_manual_crypto- Get a single manually-managed crypto balance by IDcreate_manual_crypto- Create a manually-managed crypto assetupdate_manual_crypto- Update a manual crypto balance's name, display name, institution name, or balancedelete_manual_crypto- Delete a manual crypto asset (irreversible)get_all_synced_crypto- List synced crypto accounts and their nested per-symbol balancesget_single_synced_crypto- Get a single synced crypto account by IDget_synced_crypto_balance- Get one balance inside a synced crypto account by symbolrefresh_synced_crypto- Trigger a balance refresh for a synced crypto account
Balance History Tools
get_balance_history- Get monthly balance history across all accounts (powers the Net Worth views); optionalstart_month/end_month(YYYY-MM) range filterget_account_balance_history- Get monthly balance history for one account (manual,plaid,crypto_manual, ordeleted)upsert_account_balance_history- Create or update monthly balance entries for one account (past months only; all-or-nothing)delete_account_balance_history- Delete all historical balance entries for one accountget_crypto_synced_balance_history- Get monthly balance history for a synced crypto holding by account id + ticker symbolupsert_crypto_synced_balance_history- Create or update monthly balance entries for a synced crypto holdingdelete_crypto_synced_balance_history- Delete all historical balance entries for a synced crypto holdingdelete_balance_history_entry- Delete a single historical balance entry by idupdate_deleted_account_details- Update the display details (name, institution, type, subtype, mask) shown for a deleted account's balance history
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
│ ├── manual-accounts.ts
│ ├── plaid-accounts.ts
│ ├── crypto.ts
│ └── balance-history.ts
├── build/ # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.mdBuilding
# Build the MCP server
npm run build
# Build MCPB package for distribution
npm run build:mcpbAdding New Tools
Create a new file in
src/tools/Implement tool handlers using the MCP SDK
Register tools in
src/index.tsAdd types to
src/types.tsif needed
Embedding as a library
The package exposes subpath entry points so it can be embedded in a custom transport (for example, a Cloudflare Worker that serves the MCP protocol over HTTP) rather than only the bundled stdio binary:
import { createServer } from "@akutishevsky/lunchmoney-mcp/server";
import { initializeConfig } from "@akutishevsky/lunchmoney-mcp/config";
initializeConfig(process.env.LUNCHMONEY_API_TOKEN!);
const server = createServer("1.0.0");
// connect `server` to whatever transport you needinitializeConfig must be called before any tool is invoked, or the first request throws "Configuration not initialized.".
Single-tenant assumption. The config is held in a module-level singleton. That is safe on per-isolate runtimes — each user gets their own isolate, so there is no shared mutable state to race on. It is not safe on shared-process multi-tenant Node hosts (e.g. one Express or Hono process serving multiple users): concurrent
initializeConfigcalls would race and leak tokens between requests. Those consumers need to fork per-user or refactor the singleton before exposing the package.
API Reference
The server implements the full LunchMoney API v2. For detailed API documentation, see:
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT License
Available Tools
59 toolsadd_supported_cryptocurrencyA
Add a new cryptocurrency to the supported manual-crypto list by submitting its CoinGecko coin-page URL. Only needed when get_supported_cryptocurrencies does not already list the symbol you want to track.
Inputs: coingecko_url (required).
attach_file_to_transactionA
Attach a local image or PDF receipt (max 10MB) to a transaction. Allowed types: image/jpeg, image/png, image/heic, image/heif, application/pdf. The file is read from the local filesystem of the host running this MCP server, and its type is determined from its actual contents — files that are not a real image or PDF are rejected. If LUNCHMONEY_ATTACHMENTS_DIR is set on the host, only files inside that directory can be attached.
Inputs: file_path (required), transaction_id (required), notes, content_type.
create_categoryA
Create a new category or a category group. Set is_group=true to create a category group; supply children as an array of existing category IDs and/or strings (names of new sub-categories to create).
Inputs: name (required), archived, children, group_id, +5 more.
create_manual_accountB
Create a new manually-managed account. (Formerly create_asset.)
Inputs: name (required), type (required), balance (required), subtype, +6 more.
create_manual_cryptoA
Create a manually-managed crypto asset. The symbol must match one returned by get_supported_cryptocurrencies.
Inputs: name (required), symbol (required), balance (required), display_name, +1 more.
create_tagA
Create a new tag.
Inputs: name (required), archived, text_color, description, +1 more.
create_transaction_groupA
Create a transaction group from 2-500 existing transactions. Source transactions are hidden from get_transactions and accessible via the new group's children (set include_children=true on get_single_transaction). Cannot include split or recurring transactions.
Inputs: ids (required), date (required), payee (required), notes, +3 more.
create_transactionsA
Insert one or more transactions (1-500 per call). Returns inserted transactions plus any skipped duplicates.
Inputs: transactions (required), apply_rules, skip_duplicates, skip_balance_update.
delete_account_balance_historyADestructive
Delete ALL historical balance entries for a single account. This is irreversible and affects the Net Worth views. To remove a single month, use delete_balance_history_entry instead.
Inputs: account_id (required), account_type (required).
delete_balance_history_entryADestructive
Delete a single historical balance entry by its id. The id must come from an entry with type=historical in a balance history response; ephemeral current entries have no id and cannot be deleted.
Inputs: entry_id (required).
delete_categoryADestructive
Delete a single category or category group. By default fails (HTTP 422) if dependencies exist, returning a structured dependents payload. Set force=true to delete and disassociate from all related budgets, transactions, recurring items, etc. Force delete is irreversible.
Inputs: category_id (required), force.
delete_crypto_synced_balance_historyADestructive
Delete ALL historical balance entries for a synced crypto holding. This is irreversible and affects the Net Worth views.
Inputs: symbol (required), account_id (required).
delete_manual_accountADestructive
Delete a manually-managed account. Optionally also delete its transactions/rules/recurring items, and/or its balance history. Both deletion options are irreversible.
Inputs: accountId (required), delete_items, delete_balance_history.
delete_manual_cryptoADestructive
Delete a manually-managed crypto asset. If the asset has balance history, keep_history must be set explicitly or the API rejects the request. Irreversible.
Inputs: crypto_id (required), keep_history.
delete_tagADestructive
Delete a tag. By default fails (HTTP 422) with a structured dependents payload if the tag is in use by transactions or rules. Set force=true to delete and disassociate from those records.
Inputs: tagId (required), force.
delete_transactionADestructive
Delete a single transaction. Fails for split/group transactions and their parents — unsplit/ungroup first. Irreversible.
Inputs: transaction_id (required).
delete_transaction_attachmentADestructive
Delete a transaction file attachment. Irreversible.
Inputs: file_id (required).
delete_transaction_groupADestructive
Delete (ungroup) a transaction group. The original child transactions remain and revert to normal ungrouped transactions.
Inputs: transaction_id (required).
delete_transactions_bulkADestructive
Bulk-delete transactions by ID (1-500). Fails if any ID is a split or group parent, or part of a split/group; unsplit or ungroup those first. Irreversible.
Inputs: ids (required).
get_account_balance_historyARead-only
Get monthly balance history for a single account. Call get_all_manual_accounts, get_all_plaid_accounts, or get_all_manual_crypto first to discover ids. For synced crypto holdings use get_crypto_synced_balance_history instead.
Inputs: account_id (required), account_type (required), end_month, start_month.
get_all_categoriesARead-only
Get a list of all categories associated with the user's account. Returns categories in alphabetical order.
Inputs: format, is_group.
get_all_manual_accountsARead-only
Get a list of all manually-managed accounts associated with the user. (Formerly known as assets in the v1 API.)
Inputs: no named parameters.
get_all_manual_cryptoARead-only
Get all manually-managed crypto balances associated with the user.
Inputs: no named parameters.
get_all_plaid_accountsARead-only
Get a list of all Plaid (synced) accounts associated with the user.
Inputs: no named parameters.
get_all_synced_cryptoARead-only
Get all synced crypto accounts (Coinbase, Kraken, Ethereum wallets) and their nested per-symbol balances. Synced accounts are connected in the Lunch Money web app and cannot be created or edited through the API.
Inputs: no named parameters.
get_all_tagsARead-only
Get a list of all tags associated with the user's account.
Inputs: no named parameters.
get_balance_historyARead-only
Get monthly account balance history across all accounts — the data behind the Net Worth views in the LunchMoney app. History is monthly. With no month range, returns all available history plus an ephemeral current entry for the current month, which is calculated on demand and may change between requests. Only months with data are included.
Inputs: end_month, start_month.
get_budget_settingsARead-only
Get budget period and display settings for the account (granularity, period length, anchor date, hide-no-activity preference, income option, rollover-left-to-budget setting).
Inputs: no named parameters.
get_budget_summaryARead-only
Get a summary of the user's budget for a specified date range. Returns per-category totals (other_activity, recurring_activity, budgeted, available, recurring_remaining, recurring_expected). Set include_occurrences=true for a per-period breakdown matching the account's budget periodicity. (Backed by the v2 GET /summary endpoint.)
Inputs: end_date (required), start_date (required), include_totals, include_occurrences, +3 more.
get_crypto_synced_balance_historyARead-only
Get monthly balance history for a synced crypto holding, identified by its account id and ticker symbol. Synced crypto is scoped per symbol, so it is not available through get_account_balance_history.
Inputs: symbol (required), account_id (required), end_month, start_month.
get_recurring_itemsARead-only
Retrieve a list of recurring items expected for a specified date range. The matches object on each item is populated based on the requested range.
Inputs: end_date, start_date, include_suggested.
get_single_categoryARead-only
Get details on a single category or category group, including the list of children categories for category groups.
Inputs: categoryId (required).
get_single_manual_accountARead-only
Get details of a single manual account by ID.
Inputs: accountId (required).
get_single_manual_cryptoARead-only
Get a single manually-managed crypto balance by ID. Call get_all_manual_crypto first to discover ids.
Inputs: crypto_id (required).
get_single_plaid_accountARead-only
Get details of a single Plaid (synced) account by ID.
Inputs: accountId (required).
get_single_recurring_itemARead-only
Retrieve a single recurring item by ID. Optional date range populates the matches object.
Inputs: recurringId (required), end_date, start_date.
get_single_synced_cryptoARead-only
Get a single synced crypto account and all its nested balances by ID.
Inputs: crypto_id (required).
get_single_tagARead-only
Get details of a single tag by ID.
Inputs: tagId (required).
get_single_transactionARead-only
Get details of a specific transaction. The response always includes plaid_metadata, custom_metadata, files, and (for split or group parents) the children array — none of which are returned by default in get_transactions.
Inputs: transaction_id (required).
get_supported_cryptocurrenciesARead-only
Get the list of cryptocurrencies supported for manual tracking. The symbol of an entry here is what must be passed to create_manual_crypto.
Inputs: no named parameters.
get_synced_crypto_balanceARead-only
Get a single balance held inside a synced crypto account, looked up by its cryptocurrency symbol.
Inputs: symbol (required), crypto_id (required).
get_transaction_attachment_urlARead-only
Get a short-lived signed download URL for a transaction file attachment. The response includes the URL and an expires_at timestamp.
Inputs: file_id (required).
get_transactionsARead-only
Retrieve transactions, optionally filtered by date range, account, category, tag, recurring item, status, and more. Returns at most limit transactions (default 1000, max 2000); has_more is set on the response when more match the filters. Pending and split-parent / group-child transactions are excluded by default.
Inputs: limit, offset, status, tag_id, +16 more.
get_userARead-only
Get details on the current user
Inputs: no named parameters.
refresh_synced_cryptoA
Trigger a balance refresh for a synced crypto account and return the refreshed account. Reaches out to the external crypto provider.
Inputs: crypto_id (required).
remove_budgetADestructive
Remove the budget for a specific category and period. The request is idempotent — succeeds even if no budget exists for the period.
Inputs: start_date (required), category_id (required).
split_transactionA
Split an existing transaction into 2-500 child transactions. The sum of child amounts must equal the parent's amount. After splitting, the parent is hidden from get_transactions and accessible via get_single_transaction (returns the parent with children).
Inputs: transaction_id (required), child_transactions (required).
trigger_plaid_fetchA
Trigger a fetch of latest data from Plaid. Optionally scope the fetch to a date range and/or a specific Plaid account ID. Note: Plaid enforces a minimum 60-second delay between fetch requests; fetching may take up to 5 minutes.
Inputs: id, end_date, start_date.
unsplit_transactionADestructive
Unsplit a previously split transaction by deleting its children and restoring the parent. Pass the parent (split_parent_id) — not a child — as the path id.
Inputs: transaction_id (required).
update_categoryAIdempotent
Update properties for an existing category or category group. For category groups, supplying children replaces the group's full child list. Cannot be used to convert between category and category group.
Inputs: categoryId (required), name, archived, children, +5 more.
update_deleted_account_detailsAIdempotent
Update the display details shown for a deleted account in the Net Worth views. Applies to all historical entries for that deleted source. At least one field must be provided; pass null to clear a field.
Inputs: account_id (required), mask, name, subtype, +3 more.
update_manual_accountBIdempotent
Update an existing manually-managed account. (Formerly update_asset.)
Inputs: accountId (required), name, type, balance, +7 more.
update_manual_cryptoAIdempotent
Update a manually-managed crypto balance. At least one of name, display_name, institution_name, or balance must be supplied. The symbol of an existing balance cannot be changed.
Inputs: crypto_id (required), name, balance, display_name, +1 more.
update_tagCIdempotent
Update properties for an existing tag.
Inputs: tagId (required), name, archived, text_color, +2 more.
update_transactionAIdempotent
Update an existing transaction. Provide any subset of writable fields directly (the v2 API no longer wraps the body in a transaction envelope). Cannot modify split or grouped transactions; use the corresponding split/group tools instead.
Inputs: update (required), transaction_id (required), update_balance.
update_transactions_bulkAIdempotent
Update multiple transactions in a single call (1-500). Each entry must include id plus at least one writable field. Cannot be used to modify split or grouped transactions.
Inputs: transactions (required).
upsert_account_balance_historyAIdempotent
Create or update monthly balance history entries for a single account. Every month must be a past calendar month — the current month is calculated on demand and cannot be written. The request is all-or-nothing: if any entry fails validation, none are applied. The response contains only the entries submitted, not the account's full history.
Inputs: balances (required), account_id (required), account_type (required).
upsert_budgetAIdempotent
Create or update a budget for a category and budget period. The start_date must be a valid budget period start for the account (see get_budget_settings).
Inputs: amount (required), start_date (required), category_id (required), notes, +1 more.
upsert_crypto_synced_balance_historyAIdempotent
Create or update monthly balance history entries for a synced crypto holding. Every month must be a past calendar month. If an entry sets symbol, it must match the symbol argument. The request is all-or-nothing.
Inputs: symbol (required), balances (required), account_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 59 tools
Tools are generally distinct by resource (categories, tags, transactions, accounts, crypto, budget). Some potential confusion exists among get_all_manual_crypto, get_all_synced_crypto, and get_all_plaid_accounts, and between get_single_recurring_item and recurring-related transaction filters, but descriptions clarify boundaries well.
Most tools follow a clear verb_noun pattern (get_all_*, create_*, update_*, delete_*), but there are inconsistencies: 'trigger_plaid_fetch' is verb-object-inverted, 'upsert_budget' uses a nonstandard verb, and 'split_transaction'/'unsplit' patterns are implied rather than explicit. Also, 'delete_transaction_attachment' exists while there is no get/create/update for attachments.
59 tools is a very large surface for an agent to navigate, even if each maps to a real API endpoint. The breadth is understandable because the Lunch Money API covers many resources, but the count pushes toward the high end and will increase selection difficulty.
The tool set comprehensively covers the domain: transactions (CRUD, bulk, split/group, attachments), accounts (manual/plaid/crypto, synced/crypto), categories, budgets, recurring items, tags, and balance history. No major obvious gaps for the apparent personal-finance API surface, aside from negligible attachment listing/deletion.
Maintenance
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that lets AI assistants interact with your Lunchmoney data, enabling natural language queries about transactions, budgets, and spending patterns.415 npm29MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that allows AI assistants to interact with Lunch Money accounts, enabling management of transactions, categories, budgets, and other financial data through natural language commands.20 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to interact directly with Lunch Money's financial API, allowing users to query transactions, access budget information, and perform financial analysis through natural language.-
- AlicenseBqualityCmaintenanceAn MCP server providing full integration with the Lunch Money API to manage financial data including transactions, budgets, assets, and categories. It enables AI assistants to perform CRUD operations on financial records through a standardized HTTP interface.26MIT