Lunch Money MCP Server
Servidor MCP de Lunch Money
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 personalizadasupdate_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 manualmentecreate_asset— Añade nuevos activos manualesget_plaid_accounts— Lista las cuentas bancarias conectadas mediante Plaidtrigger_plaid_fetch— Activa la sincronización de cuentas de Plaid
Presupuestos y Planificación
get_budgets— Visualiza presupuestos y gastos para cualquier rango de fechasupsert_budget— Establece o actualiza importes presupuestariosget_recurring_items— Visualiza gastos e ingresos recurrentes
Etiquetas
get_tags— Lista todas las etiquetas de transacciones
Related MCP server: LunchMoney MCP Server
Requisitos previos
Node.js 18 o superior
Una cuenta de Lunch Money con acceso a la API
Una clave de API de Lunch Money desde la página de desarrolladores
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 buildOpció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 deployOpción 3: Usar con npx (solo local)
Puedes ejecutar el servidor MCP directamente sin clonar:
npx -y lunchmoney-mcpNota: Aún necesitarás configurar la variable de entorno LUNCH_MONEY_API_KEY.
Configuración
Obtener tu clave de API
Inicia sesión en Lunch Money
Genera una nueva clave de API
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.jsMCP 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:
Despliega el servidor en Cloudflare Workers (o usa una instancia compartida)
Cada usuario se conecta con su propia clave API de Lunch Money
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.jsoncomo 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.gitignoresi 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
Instalar dependencias:
npm installDesplegar en Cloudflare Workers:
npm run deploy¡Tu servidor MCP público ya está activo! La URL se mostrará en la salida:
https://lunchmoney-mcp.your-account.workers.dev/mcpOpcional: Puedes establecer una clave API predeterminada para pruebas:
npx wrangler secret put LUNCH_MONEY_API_KEYCó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:workerModelo 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 inspectModo 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 deployEstructura 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.tsModos de despliegue
Modo | Transporte | Caso de uso | Punto de entrada |
Local | stdio | Cursor, Claude Desktop |
|
Cloudflare Workers | Streamable HTTP | Acceso remoto, clientes web |
|
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
.envestá en.gitignorepor 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_fetchpara poner en cola una sincronización en segundo planoTen 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.
Haz un fork del repositorio
Crea tu rama de características (
git checkout -b feature/amazing-feature)Confirma tus cambios (
git commit -m 'feat: add amazing feature')Empuja a la rama (
git push origin feature/amazing-feature)Abre un Pull Request
Licencia
Este proyecto está bajo la Licencia ISC; consulta el archivo LICENSE para más detalles.
Reconocimientos
Construido con el SDK de TypeScript del Protocolo de Contexto de Modelo
Impulsado por Lunch Money
Soporte
Para problemas con este servidor MCP, por favor abre un issue en GitHub
Para preguntas sobre la API de Lunch Money, consulta la documentación de la API de Lunch Money
Para preguntas sobre el protocolo MCP, consulta la documentación de MCP
Descargo de responsabilidad: Este es un proyecto comunitario no oficial. No está afiliado ni respaldado por Lunch Money.
Available Tools
15 toolscreate_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_assetsARead-only
List manually managed Lunch Money assets.
Inputs: no named parameters.
get_budgetsARead-only
Get Lunch Money budgets and spending for a date range.
Inputs: start_date (required), end_date (required), currency.
get_categoriesARead-only
List Lunch Money categories in flattened or nested form.
Inputs: format.
get_plaid_accountsARead-only
List Lunch Money Plaid-connected accounts.
Inputs: no named parameters.
get_recurring_itemsARead-only
Get Lunch Money recurring items for the current or specified month range.
Inputs: start_date, end_date, debit_as_negative.
get_tagsARead-only
List all Lunch Money tags.
Inputs: no named parameters.
get_transactionsCRead-only
Get Lunch Money transactions with optional filters.
Inputs: tag_id, recurring_id, plaid_account_id, category_id, +9 more.
get_userARead-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
Scored across 15 tools
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.
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.
With 15 tools, the server covers the core aspects of personal finance management without being overloaded or underdeveloped. Each tool has a clear purpose.
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
Read-only Lunch Money accounts, transactions, categories and budgets. Unofficial connector.
The budget app your AI agent can use. Check budgets and log spending, with no bank logins.
Connect AI agents to bank accounts, transactions, balances, and investments.
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables managing personal finances through the Lunch Money API, including transactions, categories, budgets, and accounts via natural language commands.145MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT