Skip to main content
Glama
Lunch Money MCP Server

Lunch Money MCP Server

by robshox

Servidor MCP de Lunch Money

TypeScript Node.js Licencia

Un servidor del Protocolo de Contexto de Modelo (MCP) que permite a los agentes de IA interactuar con tus datos de finanzas personales de Lunch Money.

Características

Este servidor MCP expone 15 herramientas para gestionar tus datos financieros:

Usuario y Cuenta

  • get_user — Obtén tu perfil e información de cuenta

Categorías

  • get_categories — Lista todas las categorías (planas o anidadas)

  • create_category — Crea nuevas categorías personalizadas

  • update_category — Modifica categorías existentes

Transacciones

  • get_transactions — Consulta transacciones con filtros (rango de fechas, categoría, estado, etc.)

  • create_transaction — Añade nuevas transacciones (individuales o por lotes de hasta 500)

  • update_transaction — Actualiza transacciones o divídelas en múltiples entradas

Activos y Cuentas

  • get_assets — Lista los activos gestionados manualmente

  • create_asset — Añade nuevos activos manuales

  • get_plaid_accounts — Lista las cuentas bancarias conectadas mediante Plaid

  • trigger_plaid_fetch — Activa la sincronización de cuentas de Plaid

Presupuestos y Planificación

  • get_budgets — Visualiza presupuestos y gastos para cualquier rango de fechas

  • upsert_budget — Establece o actualiza importes presupuestarios

  • get_recurring_items — Visualiza gastos e ingresos recurrentes

Etiquetas

  • get_tags — Lista todas las etiquetas de transacciones

Related MCP server: LunchMoney MCP Server

Requisitos previos

Instalación

Opción 1: Clonar y compilar (transporte stdio local)

Para uso local con Cursor, Claude Desktop u otros clientes MCP basados en stdio:

# Clone the repository
git clone https://github.com/yourusername/lunchmoney-mcp.git
cd lunchmoney-mcp

# Install dependencies
npm install

# Build the TypeScript
npm run build

Opción 2: Cloudflare Workers (transporte HTTP remoto)

Despliega como un servidor MCP remoto accesible vía HTTP:

# Clone the repository
git clone https://github.com/yourusername/lunchmoney-mcp.git
cd lunchmoney-mcp

# Install dependencies
npm install

# Set your API key as a secret
npx wrangler secret put LUNCH_MONEY_API_KEY
# Enter your Lunch Money API key when prompted

# Deploy to Cloudflare Workers
npm run deploy

Opción 3: Usar con npx (solo local)

Puedes ejecutar el servidor MCP directamente sin clonar:

npx -y lunchmoney-mcp

Nota: Aún necesitarás configurar la variable de entorno LUNCH_MONEY_API_KEY.

Configuración

Obtener tu clave de API

  1. Inicia sesión en Lunch Money

  2. Ve a Configuración → Desarrolladores

  3. Genera una nueva clave de API

  4. Copia la clave (¡mantenla segura!)

Cursor IDE

Añade a tu configuración MCP de Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "lunchmoney": {
      "command": "node",
      "args": ["/path/to/lunchmoney-mcp/dist/index.js"],
      "env": {
        "LUNCH_MONEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

O con npx:

{
  "mcpServers": {
    "lunchmoney": {
      "command": "npx",
      "args": ["-y", "lunchmoney-mcp"],
      "env": {
        "LUNCH_MONEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "lunchmoney": {
      "command": "node",
      "args": ["/path/to/lunchmoney-mcp/dist/index.js"],
      "env": {
        "LUNCH_MONEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Otros clientes MCP

Cualquier cliente MCP que soporte transporte stdio puede usar este servidor. Configura la variable de entorno LUNCH_MONEY_API_KEY y ejecuta:

node /path/to/lunchmoney-mcp/dist/index.js

MCP remoto vía Cloudflare Workers (Trae tu propia clave API)

El despliegue en Cloudflare Workers está diseñado como un servidor MCP público donde cada usuario aporta su propia clave API. El servidor nunca almacena ninguna clave API.

Cómo funciona:

  1. Despliega el servidor en Cloudflare Workers (o usa una instancia compartida)

  2. Cada usuario se conecta con su propia clave API de Lunch Money

  3. La clave API se envía con cada solicitud en el encabezado X-LunchMoney-API-Key

Conectando con el proxy mcp-remote:

{
  "mcpServers": {
    "lunchmoney": {
      "command": "npx",
      "args": ["mcp-remote", "https://lunchmoney-mcp.your-subdomain.workers.dev/mcp"],
      "env": {
        "MCP_HEADERS": "X-LunchMoney-API-Key: your_api_key_here"
      }
    }
  }
}

Nota: El proxy mcp-remote debe soportar encabezados personalizados. Es posible que algunos clientes MCP aún no soporten esto.

⚠️ Trata tu archivo mcp.json como un archivo de credenciales. Ahora contiene tu clave API de Lunch Money. Nunca lo subas a un repositorio Git (incluyendo repositorios de archivos de configuración). Añádelo a .gitignore si reside dentro de uno. Cualquiera con acceso de lectura a este archivo puede leer y modificar tus datos de Lunch Money.

Seguridad: Este es el modelo más seguro porque:

  • El servidor nunca almacena ninguna clave API

  • Cada usuario solo accede a sus propios datos

  • Las claves API se pasan por solicitud, no se almacenan en el servidor

  • El worker público aplica límites de tasa por IP y nunca registra cuerpos o encabezados de solicitud

Despliegue en Cloudflare Workers (Servidor Público)

Esto crea un servidor MCP público que cualquiera puede usar con su propia clave API. El servidor no almacena ninguna credencial.

Requisitos previos

  • Una cuenta de Cloudflare (el nivel gratuito funciona)

  • Wrangler CLI instalado

Despliegue

  1. Instalar dependencias:

 npm install
  1. Desplegar en Cloudflare Workers:

 npm run deploy
  1. ¡Tu servidor MCP público ya está activo! La URL se mostrará en la salida:

 https://lunchmoney-mcp.your-account.workers.dev/mcp

Opcional: Puedes establecer una clave API predeterminada para pruebas:

npx wrangler secret put LUNCH_MONEY_API_KEY

Cómo se conectan los usuarios

Los usuarios se conectan a tu servidor público con su propia clave API de Lunch Money:

{
  "mcpServers": {
    "lunchmoney": {
      "command": "npx",
      "args": ["mcp-remote", "https://lunchmoney-mcp.your-account.workers.dev/mcp"],
      "env": {
        "MCP_HEADERS": "X-LunchMoney-API-Key: their_api_key_here"
      }
    }
  }
}

Desarrollo local con Wrangler

# Run locally with hot reload
npm run dev:worker

Modelo de seguridad

  • El servidor nunca almacena claves API — las claves se pasan por solicitud mediante encabezado

  • Los usuarios solo acceden a sus propios datos — cada solicitud usa la propia clave del usuario

  • Accesible públicamente — cualquiera puede usar el servidor, pero necesitan su propia cuenta de Lunch Money

Esto es similar a cómo funcionan las pasarelas de API públicas: la infraestructura es compartida, pero las credenciales son por usuario.

Ejemplos de uso

Una vez configurado, puedes hacer preguntas a tu asistente de IA como:

  • "Muéstrame mis gastos por categoría este mes"

  • "¿Cuál fue mi mayor gasto la semana pasada?"

  • "Categoriza todas mis transacciones sin categoría de marzo"

  • "Crea una nueva categoría llamada 'Ingresos Freelance'"

  • "¿Cuánto gasté en comestibles en el primer trimestre?"

  • "Lista todas mis suscripciones recurrentes"

Desarrollo

Modo stdio local (para Cursor, Claude Desktop)

# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Type check without emitting
npm run typecheck

# Test with MCP Inspector
npm run inspect

Modo Cloudflare Workers (para acceso HTTP remoto)

# Build the Worker
npm run build

# Run locally with Wrangler
npm run dev:worker

# Deploy to production
npm run deploy

Estructura del proyecto

src/
├── index.ts           # MCP server entry point (stdio mode)
├── worker.ts          # Cloudflare Workers entry point (HTTP mode)
├── client.ts          # Lunch Money API client
├── types.ts           # TypeScript type definitions
├── tool-utils.ts      # Shared tool utilities
└── tools/             # Individual tool implementations
    ├── user.ts
    ├── categories.ts
    ├── transactions.ts
    ├── assets.ts
    ├── plaid.ts
    ├── budgets.ts
    ├── recurring.ts
    └── tags.ts

Modos de despliegue

Modo

Transporte

Caso de uso

Punto de entrada

Local

stdio

Cursor, Claude Desktop

src/index.ts

Cloudflare Workers

Streamable HTTP

Acceso remoto, clientes web

src/worker.ts

Ambos modos comparten las mismas implementaciones de herramientas y cliente API.

Seguridad

Protección de la clave API

  • Nunca subas tu clave API. El archivo .env está en .gitignore por esta razón.

  • Almacena tu clave en variables de entorno o archivos de configuración MCP seguros.

  • Si tu clave queda expuesta, revócala inmediatamente en Desarrolladores de Lunch Money y genera una nueva.

Privacidad de datos

  • Este servidor actúa como un proxy entre tu asistente de IA y Lunch Money.

  • Tus datos financieros se procesan de acuerdo con la política de privacidad de Lunch Money.

  • Los mensajes de error se desinfectan para evitar la divulgación accidental de información.

Permisos

La clave API que proporcionas determina qué acciones puede realizar el servidor MCP. Las claves API de Lunch Money pueden:

  • Leer todos tus datos financieros

  • Crear, actualizar y eliminar transacciones

  • Modificar categorías y presupuestos

  • Activar sincronizaciones de Plaid

Referencia de la API

Este servidor MCP utiliza la API v1 de Lunch Money.

Límites de tasa

La API de Lunch Money tiene límites de tasa. El servidor MCP pasará cualquier error de límite de tasa de la API. Si encuentras un límite de tasa, espera unos minutos antes de volver a intentarlo.

Manejo de errores

El servidor maneja los errores de la API de Lunch Money y los devuelve como errores de herramientas MCP. Algunas notas:

  • Lunch Money a veces devuelve errores lógicos como respuestas HTTP 200; estos se normalizan en errores adecuados

  • El servidor desinfecta los mensajes de error para eliminar información potencialmente sensible

  • Los detalles completos del error se registran en stderr para depuración

Solución de problemas

Error "Missing LUNCH_MONEY_API_KEY"

La variable de entorno LUNCH_MONEY_API_KEY no está configurada. Revisa tu configuración MCP y asegúrate de que la clave esté configurada correctamente.

Error "Unauthorized"

Tu clave API puede ser inválida o haber sido revocada. Verifica tu clave en https://my.lunchmoney.app/developers

Las transacciones no aparecen

Si usas cuentas conectadas a Plaid, es posible que necesites activar una sincronización:

  • Usa la herramienta trigger_plaid_fetch para poner en cola una sincronización en segundo plano

  • Ten en cuenta que esto solo pone en cola el trabajo; puede tardar unos minutos en que aparezcan las transacciones

Contribución

¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar un Pull Request.

  1. Haz un fork del repositorio

  2. Crea tu rama de características (git checkout -b feature/amazing-feature)

  3. Confirma tus cambios (git commit -m 'feat: add amazing feature')

  4. Empuja a la rama (git push origin feature/amazing-feature)

  5. Abre un Pull Request

Licencia

Este proyecto está bajo la Licencia ISC; consulta el archivo LICENSE para más detalles.

Reconocimientos

Soporte


Descargo de responsabilidad: Este es un proyecto comunitario no oficial. No está afiliado ni respaldado por Lunch Money.

Available Tools

15 tools
create_assetC

Create a manually managed asset in Lunch Money.

Inputs: type_name (required), name (required), balance (required), subtype_name, +6 more.

create_categoryC

Create a new Lunch Money category.

Inputs: name (required), description, is_income, exclude_from_budget, +3 more.

create_transactionC

Create one or more Lunch Money transactions.

Inputs: transactions (required), apply_rules, skip_duplicates, check_for_recurring, +2 more.

get_assetsA
Read-only

List manually managed Lunch Money assets.

Inputs: no named parameters.

get_budgetsA
Read-only

Get Lunch Money budgets and spending for a date range.

Inputs: start_date (required), end_date (required), currency.

get_categoriesA
Read-only

List Lunch Money categories in flattened or nested form.

Inputs: format.

get_plaid_accountsA
Read-only

List Lunch Money Plaid-connected accounts.

Inputs: no named parameters.

get_recurring_itemsA
Read-only

Get Lunch Money recurring items for the current or specified month range.

Inputs: start_date, end_date, debit_as_negative.

get_tagsA
Read-only

List all Lunch Money tags.

Inputs: no named parameters.

get_transactionsC
Read-only

Get Lunch Money transactions with optional filters.

Inputs: tag_id, recurring_id, plaid_account_id, category_id, +9 more.

get_userA
Read-only

Get information about the Lunch Money user connected to the configured API key.

Inputs: no named parameters.

trigger_plaid_fetchC

Trigger a Lunch Money fetch for eligible Plaid accounts. This queues a background fetch job.

Inputs: start_date, end_date, plaid_account_id.

update_categoryC

Update an existing Lunch Money category.

Inputs: category_id (required), name, description, is_income, +4 more.

update_transactionC

Update a Lunch Money transaction or split it into multiple child transactions.

Inputs: transaction_id (required), transaction, split, debit_as_negative, +1 more.

upsert_budgetC

Create or update a Lunch Money budget entry for a category and month.

Inputs: start_date (required), category_id (required), amount (required), currency.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action, with clear separation between asset, category, transaction, budget, account, recurring item, tag, and user operations. No overlapping functionality.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (e.g., create_asset, get_transactions, update_category), using the same set of verbs (create, get, update, upsert, trigger) throughout.

    Tool Count5/5

    With 15 tools, the server covers the core aspects of personal finance management without being overloaded or underdeveloped. Each tool has a clear purpose.

    Completeness2/5

    The server provides create, read, and update operations for several resources, but lacks delete operations for all resources and missing update for assets and recurring items. Tags only have a get operation, leaving significant gaps in the lifecycle.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables managing personal finances through the Lunch Money API, including transactions, categories, budgets, and accounts via natural language commands.
      14
      5
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants and MCP clients to access and manage personal finance data through LunchMoney's API, including transactions, budgets, categories, tags, recurring items, accounts, crypto, and balance history.
      41 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants and MCP clients to access and manage LunchMoney personal finance data, including transactions, categories, tags, budgets, accounts, recurring items, and crypto through LunchMoney's API.
      41 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants and MCP clients to manage personal finance data through the LunchMoney API, including transactions, budgets, categories, tags, accounts, recurring items, and crypto balances.
      41 npm
      MIT