playbooks

home / mcp / lunchmoney mcp server

LunchMoney MCP Server

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

Installation
Add the following to your MCP client configuration file.

Configuration

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

You can use the LunchMoney MCP Server to access and manage your LunchMoney data through a standard MCP client. It exposes tools for transactions, categories, budgets, assets, and more, enabling AI assistants and other MCP clients to perform automated financial insights and actions.

How to use

Connect to the LunchMoney MCP Server from your MCP client to perform common tasks such as viewing account details, listing and managing categories, handling transactions, tracking budgets and recurring items, and querying asset and crypto data. Use your MCP client’s built-in mechanisms to discover available tools, then compose prompts that map to those tools to fetch data, create or update items, or run analyses. For example, request a summary of your budget, list recent transactions, or fetch all assets and their balances.

How to install

Prerequisites you need before installing: node.js 16+ and npm or npx available in your system path. You will also need a valid LunchMoney API token with appropriate permissions.

Option 1: Desktop Extension Tool (DXT) - Recommended. Install as a Desktop Extension Tool in your Claude Desktop environment to run directly from the desktop.

Option 2: Manual MCP Configuration. Use a local MCP client configuration file to connect to the server as described below.

Standalone run command (when starting from the MCP host): set your API token and run the MCP server with npx.

LUNCHMONEY_API_TOKEN="your-api-token" npx @akutishevsky/lunchmoney-mcp

Configuration

The LunchMoney MCP Server is configured as a standard MCP entry. Use the following configuration snippet in your MCP client to connect via a local stdio integration. The environment variable LUNCHMONEY_API_TOKEN must be set to your LunchMoney API token.

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

Security and tokens

Protect your LunchMoney API token. Use a token with the minimum necessary permissions for your tasks. Do not share tokens or embed them in publicly accessible configurations.

Examples of common tasks

Account overview: fetch your current user details and summary of the LunchMoney account.

Category management: list all categories, create new ones, or update category properties.

Transaction management: list, create, update, or group transactions, including filtering by date, amount, or status.

Budgets and assets: retrieve budget summaries and manage manually tracked assets.

Plaid accounts and crypto: view connected accounts and manually tracked crypto holdings.

Notes

If you plan to run the server locally, ensure Node.js 16+ is installed and that npx is available in your command path. When you start the server, provide your LunchMoney API token via an environment variable as shown in the configuration example.

Troubleshooting

If you encounter connection issues, verify that the API token is valid and has the necessary permissions. Check that the MCP client configuration points to the LunchMoney MCP entry and that the environment variable is correctly set in your runtime environment.

Available tools

get_user

Retrieve current user details from LunchMoney.

get_all_categories

List all spending categories.

get_single_category

Get details for a specific category.

create_category

Create a new spending category.

create_category_group

Create a group of categories.

update_category

Update properties of an existing category.

add_to_category_group

Add categories to a category group.

delete_category

Delete a category.

force_delete_category

Force delete a category with data cleanup.

get_all_tags

List all available tags.

get_transactions

List transactions with extensive filtering options.

get_single_transaction

Get detailed information about a specific transaction.

create_transactions

Create new transactions.

update_transaction

Update an existing transaction.

unsplit_transactions

Remove transactions from split groups.

get_transaction_group

Get details of a transaction group.

create_transaction_group

Create a transaction group.

delete_transaction_group

Delete a transaction group.

get_recurring_items

List recurring items for a date range.

get_budget_summary

Get budget summary by date range.

upsert_budget

Create or update budget amounts.

remove_budget

Remove budget for a category.

get_all_assets

List all manually-managed assets.

create_asset

Create a new asset.

update_asset

Update asset properties.

get_all_plaid_accounts

List all connected Plaid accounts.

trigger_plaid_fetch

Trigger fetch of latest data from Plaid.

get_all_crypto

List all cryptocurrency assets.

update_manual_crypto

Update balance for manually-managed crypto.