Skip to content
Back to search

lunchmoney-mcp

A Model Context Protocol (MCP) server implementation for LunchMoney, providing programmatic access to personal finance management through LunchMoney's API.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/akutishevsky--lunchmoney-mcp/badge.svg)](/listings/akutishevsky--lunchmoney-mcp)

HTML

<a href="/listings/akutishevsky--lunchmoney-mcp"><img src="/api/listings/akutishevsky--lunchmoney-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

<a id="mcp-bundle"></a>

MCP Bundle (.mcpb) - Recommended

The easiest way to install this server is as an MCP Bundle in Claude Desktop:

1. Download the latest `.mcpb` file from the [releases page](https://github.com/akutishevsky/lunchmoney-mcp/releases) 2. Open Claude Desktop and go to Extensions 3. Click "Install Extension" and select the downloaded `.mcpb` file 4. Enter your LunchMoney API token when prompted (get it from [LunchMoney Developer Settings](https://my.lunchmoney.app/developers)) 5. The LunchMoney tools will be immediately available

<a id="claude-code-cli"></a>

<details> <summary><strong>Claude Code CLI</strong></summary>

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-mcp

To 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-mcp

Verify the server was added:

claude mcp list
claude mcp get lunchmoney

</details>

<a id="codex-cli"></a>

<details> <summary><strong>Codex CLI</strong></summary>

Add the LunchMoney MCP server to Codex:

codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcp

To enable debug logging:

codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here --env LUNCHMONEY_DEBUG=true -- npx -y @akutishevsky/lunchmoney-mcp

Verify the server was added:

codex mcp list
codex mcp get lunchmoney

</details>

<a id="manual-mcp-configuration"></a>

<details> <summary><strong>Manual MCP Configuration</strong></summary>

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:

{
    "mcpServers": {
        "lunchmoney": {
            "command": "npx",
            "args": ["@akutishevsky/lunchmoney-mcp"],
            "env": {
                "LUNCHMONEY_API_TOKEN": "your-api-token-here",
                "LUNCHMONEY_DEBUG": "true"
            }
        }
    }
}

> **Note:** `LUNCHMONEY_DEBUG` is optional. Set it to `"true"` to enable debug logging of API requests and responses to stderr. Useful for troubleshooting.

> **Note:** `LUNCHMONEY_ATTACHMENTS_DIR` is optional. `attach_file_to_transaction` is 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 `~/Receipts` folder) 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](#remote-deployments).

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 486 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # LunchMoney MCP Server
  2. [![npm version](https://img.shields.io/npm/v/@akutishevsky/lunchmoney-mcp)](https://www.npmjs.com/package/@akutishevsky/lunchmoney-mcp)
  3. [![npm downloads](https://img.shields.io/npm/dm/@akutishevsky/lunchmoney-mcp?label=npm%20downloads)](https://www.npmjs.com/package/@akutishevsky/lunchmoney-mcp)
  4. [![GitHub downloads](https://img.shields.io/github/downloads/akutishevsky/lunchmoney-mcp/total?label=release%20downloads)](https://github.com/akutishevsky/lunchmoney-mcp/releases)
  5. [![license](https://img.shields.io/npm/l/@akutishevsky/lunchmoney-mcp)](https://github.com/akutishevsky/lunchmoney-mcp/blob/main/LICENSE)
  6. [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
  7. [![MCP Badge](https://lobehub.com/badge/mcp/akutishevsky-lunchmoney-mcp?style=plastic)](https://lobehub.com/mcp/akutishevsky-lunchmoney-mcp)
  8. A Model Context Protocol (MCP) server implementation for [LunchMoney](https://lunchmoney.app/), providing programmatic access to personal finance management through LunchMoney's API. Also available as an MCP Bundle (.mcpb) for easy installation in Claude Desktop.
  9. > **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, `null` or empty amounts, unpaired date ranges, updates with no fields, and conflicting fields such as `manual_account_id` with `plaid_account_id`. `delete_tag` and `delete_category` now report a 422 as an error, and a split child with `category_id: null` is sent as uncategorized instead of `0`. See [CHANGELOG.md](./CHANGELOG.md) for the full list. If you depend on the old behaviour, pin `@akutishevsky/lunchmoney-mcp@^3.0.0`.
  10. > **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's `GET /crypto`. Replace `get_all_crypto` with `get_all_manual_crypto` and `get_all_synced_crypto`, which together return everything it did and more. `update_manual_crypto` also drops its `currency` parameter. Nothing outside the crypto domain changed; if you don't use the crypto tools, upgrading from 2.x needs no action. See [CHANGELOG.md](./CHANGELOG.md). If you depend on `get_all_crypto`, pin `@akutishevsky/lunchmoney-mcp@^2.2.0`.
  11. > **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, `assets` is now `manual_accounts`, `tags` arrays are now `tag_ids`, transaction `asset_id` is now `manual_account_id`, the `debit_as_negative` toggle is gone, and the budget summary moved to a new `/summary` endpoint). See [CHANGELOG.md](./CHANGELOG.md) for the full list. If you depend on v1.x, pin `@akutishevsky/lunchmoney-mcp@^1.4.3`.
  12. <a href="https://glama.ai/mcp/servers/@akutishevsky/lunchmoney-mcp">
  13. <img width="380" height="200" src="https://glama.ai/mcp/servers/@akutishevsky/lunchmoney-mcp/badge" alt="LunchMoney Server MCP server" />
  14. </a>
  15. ## Table of Contents
  16. - [Overview](#overview)
  17. - [Features](#features)
  18. - [Usage](#usage)
  19. - [Installation Options](#installation-options)
  20. - [MCP Bundle](#mcp-bundle)
  21. - [Claude Code CLI](#claude-code-cli)
  22. - [Codex CLI](#codex-cli)
  23. - [Manual MCP Configuration](#manual-mcp-configuration)
  24. - [Standalone Server](#standalone-server)
  25. - [Remote Deployments](#remote-deployments)
  26. - [Example Prompts](#example-prompts)
  27. - [Available Tools](#available-tools)
  28. - [Development](#development)
  29. - [API Reference](#api-reference)
  30. - [Contributing](#contributing)
  31. - [License](#license)
  32. ## Overview
  33. 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.
  34. ## Features
  35. ### Comprehensive Tool Coverage
  36. - **User Management** - Access user account details
  37. - **Categories** - Full CRUD on categories and category groups
  38. - **Tags** - Full CRUD for transaction tags
  39. - **Transactions** - Full CRUD with advanced filtering, bulk update, bulk delete, splits, groups, and file attachments
  40. - **Recurring Items** - Track and manage recurring expenses, including system-suggested items
  41. - **Budgets** - Per-period budget summary, account-wide budget settings, upsert, and delete
  42. - **Manual Accounts** - Full CRUD for manually-managed accounts (formerly known as "assets")
  43. - **Plaid Accounts** - List, retrieve, and trigger sync of connected bank accounts
  44. - **Cryptocurrency** - Full CRUD for manual crypto balances, read and refresh synced crypto accounts, and manage the supported-cryptocurrency list
  45. - **Balance History** - Read, upsert, and delete monthly balance history for manual, Plaid, crypto, and deleted accounts
  46. ### Key Capabilities
  47. - Full integration with LunchMoney API v2 (alpha)
  48. - Type-safe implementation with TypeScript and Zod validation
  49. - Token-efficient responses using [TOON](https://github.com/nicfontaine/toon) encoding instead of JSON, reducing token usage in AI conversations
  50. - Modular architecture for easy extension
  51. - Standard MCP server implementation using stdio transport
  52. ## Usage
  53. ### Installation Options
  54. <a id="mcp-bundle"></a>
  55. #### MCP Bundle (.mcpb) - Recommended
  56. The easiest way to install this server is as an MCP Bundle in Claude Desktop:
  57. 1. Download the latest `.mcpb` file from the [releases page](https://github.com/akutishevsky/lunchmoney-mcp/releases)
  58. 2. Open Claude Desktop and go to Extensions
  59. 3. Click "Install Extension" and select the downloaded `.mcpb` file
  60. 4. Enter your LunchMoney API token when prompted (get it from [LunchMoney Developer Settings](https://my.lunchmoney.app/developers))
  61. 5. The LunchMoney tools will be immediately available
  62. <a id="claude-code-cli"></a>
  63. <details>
  64. <summary><strong>Claude Code CLI</strong></summary>
  65. Add the LunchMoney MCP server to Claude Code:
  66. ```bash
  67. claude mcp add lunchmoney --transport stdio -e LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcp
  68. ```
  69. To enable debug logging:
  70. ```bash
  71. claude mcp add lunchmoney --transport stdio -e LUNCHMONEY_API_TOKEN=your-api-token-here -e LUNCHMONEY_DEBUG=true -- npx -y @akutishevsky/lunchmoney-mcp
  72. ```
  73. Verify the server was added:
  74. ```bash
  75. claude mcp list
  76. claude mcp get lunchmoney
  77. ```
  78. </details>
  79. <a id="codex-cli"></a>
  80. <details>
  81. <summary><strong>Codex CLI</strong></summary>
  82. Add the LunchMoney MCP server to Codex:
  83. ```bash
  84. codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here -- npx -y @akutishevsky/lunchmoney-mcp
  85. ```
  86. To enable debug logging:
  87. ```bash
  88. codex mcp add lunchmoney --env LUNCHMONEY_API_TOKEN=your-api-token-here --env LUNCHMONEY_DEBUG=true -- npx -y @akutishevsky/lunchmoney-mcp
  89. ```
  90. Verify the server was added:
  91. ```bash
  92. codex mcp list
  93. codex mcp get lunchmoney
  94. ```
  95. </details>
  96. <a id="manual-mcp-configuration"></a>
  97. <details>
  98. <summary><strong>Manual MCP Configuration</strong></summary>
  99. To use this MCP server with any MCP-compatible client (such as Claude Desktop), you need to add it to the client's configuration.
  100. ##### Configuration
  101. 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:
  102. ```json
  103. {
  104. "mcpServers": {
  105. "lunchmoney": {
  106. "command": "npx",
  107. "args": ["@akutishevsky/lunchmoney-mcp"],
  108. "env": {
  109. "LUNCHMONEY_API_TOKEN": "your-api-token-here",
  110. "LUNCHMONEY_DEBUG": "true"
  111. }
  112. }
  113. }
  114. }
  115. ```
  116. > **Note:** `LUNCHMONEY_DEBUG` is optional. Set it to `"true"` to enable debug logging of API requests and responses to stderr. Useful for troubleshooting.
  117. > **Note:** `LUNCHMONEY_ATTACHMENTS_DIR` is optional. `attach_file_to_transaction` is 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 `~/Receipts` folder) 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](#remote-deployments).
  118. Replace `"your-api-token-here"` with your actual LunchMoney API token from [LunchMoney Developer Settings](https://my.lunchmoney.app/developers).
  119. ##### Common MCP Client Configuration Locations
  120. Different MCP clients store their configuration in different locations:
  121. - **Claude Desktop**:
  122. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  123. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  124. - Linux: `~/.config/Claude/claude_desktop_config.json`
  125. - **Other MCP Clients**: Check your client's documentation for the configuration file location.
  126. ##### Setup Steps
  127. 1. Locate your MCP client's configuration file (create it if it doesn't exist).
  128. 2. Add the LunchMoney server configuration to the `mcpServers` section.
  129. 3. Save the file and restart your MCP client.
  130. 4. The LunchMoney tools should now be available in your client.
  131. ##### Requirements
  132. - Node.js 16+ installed on your system
  133. - `npx` available in your system PATH
  134. - Valid LunchMoney API token with appropriate permissions
  135. </details>
  136. ### Standalone Server
  137. ```bash
  138. # Run with npx
  139. LUNCHMONEY_API_TOKEN="your-api-token" npx @akutishevsky/lunchmoney-mcp
  140. ```
  141. ## Remote Deployments
  142. The bundled stdio binary covers desktop MCP clients, but Claude on mobile and the [custom connectors](https://support.anthropic.com/en/articles/11503834-using-custom-connectors-with-claude) feature in [claude.ai](https://claude.ai) only speak HTTP. There are two ways to expose this server remotely.
  143. ### Turnkey: Cloudflare Workers
  144. [lunchmoney-mcp-cloudflare](https://github.com/bm1549/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](#embedding-as-a-library) stays per-user.
  145. ### Self-hosted: HTTP transport on your own host
  146. For a single-user deployment, wire `createServer()` into [`StreamableHTTPServerTransport`](https://github.com/modelcontextprotocol/typescript-sdk#streamable-http-transport) and serve it from any Node HTTP framework. Example with Express:
  147. ```ts
  148. import express from "express";
  149. import { createServer } from "@akutishevsky/lunchmoney-mcp/server";
  150. import { initializeConfig } from "@akutishevsky/lunchmoney-mcp/config";
  151. import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
  152. initializeConfig(process.env.LUNCHMONEY_API_TOKEN!);
  153. const server = createServer("1.0.0");
  154. const transport = new StreamableHTTPServerTransport({
  155. sessionIdGenerator: () => crypto.randomUUID(),
  156. });
  157. await server.connect(transport);
  158. const app = express();
  159. app.use(express.json());
  160. app.all("/mcp", (req, res) => transport.handleRequest(req, res, req.body));
  161. app.listen(3000);
  162. ```
  163. 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.
  164. > **Set `LUNCHMONEY_ATTACHMENTS_DIR` on any remote deployment.** `attach_file_to_transaction` reads 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.
  165. > **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](#embedding-as-a-library); fork the process per user or use the Cloudflare option above (each user gets their own isolate).
  166. ## Example Prompts
  167. Here are some example prompts you can use with the LunchMoney MCP server:
  168. ### Account Overview
  169. - "Show me my LunchMoney account details"
  170. - "What's my current account status?"
  171. ### Category Management
  172. - "List all my spending categories"
  173. - "Create a new category called 'Subscriptions' with a monthly budget of $100"
  174. - "Show me details for my 'Food & Dining' category"
  175. - "Create a category group for all my entertainment expenses"
  176. - "Delete the 'Unused Category' and reassign its transactions to 'Miscellaneous'"
  177. ### Transaction Management
  178. - "Show me all transactions from last month"
  179. - "Find all transactions over $100 in the past week"
  180. - "Create a new expense for $45.99 at Amazon in the Shopping category"
  181. - "Update transaction #12345 to change the amount to $50"
  182. - "Show me all pending transactions"
  183. - "Group these coffee shop transactions together"
  184. ### Budgeting
  185. - "Show me my budget summary for this month"
  186. - "Set a budget of $500 for Groceries this month"
  187. - "Remove the budget for Entertainment category"
  188. - "How much have I spent vs budgeted in each category?"
  189. ### Manual Account Tracking
  190. - "List all my manual accounts"
  191. - "Create a new manual account for my savings account with a balance of $10,000"
  192. - "Update my investment account balance to $25,000"
  193. - "Close my old credit card account"
  194. ### Recurring Expenses
  195. - "Show me all my recurring expenses"
  196. - "What subscriptions do I have?"
  197. - "List recurring items for the next 3 months"
  198. ### Banking Integration
  199. - "Show me all my connected Plaid accounts"
  200. - "Refresh my bank account data"
  201. - "Trigger a sync for my checking account"
  202. ### Cryptocurrency
  203. - "Show me all my crypto holdings"
  204. - "Update my Bitcoin balance to 0.5 BTC"
  205. - "List all my manually tracked crypto assets"
  206. - "Add a cold wallet holding 0.85 BTC called Ledger Cold Storage"
  207. - "Refresh my Coinbase account and show the updated balances"
  208. - "Which cryptocurrencies can I track manually?"
  209. ### Net Worth & Balance History
  210. - "Show me how my net worth changed over the last 12 months"
  211. - "What was my savings account balance in March 2026?"
  212. - "Set my car's value to $18,000 for June 2026"
  213. - "Clear the balance history for my old brokerage account"
  214. ### Analysis & Insights
  215. - "What are my top spending categories this month?"
  216. - "Show me all transactions tagged as 'vacation'"
  217. - "Find all transactions at coffee shops"
  218. - "List all transactions that need to be categorized"
  219. ## Available Tools
  220. ### User Tools
  221. - `get_user` - Retrieve current user details
  222. - `get_account_settings` - Get account-wide settings (currencies, locale, display name, rule automation)
  223. - `update_account_settings` - Update account-wide settings (at least one field required)
  224. - `get_user_settings` - Get user-wide display and formatting preferences
  225. - `update_user_settings` - Update user-wide display and formatting preferences (at least one field required)
  226. - `get_user_account_settings` - Get user-specific settings within the budget account
  227. - `update_user_account_settings` - Update user-specific account settings, such as the default manual account (at least one field required)
  228. ### Category Tools
  229. - `get_all_categories` - List all categories (supports `format` and `is_group` filters)
  230. - `get_single_category` - Get details for a specific category or category group
  231. - `create_category` - Create a category or category group (set `is_group=true` plus `children`)
  232. - `update_category` - Update properties; replaces the children list on category groups
  233. - `delete_category` - Delete a category; pass `force=true` to override dependency check
  234. ### Tag Tools
  235. - `get_all_tags` - List all tags
  236. - `get_single_tag` - Get a tag by ID
  237. - `create_tag` - Create a new tag
  238. - `update_tag` - Update tag properties
  239. - `delete_tag` - Delete a tag (with `force` to override dependents)
  240. ### Transaction Tools
  241. - `get_transactions` - List transactions with extensive filtering options (date range, account, category, tag, status, pending, metadata, files, etc)
  242. - `get_single_transaction` - Get full transaction details (always includes plaid_metadata, custom_metadata, files, and children for split/group parents)
  243. - `create_transactions` - Insert 1–500 transactions in one call
  244. - `update_transaction` - Partial update of one transaction
  245. - `delete_transaction` - Delete one transaction (cannot be split/group)
  246. - `update_transactions_bulk` - Bulk update 1–500 transactions
  247. - `delete_transactions_bulk` - Bulk delete 1–500 transactions by ID
  248. - `create_transaction_group` - Create a transaction group from existing transactions
  249. - `delete_transaction_group` - Ungroup a transaction group
  250. - `split_transaction` - Split a transaction into 2–500 children
  251. - `unsplit_transaction` - Undo a previous split
  252. - `attach_file_to_transaction` - Upload a local file (jpeg/png/heic/heif/pdf, ≤10MB), type verified from its contents
  253. - `get_transaction_attachment_url` - Get a signed download URL for a file attachment
  254. - `delete_transaction_attachment` - Delete a file attachment
  255. ### Recurring Items Tools
  256. - `get_recurring_items` - List recurring items for a date range (`include_suggested` for system suggestions)
  257. - `get_single_recurring_item` - Get a recurring item by ID
  258. ### Budget Tools
  259. - `get_budget_summary` - Per-category budget summary (backed by `/summary`); supports occurrences, totals, rollover-pool toggles
  260. - `get_budget_settings` - Account-wide budget period and display settings
  261. - `upsert_budget` - Create or update a budget for a category and period
  262. - `remove_budget` - Remove a budget for a category and period
  263. ### Manual Account Tools
  264. - `get_all_manual_accounts` - List all manually-managed accounts (formerly "assets")
  265. - `get_single_manual_account` - Get a manual account by ID
  266. - `create_manual_account` - Create a new manually-managed account
  267. - `update_manual_account` - Update properties of a manual account
  268. - `delete_manual_account` - Delete a manual account; optionally also delete its transactions / balance history
  269. ### Plaid Account Tools
  270. - `get_all_plaid_accounts` - List all connected Plaid accounts
  271. - `get_single_plaid_account` - Get a Plaid account by ID
  272. - `trigger_plaid_fetch` - Trigger fetch of latest data from Plaid (optionally scoped to a date range or account)
  273. ### Crypto Tools
  274. - `get_supported_cryptocurrencies` - List the cryptocurrencies supported for manual tracking (optional `search` filter)
  275. - `add_supported_cryptocurrency` - Add a cryptocurrency to the supported list from its CoinGecko coin-page URL
  276. - `get_all_manual_crypto` - List all manually-managed crypto balances
  277. - `get_single_manual_crypto` - Get a single manually-managed crypto balance by ID
  278. - `create_manual_crypto` - Create a manually-managed crypto asset
  279. - `update_manual_crypto` - Update a manual crypto balance's name, display name, institution name, or balance
  280. - `delete_manual_crypto` - Delete a manual crypto asset (irreversible)
  281. - `get_all_synced_crypto` - List synced crypto accounts and their nested per-symbol balances
  282. - `get_single_synced_crypto` - Get a single synced crypto account by ID
  283. - `get_synced_crypto_balance` - Get one balance inside a synced crypto account by symbol
  284. - `refresh_synced_crypto` - Trigger a balance refresh for a synced crypto account
  285. ### Balance History Tools
  286. - `get_balance_history` - Get monthly balance history across all accounts (powers the Net Worth views); optional `start_month`/`end_month` (YYYY-MM) range filter
  287. - `get_account_balance_history` - Get monthly balance history for one account (`manual`, `plaid`, `crypto_manual`, or `deleted`)
  288. - `upsert_account_balance_history` - Create or update monthly balance entries for one account (past months only; all-or-nothing)
  289. - `delete_account_balance_history` - Delete all historical balance entries for one account
  290. - `get_crypto_synced_balance_history` - Get monthly balance history for a synced crypto holding by account id + ticker symbol
  291. - `upsert_crypto_synced_balance_history` - Create or update monthly balance entries for a synced crypto holding
  292. - `delete_crypto_synced_balance_history` - Delete all historical balance entries for a synced crypto holding
  293. - `delete_balance_history_entry` - Delete a single historical balance entry by id
  294. - `update_deleted_account_details` - Update the display details (name, institution, type, subtype, mask) shown for a deleted account's balance history
  295. ## Development
  296. ### Project Structure
  297. ```
  298. lunchmoney-mcp/
  299. ├── src/
  300. │ ├── index.ts # Server entry point
  301. │ ├── config.ts # Configuration management
  302. │ ├── types.ts # TypeScript type definitions
  303. │ └── tools/ # Tool implementations
  304. │ ├── user.ts
  305. │ ├── categories.ts
  306. │ ├── tags.ts
  307. │ ├── transactions.ts
  308. │ ├── recurring-items.ts
  309. │ ├── budgets.ts
  310. │ ├── manual-accounts.ts
  311. │ ├── plaid-accounts.ts
  312. │ ├── crypto.ts
  313. │ └── balance-history.ts
  314. ├── build/ # Compiled JavaScript output
  315. ├── package.json
  316. ├── tsconfig.json
  317. └── README.md
  318. ```
  319. ### Building
  320. ```bash
  321. # Build the MCP server
  322. npm run build
  323. # Build MCPB package for distribution
  324. npm run build:mcpb
  325. ```
  326. ### Adding New Tools
  327. 1. Create a new file in `src/tools/`
  328. 2. Implement tool handlers using the MCP SDK
  329. 3. Register tools in `src/index.ts`
  330. 4. Add types to `src/types.ts` if needed
  331. ### Embedding as a library
  332. 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:
  333. ```ts
  334. import { createServer } from "@akutishevsky/lunchmoney-mcp/server";
  335. import { initializeConfig } from "@akutishevsky/lunchmoney-mcp/config";
  336. initializeConfig(process.env.LUNCHMONEY_API_TOKEN!);
  337. const server = createServer("1.0.0");
  338. // connect `server` to whatever transport you need
  339. ```
  340. `initializeConfig` must be called before any tool is invoked, or the first request throws `"Configuration not initialized."`.
  341. > **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 `initializeConfig` calls would race and leak tokens between requests. Those consumers need to fork per-user or refactor the singleton before exposing the package.
  342. ## API Reference
  343. The server implements the full LunchMoney API v2. For detailed API documentation, see:
  344. - [LunchMoney v2 API Documentation](https://alpha.lunchmoney.dev/v2)
  345. - [v2 Migration Guide](https://alpha.lunchmoney.dev/v2/migration-guide)
  346. - [Model Context Protocol Specification](https://modelcontextprotocol.io/)
  347. ## Contributing
  348. Contributions are welcome! Please feel free to submit a Pull Request.
  349. ## License
  350. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.