Lunch Money

What Lunch Money does

Lunch Money exposes personal-finance operations through MCP tools backed by LunchMoney's v2 API. It can read the current user's details, list and manage categories and category groups, and create, update, or delete transaction tags. Category and tag deletions protect dependent records by returning a structured dependency error unless a force option is used.

Transaction coverage is the largest part of the server. Agents can query transactions with filters such as dates, accounts, categories, tags, recurring items, and status; retrieve detailed records; create, edit, and delete transactions; and perform bulk updates or deletions. The server also handles transaction groups, splits, unsplitting, and receipt files. Recurring items and budget information are available for planning and review workflows.

How it works

The server implements MCP over stdio, allowing a compatible client to launch it as a local process. Requests are sent to LunchMoney's API using an API token, and responses are encoded with TOON rather than ordinary JSON to reduce token use in conversations. Input validation uses the LunchMoney v2 specification and rejects several invalid requests before they reach the API.

Transaction operations have important visibility rules. Pending transactions and split or group child records are excluded from ordinary transaction searches by default. Split or group parents can be inspected with the single-transaction tool, which includes their children. Creating a split requires child amounts to add up to the parent amount, while grouping accepts between two and 500 existing transactions.

Setup and configuration

Install the npm package through an MCP client's stdio configuration, for example with npx -y @akutishevsky/lunchmoney-mcp. Set LUNCHMONEY_API_TOKEN to a token obtained from LunchMoney Developer Settings. The server can also be installed in Claude Desktop from its downloadable MCP Bundle, which prompts for the token during installation.

Claude Code and Codex CLI have dedicated commands for registering the server. Other MCP-compatible clients can use a configuration entry with npx as the command and the package name as its argument. Set LUNCHMONEY_DEBUG=true to write API request and response debugging information to stderr.

For receipt uploads, attach_file_to_transaction reads the file from the host running the server. LUNCHMONEY_ATTACHMENTS_DIR can restrict uploads to one directory; paths outside it, including those reached through disallowed symlinks or parent-directory traversal, are rejected.

Tools and capabilities

• Read user details with get_user.
• Create, inspect, update, and delete categories and category groups.
• Create, inspect, update, and delete tags.
• Query transactions with filters and retrieve expanded single-transaction details.
• Create up to 500 transactions in one request and report skipped duplicates.
• Update or delete individual transactions, or process batches of up to 500 records.
• Create and remove transaction groups, or split and unsplit transactions.
• Attach, download through a signed URL, and delete receipt files.
• Retrieve recurring items and populate their date-range matches.
• Read budget settings and summaries, including optional per-period occurrences.
• Create or update a category budget for a valid budget-period start date.

Limitations and notes

Destructive operations are irreversible where noted by the API, including forced category or tag deletion, transaction deletion, unsplitting, and attachment deletion. Category and tag deletion normally fails when dependent records exist; force deletion disassociates those records.

Individual and bulk transaction updates cannot modify split or grouped transactions. Those records must be handled with the relevant split or group operation. A transaction group cannot include split or recurring transactions, and a split must contain between two and 500 children whose amounts equal the parent.

Receipt uploads are limited to real JPEG, PNG, HEIC, HEIF, or PDF files no larger than 10 MB. Attachment download URLs are short-lived and include an expiration timestamp. Transaction searches return at most 2,000 records per request and indicate when more matches exist. The server targets LunchMoney's v2 API, described as alpha in its project documentation.