CloudFramework Finance MCP Server

Un servidor MCP (Model Context Protocol) para acceder a la API de Finance de CloudFramework, implementado en Node.js. Compatible con Claude Desktop y cualquier cliente MCP.

Características

Este servidor MCP proporciona 14 herramientas (tools) organizadas en 3 categorías:

💰 Finance (5 herramientas)

1. finance_login - Login con usuario/contraseña (con soporte 2FA opcional)
2. finance_check - Verifica la salud y conectividad de la API
3. finance_list_clients - Lista clientes con paginación y filtros
4. finance_client_stats - Obtiene estadísticas de clientes
5. finance_outstanding_invoices - Consulta facturas pendientes de un cliente

🏦 Treasury / Tesorería (5 herramientas)

6. treasury_check - Verifica la salud de la API de tesorería
7. treasury_cash_flow - Obtiene flujo de caja (ingresos, gastos, neto) por períodos
8. treasury_bank_accounts - Lista cuentas bancarias con saldos
9. treasury_projections - Proyecciones de tesorería para meses futuros
10. treasury_movements - Movimientos detallados de tesorería con filtros

📊 Tax / Impuestos (4 herramientas)

11. tax_check - Verifica la salud de la API de impuestos
12. tax_vat_calculation - Cálculo de IVA por trimestre (Modelo 303)
13. tax_irpf_calculation - Cálculo de IRPF por trimestre (Modelo 130/111)
14. tax_upcoming_deadlines - Próximos vencimientos fiscales

Autenticación Dinámica

El servidor ahora soporta autenticación dinámica con las siguientes características:

• ✓ Login con usuario y contraseña mediante la tool finance_login
• ✓ Soporte para autenticación de dos factores (2FA/Google Authenticator)
• ✓ Refresh automático del token cuando expira
• ✓ Almacenamiento seguro del token en memoria durante la sesión
• ✓ Opción de usar token estático en .env o login dinámico

Tabla de Contenidos

• Características
• Instalación
• Configuración
• Uso
• Herramientas Disponibles
• Ejemplos
• Solución de Problemas
• Contribuir
• Licencia

Requisitos previos

• Node.js >= 18.0.0
• npm (incluido con Node.js)
• Cuenta de CloudFramework con acceso a Finance API

Instalación

Opción 1: Instalar desde npm (Recomendado)

npm install -g cloudframework-finance-mcp

Opción 2: Instalar desde código fuente

git clone https://github.com/CloudFramework-io/cloudframework-finance-mcp.git
cd cloudframework-finance-mcp
npm install

Configuración

1. Configurar las credenciales

cp .env.example .env
# Edita .env con tus credenciales

Configura las siguientes variables en el archivo .env:

CLOUDFRAMEWORK_API_URL=https://api.cloudframework.io
CLOUDFRAMEWORK_X_WEB_KEY=tu_web_key
CLOUDFRAMEWORK_X_DS_TOKEN=tu_ds_token  # Opcional si usas finance_login
CLOUDFRAMEWORK_PLATFORM=tu_platform_code
CLOUDFRAMEWORK_USER=tu_email_o_uuid

Nota: El CLOUDFRAMEWORK_X_DS_TOKEN ahora es opcional. Tienes dos opciones:

• Opción 1 (Recomendada): Omitir el token y usar la tool finance_login con tu usuario y contraseña
• Opción 2 (Tradicional): Configurar un token estático en .env

2. Probar la configuración (solo si instalaste desde código fuente)

Antes de usar el servidor en Claude Desktop, prueba que todo funciona correctamente:

# Opción 1: Script de prueba automático (recomendado)
npm test
# O directamente:
./test_server.js

# Opción 2: Ejecutar el inspector MCP
npm run inspector
# O directamente:
./run_inspector.sh

# Opción 3: Ejecutar el servidor directamente
npm start
# O directamente:
./run_server.sh

El script de prueba verificará:

• ✓ Configuración de variables de entorno
• ✓ Conectividad con la API de CloudFramework
• ✓ Disponibilidad del servidor MCP
• ✓ Herramientas disponibles

Uso

Modo local / desarrollo

Probar con el Inspector MCP

El inspector MCP proporciona una interfaz web para probar las herramientas:

npm run inspector
# O:
./run_inspector.sh

Esto abrirá automáticamente http://localhost:6274 en tu navegador donde podrás:

• Ver las herramientas disponibles
• Probar cada herramienta con diferentes parámetros
• Ver las respuestas de la API en tiempo real

Ejecutar el servidor directamente

npm start
# O:
./run_server.sh

Configuración en Claude Desktop

Ubicación del archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Si instalaste desde npm (global):

{
  "mcpServers": {
    "cloudframework-finance": {
      "command": "cloudframework-finance-mcp",
      "env": {
        "CLOUDFRAMEWORK_API_URL": "https://api.cloudframework.io",
        "CLOUDFRAMEWORK_X_WEB_KEY": "tu_web_key",
        "CLOUDFRAMEWORK_X_DS_TOKEN": "tu_ds_token_opcional",
        "CLOUDFRAMEWORK_PLATFORM": "tu_platform",
        "CLOUDFRAMEWORK_USER": "tu_usuario"
      }
    }
  }
}

Si instalaste desde código fuente:

{
  "mcpServers": {
    "cloudframework-finance": {
      "command": "node",
      "args": [
        "/ruta/completa/al/proyecto/server.js"
      ],
      "env": {
        "CLOUDFRAMEWORK_API_URL": "https://api.cloudframework.io",
        "CLOUDFRAMEWORK_X_WEB_KEY": "tu_web_key",
        "CLOUDFRAMEWORK_X_DS_TOKEN": "tu_ds_token_opcional",
        "CLOUDFRAMEWORK_PLATFORM": "tu_platform",
        "CLOUDFRAMEWORK_USER": "tu_usuario"
      }
    }
  }
}

Importante:

• Usa la ruta completa al archivo server.js
• Configura las variables de entorno con tus credenciales reales
• Después de guardar el archivo, reinicia Claude Desktop

Ejemplo de configuración real:

{
  "mcpServers": {
    "cloudframework-finance": {
      "command": "node",
      "args": [
        "/Users/tu_usuario/proyectos/claude-node-finance/server.js"
      ],
      "env": {
        "CLOUDFRAMEWORK_API_URL": "https://api.cloudframework.io",
        "CLOUDFRAMEWORK_X_WEB_KEY": "tu_web_key_aqui",
        "CLOUDFRAMEWORK_X_DS_TOKEN": "tu_token_opcional",
        "CLOUDFRAMEWORK_PLATFORM": "mi_plataforma",
        "CLOUDFRAMEWORK_USER": "[email protected]"
      }
    }
  }
}

Herramientas disponibles

finance_login

NUEVA: Realiza login con usuario y contraseña para obtener un token dinámico.

Parámetros:

• user (string, requerido): Email o nombre de usuario
• password (string, requerido): Contraseña del usuario
• google_authenticator_code (string, opcional): Código 2FA si tienes autenticación de dos factores

Características:

• El token se almacena automáticamente en memoria durante la sesión
• El servidor refresca el token automáticamente cuando expira
• Las credenciales se guardan de forma segura para el auto-refresh
• No es necesario volver a hacer login manualmente

Retorna:

• Confirmación de login exitoso
• Información del usuario (nombre, email, organizaciones, privilegios)
• Tiempo de expiración del token

Ejemplo de uso en Claude:

"Login con usuario [email protected] y contraseña mi_password"
→ Usa finance_login

"Login con usuario [email protected], contraseña mi_password y código 2FA 123456"
→ Usa finance_login con google_authenticator_code

finance_check

Verifica la salud de la API y devuelve información de configuración.

Uso:

// No requiere parámetros

Retorna:

• Versión de la API
• Información de la plataforma
• Estado de conexión (DS, DB)
• Endpoints disponibles

finance_list_clients

Lista clientes con opciones de paginación y filtrado.

Parámetros:

• limit (number, opcional): Número máximo de registros (default: 50)
• offset (number, opcional): Número de registros a saltar (default: 0)
• status (string, opcional): Filtrar por estado: 'active', 'inactive', 'all'
• query (string, opcional): Buscar por nombre de cliente

Retorna: Lista de clientes con detalles completos.

finance_client_stats

Obtiene estadísticas agregadas de clientes.

Uso:

// No requiere parámetros

Retorna: Métricas y estadísticas sobre la distribución de clientes.

finance_outstanding_invoices

Consulta facturas pendientes de pago de un cliente específico.

Parámetros:

• name (string, opcional): Nombre del cliente (búsqueda parcial)
• vat_id (string, opcional): CIF del cliente

Nota: Se debe proporcionar al menos name o vat_id.

Retorna: Lista de facturas pendientes con montos, fechas y detalles.

treasury_check

Verifica el estado de la API de Tesorería.

Uso:

// No requiere parámetros

Retorna: Versión de la API, endpoints disponibles y estado de conexión.

treasury_cash_flow

Obtiene datos de flujo de caja mostrando ingresos, gastos y flujo neto.

Parámetros:

• period (string, opcional): Período de agrupación: 'daily', 'weekly', 'monthly' (default: monthly)
• from_date (string, opcional): Fecha inicio en formato YYYY-MM-DD
• to_date (string, opcional): Fecha fin en formato YYYY-MM-DD

Retorna: Datos de flujo de caja agrupados por período con ingresos, gastos y balance neto.

treasury_bank_accounts

Lista todas las cuentas bancarias de la organización.

Uso:

// No requiere parámetros

Retorna: Lista de cuentas bancarias con detalles, saldos e información de estado.

treasury_projections

Obtiene proyecciones de tesorería para meses futuros.

Parámetros:

• months_ahead (number, opcional): Número de meses a proyectar (default: 6)

Retorna: Proyecciones de ingresos, gastos y balance para los próximos meses.

treasury_movements

Obtiene movimientos detallados de tesorería con filtros opcionales.

Parámetros:

• from_date (string, opcional): Fecha inicio en formato YYYY-MM-DD
• to_date (string, opcional): Fecha fin en formato YYYY-MM-DD
• category (string, opcional): Filtrar por categoría de transacción
• subcategory (string, opcional): Filtrar por subcategoría

Retorna: Registros individuales de transacciones con detalles completos.

tax_check

Verifica el estado de la API de Impuestos.

Uso:

// No requiere parámetros

Retorna: Versión de la API, endpoints disponibles y estado de conexión.

tax_vat_calculation

Calcula el IVA para un trimestre y año específicos (Modelo 303).

Parámetros:

• year (number, requerido): Año para el cálculo (ej. 2025)
• quarter (number, requerido): Número de trimestre: 1, 2, 3 o 4

Retorna: IVA repercutido, IVA soportado y IVA neto a pagar o devolver.

tax_irpf_calculation

Calcula el IRPF para un trimestre y año específicos (Modelo 130/111).

Parámetros:

• year (number, requerido): Año para el cálculo (ej. 2025)
• quarter (number, requerido): Número de trimestre: 1, 2, 3 o 4

Retorna: Retenciones de ventas, retenciones de gastos e información del modelo 130/111.

tax_upcoming_deadlines

Obtiene los próximos vencimientos fiscales.

Parámetros:

• days_ahead (number, opcional): Días hacia adelante para buscar vencimientos (default: 120)

Retorna: Lista de obligaciones fiscales con fechas de vencimiento, tipos y descripciones.

Ejemplos de uso en Claude

Una vez configurado, puedes usar el servidor en Claude Desktop:

Con autenticación dinámica (Recomendado)

"Login con mi usuario [email protected] y contraseña MiPassword123"
→ Usa finance_login (el token se guarda automáticamente)

"Muéstrame el estado de la API de finanzas"
→ Usa finance_check (usa el token de la sesión)

"Lista los primeros 20 clientes activos"
→ Usa finance_list_clients con limit=20, status="active"

"¿Cuántos clientes tenemos en total?"
→ Usa finance_client_stats

"Muestra las facturas pendientes del cliente BUSINESS MANAGEMENT"
→ Usa finance_outstanding_invoices con name="BUSINESS MANAGEMENT"

Consultas de Tesorería

"Muéstrame el flujo de caja mensual del último año"
→ Usa treasury_cash_flow con period="monthly"

"¿Qué cuentas bancarias tenemos y cuál es el saldo total?"
→ Usa treasury_bank_accounts

"Dame las proyecciones de tesorería para los próximos 12 meses"
→ Usa treasury_projections con months_ahead=12

"Muéstrame los movimientos de tesorería de enero a marzo 2025"
→ Usa treasury_movements con from_date="2025-01-01", to_date="2025-03-31"

Consultas Fiscales/Impuestos

"Calcula el IVA del primer trimestre de 2025"
→ Usa tax_vat_calculation con year=2025, quarter=1

"¿Cuánto IRPF tengo que pagar este trimestre?"
→ Usa tax_irpf_calculation con año y trimestre actual

"¿Qué vencimientos fiscales tengo en los próximos 60 días?"
→ Usa tax_upcoming_deadlines con days_ahead=60

Nota: Una vez hecho el login, no es necesario volver a autenticarse. El token se refresca automáticamente cuando expira.

Con token estático en .env

"Muéstrame el estado de la API de finanzas"
→ Usa finance_check

"Lista los primeros 20 clientes activos"
→ Usa finance_list_clients con limit=20, status="active"

Solución de problemas

El servidor no aparece en Claude Desktop

1. Verifica que Claude Desktop esté completamente cerrado y reiniciado

   # En macOS, fuerza el cierre
   pkill -9 Claude

2. Comprueba la configuración con el script de pruebas

   npm test

3. Verifica que la ruta en claude_desktop_config.json sea absoluta

   • ❌ Incorrecto: "args": ["server.js"]
   • ✓ Correcto: "args": ["/Users/tu_usuario/proyectos/claude-node-finance/server.js"]

4. Revisa los logs de Claude Desktop

   • macOS: ~/Library/Logs/Claude/

Error al conectar con la API

1. Verifica tus credenciales en .env
2. Ejecuta el test: npm test
3. Comprueba que la API esté accesible: curl https://api.cloudframework.io

Problema con las dependencias

# Limpiar e instalar de nuevo
rm -rf node_modules package-lock.json
npm install

Error de módulos ES

Si ves errores relacionados con import, asegúrate de que:

• El archivo package.json tiene "type": "module"
• Estás usando Node.js >= 18.0.0

Verifica tu versión de Node.js:

node --version

Estructura del proyecto

claude-node-finance/
├── server.js              # Servidor MCP principal
├── test_server.js         # Script de validación y pruebas
├── run_server.sh          # Script para ejecutar el servidor
├── run_inspector.sh       # Script para ejecutar el inspector MCP
├── package.json           # Dependencias y scripts de Node.js
├── .env.example          # Ejemplo de configuración
├── .env                  # Tu configuración (no commitear)
├── .gitignore            # Archivos a ignorar en git
├── node_modules/         # Dependencias (generado por npm)
└── README.md             # Esta documentación

Dependencias

• @modelcontextprotocol/sdk ^1.0.4 - SDK oficial de MCP
• dotenv ^16.4.5 - Carga variables de entorno
• node-fetch ^3.3.2 - Cliente HTTP para peticiones a la API

Diferencias con la versión Python

Esta es una implementación equivalente del servidor MCP de CloudFramework Finance, pero utilizando Node.js en lugar de Python. Las principales diferencias técnicas son:

• Usa @modelcontextprotocol/sdk en lugar de fastmcp
• Usa node-fetch en lugar de httpx
• Sintaxis JavaScript/ES6 en lugar de Python
• Sistema de módulos ES en lugar de imports de Python

Funcionalidad: Ambas versiones proporcionan exactamente las mismas herramientas y funcionalidades.

Scripts disponibles

• npm start - Inicia el servidor MCP
• npm test - Ejecuta las pruebas de configuración
• npm run inspector - Abre el inspector MCP en el navegador

Contribuir

Las contribuciones son bienvenidas. Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

Soporte

Si encuentras algún problema o tienes preguntas:

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentación: Hugging Face

Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

Enlaces

• Documentación de CloudFramework
• Model Context Protocol
• Claude Desktop