Finance Manager MCP Server

# 🤖 Finance Manager - Servidor MCP

Servidor basado en el estándar Model Context Protocol (MCP) para permitir que asistentes de Inteligencia Artificial (Antigravity, Claude Desktop, Cursor, etc.) interactúen con la plataforma Finance Manager Suite.

📋 Requisitos Previos

• Node.js 18+ (recomendado v22+)

• Backend de Finance Manager (finance-manager-api) en ejecución.

• Un Personal Access Token (API_TOKEN) generado desde la interfaz web o mediante la API.

Related MCP server: monzo-mcp

⚙️ Configuración

1. Crea el archivo .env en la raíz de este proyecto (o copia .env.example):

API_BASE_URL=http://localhost:3000/api/v1
# Personal Access Token generado en el perfil de usuario (fm_live_...)
API_TOKEN=fm_live_tu_clave_aqui

2. Instala dependencias y compila el proyecto:

npm install
npm run build

🧰 Herramientas (Tools) Disponibles

1. get_account_balances

• Descripción: Consulta la lista de cuentas financieras activas, sus saldos actuales y el total consolidado.

• Argumentos: Ninguno.

• Respuesta: Objeto JSON con totalBalance, totalAccounts y el detalle de cada cuenta (id, name, type, currency, currentBalance, isActive).

2. list_transactions

• Descripción: Consulta el historial de movimientos o transacciones financieras del usuario, permitiendo filtrar por tipo, cuenta y rango de fechas.

• Argumentos opcionales:

  • accountId (string, UUID): Filtrar movimientos de una cuenta específica.

  • type (enum): Tipo de movimiento ("EXPENSE", "INCOME", "TRANSFER").

  • startDate (string, ISO o YYYY-MM-DD): Fecha inicial del rango.

  • endDate (string, ISO o YYYY-MM-DD): Fecha final del rango.

  • limit (number, 1-100): Cantidad máxima de registros (por defecto 20).

  • offset (number): Desplazamiento para paginación.

• Respuesta: Objeto JSON con total, returnedCount y el listado de transacciones formateadas (id, type, amount, currency, date, account, category, destinationAccount, description).

🔌 Cómo conectarlo con Clientes MCP

Antigravity, Cursor o Claude Desktop

En el archivo de configuración claude_desktop_config.json o configuración de MCP:

{
  "mcpServers": {
    "finance-manager": {
      "command": "node",
      "args": [
        "/ruta/absoluta/a/wallet server mcp/dist/index.js"
      ],
      "env": {
        "API_BASE_URL": "http://localhost:3000/api/v1",
        "API_TOKEN": "fm_live_tu_clave_aqui"
      }
    }
  }
}

🧪 Pruebas Locales

• Con MCP Inspector:

npm run inspector

• Smoke test programático:

npm test