lunchmoney

LunchMoney MCP Server provides programmatic access to your LunchMoney data via the MCP protocol. It exposes a suite of tools for managing users, categories, tags, transactions, budgets, assets, Plaid accounts, and cryptocurrency holdings by interfacing with LunchMoney's API. The server uses a token-efficient encoding (TOON) for responses to optimize prompts in AI workflows, and is designed to plug into MCP-compatible clients like Claude Desktop. To use it, configure an MCP client to point at the LunchMoney server entry (usually by specifying the npx-based launch command and your LunchMoney API token). When you start the server, supply your LunchMoney API token and, optionally, enable debug logging to stderr for troubleshooting. The available tools allow you to retrieve data, create or modify records, and perform common financial management tasks through natural-language prompts processed by the MCP client.

Prerequisites:

• Node.js 16+ installed and available in your PATH
• npm or npx available
• A LunchMoney API token with appropriate permissions

Install and run the MCP server locally:

1. Install the MCP using npx (no global install required):

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

2. Alternatively, if you want to pin a specific version, you can run:

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

3. If you need to configure via MCP client configuration, use the following example to add LunchMoney as an MCP server:

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

4. Start the server and point your MCP client to the LunchMoney server entry (name: lunchmoney). Ensure your API token remains private and is not shared publicly.

Tips and common issues:

• Ensure your LunchMoney API token has the necessary permissions for the actions you intend to perform.
• If you encounter rate limits or API errors, enable LUNCHMONEY_DEBUG to get verbose request/response logs for troubleshooting.
• The server is designed to work as an MCP Bundle or via a client’s JSON configuration; for Claude Desktop, you can install the bundle or add it to the configuration under mcpServers.
• If the token or environment variables are not picked up, verify your shell exports and restart the MCP client or process.
• For production deployments, consider using a dedicated environment file or secret manager to inject LUNCHMONEY_API_TOKEN securely.