Servidor MCP de Money Lover

Implementación en Node.js de un servidor del Protocolo de Contexto de Modelo (MCP) que envuelve la API REST no oficial de Money Lover. El servidor expone 27 herramientas MCP que cubren autenticación, carteras, categorías, transacciones, eventos, deudas y configuración estática, permitiendo a los asistentes de IA o clientes compatibles con MCP consultar y gestionar datos de finanzas personales.

Características

• Autenticación automática mediante variables de entorno EMAIL/PASSWORD: no se requiere pasar tokens para la mayoría de las herramientas.

• 23 herramientas de lectura que cubren información de usuario, carteras, categorías, transacciones, eventos, deudas, iconos, proveedores y configuración estática.

• 4 herramientas de escritura: crear, actualizar y eliminar transacciones, carteras y categorías.

• Las respuestas grandes se truncan automáticamente para mantener el contexto del LLM manejable (configurable mediante el parámetro limit).

• Servidor basado en Stdio compatible con Claude Code, Claude Desktop, Cursor y cualquier host MCP.

• Caché de tokens por correo electrónico en ~/.moneylover-mcp/ con actualización automática en caso de errores de autenticación.

Related MCP server: YNAB Assistant

Requisitos previos

• Node.js 22 o superior.

• Credenciales de cuenta de Money Lover.

Instalación

npm install

Uso

Inicie el servidor MCP a través de stdio:

npm start

Configuración con alcance de proyecto (Claude Code)

Añada .mcp.json en la raíz del proyecto:

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "node",
      "args": ["/absolute/path/to/moneylover-mcp/src/server.js"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

Y actívelo en .claude/settings.json:

{ "enabledMcpjsonServers": ["mcp-moneylover"] }

Configuración global (Claude Desktop / Cursor)

{
  "mcpServers": {
    "mcp-moneylover": {
      "command": "npx",
      "args": ["@ferdhika31/moneylover-mcp@latest"],
      "env": {
        "EMAIL": "your@email.com",
        "PASSWORD": "your-password"
      }
    }
  }
}

Herramientas disponibles

Autenticación

Usuario

Carteras

Categorías

Transacciones

Estática y Configuración

Ejemplos de uso de herramientas

Ejemplos de prompts, campos requeridos vs opcionales, advertencias y patrones comunes de varios pasos para cada herramienta: docs/examples.md.

Uso de la biblioteca

import { MoneyloverClient } from './src/moneyloverClient.js';

const token = await MoneyloverClient.getToken(email, password);
const client = new MoneyloverClient(token);

const wallets = await client.getWallets();
const txns = await client.getTransactions(walletId, '2026-01-01', '2026-04-30');
await client.addTransaction({ walletId, categoryId, amount: '50000', date: '2026-04-18' });
await client.editTransaction('txn-id', { amount: '60000', note: 'updated' });
await client.deleteTransaction('txn-id');

Pruebas

Pruebas unitarias

Pruebas unitarias simuladas: no se requieren llamadas a la API en vivo:

npm test

Pruebas de integración (mcp-tester)

mcp-tester es un marco de pruebas MCP basado en agentes ReAct. Inicia el servidor, dirige a un LLM para llamar a herramientas en respuesta a prompts en lenguaje natural y verifica que se llamaron las herramientas correctas con los argumentos correctos.

Instalar

pipx install --index-url https://pypi.artifacts.furycloud.io/simple/ mcp-tester

Configurar

tests/mcp-tester/mcps.json: apunte al servidor local con sus credenciales:

{
  "mcp-moneylover": {
    "command": "node",
    "args": ["/absolute/path/to/src/server.js"],
    "transport": "stdio",
    "env": {
      "EMAIL": "your@email.com",
      "PASSWORD": "your-password"
    }
  }
}

Ejecutar

mcp-tester run-tests \
  --mcps tests/mcp-tester/mcps.json \
  --model gpt-4o-mini \
  --concurrent-runs 3 \
  tests/mcp-tester/read-tools.yaml

Resultados

tests/mcp-tester/read-tools.yaml contiene 25 pruebas de integración que cubren cada herramienta de lectura:

total 25, success 25, failures 0

Decisiones clave que hacen que las pruebas sean estables:

• Sin parámetro de token en herramientas de lectura: exponer un campo token opcional causaba que los LLMs inyectaran IDs de cartera en él. El servidor se autentica automáticamente mediante variables de entorno.

• Truncamiento de respuesta: varios endpoints devuelven cientos de miles de registros de la base de datos compartida de MoneyLover. Las herramientas aceptan un parámetro limit (predeterminado: 20–100) para mantener el contexto del LLM bajo control.

• Envoltura de diccionario: todas las respuestas de las herramientas devuelven un objeto JSON (nunca un array desnudo) para que pase la validación del marco MCP.

Pruebas de herramientas de escritura (mcp-tester)

Tres archivos YAML adicionales prueban el ciclo de vida CRUD completo para carteras, categorías y transacciones en tres fases secuenciales. Cada fase ejecuta los tres tipos de recursos simultáneamente.

Ejecute las fases en orden: cada una depende de la anterior:

# Phase 1: Create
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-create.yaml

# Phase 2: Edit (after Phase 1 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-edit.yaml

# Phase 3: Delete (after Phase 2 passes)
mcp-tester run-tests --mcps tests/mcp-tester/mcps.json --model gpt-4o-mini --concurrent-runs 3 tests/mcp-tester/write-delete.yaml

Resultados en las tres fases:

Phase 1 (Create): total 3, success 3, failures 0
Phase 2 (Edit):   total 3, success 3, failures 0
Phase 3 (Delete): total 3, success 3, failures 0

Decisiones de diseño clave para las pruebas de herramientas de escritura:

• Descubrimiento antes de la mutación: las pruebas de edición y eliminación instruyen al agente para que primero llame a una herramienta de lectura (get_wallets, get_categories, get_transactions) para localizar el objetivo por nombre, y luego llame a la herramienta de mutación. Esto refleja el comportamiento del agente en el mundo real donde los IDs no se conocen de antemano.

• args: !any para aserciones de herramientas de escritura: el marco requiere una coincidencia exacta de argumentos. Las herramientas de escritura aceptan campos opcionales (icon, with, etc.) que el agente puede incluir a su discreción; !any verifica que la herramienta fue llamada y tuvo éxito sin fallar por extras inofensivos. Las aserciones de herramientas de lectura pueden usar coincidencias exactas de argumentos porque sus esquemas no tienen campos opcionales que el LLM añadiría espontáneamente.

• Identificadores predecibles: los recursos de prueba usan nombres fijos (MCP-Test-Wallet, MCP-Test-Category) y una nota fija (MCP test transaction) para que el agente pueda localizarlos por nombre durante las fases de edición y eliminación sin necesidad de compartir estado entre ejecuciones de prueba.

• Aserciones de edición de carga útil completa: edit_transaction es una operación de reemplazo completo; el prompt de prueba instruye al agente para que primero obtenga la transacción existente (get_transactions) y traslade todos los valores de campo actuales, cambiando solo la nota. Esto valida el razonamiento de varios pasos que requiere la descripción de la herramienta.

Notas de seguridad

• Nunca confirme credenciales o tokens reales.

• Los tokens en caché viven en ~/.moneylover-mcp/ restringidos al usuario actual.

• Elimine ese directorio para revocar todas las sesiones en caché.