You can deploy this model and start earning money today!

fran-herrera-cloudfw/
cloudframework-finance-mcp

mit

Views

No views yet

CloudFramework Finance MCP Server 💰

npm version

License: MIT

Conecta Claude Desktop con tu sistema de gestión financiera CloudFramework

Instalación • Configuración • Características • Ejemplos

¿Qué es esto?

CloudFramework Finance MCP Server es un servidor del Model Context Protocol (MCP) que permite a Claude y otros asistentes de IA acceder directamente a tu sistema de gestión financiera de CloudFramework. Esto significa que puedes:

💬 Preguntar en lenguaje natural sobre tus clientes y facturas
📊 Obtener análisis financieros en tiempo real
🔍 Consultar facturas pendientes de cualquier cliente
🤖 Automatizar tareas administrativas con IA

🌟 Características Principales

14 Herramientas Organizadas en 3 Categorías

💰 Finance - Gestión Financiera (5 herramientas)

Herramienta	Descripción	Caso de Uso
🔐 finance_login	Autenticación con usuario/contraseña	Login seguro con soporte 2FA
✅ finance_check	Verifica salud de la API	Comprobar conectividad y configuración
📋 finance_list_clients	Lista clientes con filtros	"Muéstrame todos los clientes activos"
📊 finance_client_stats	Estadísticas de clientes	"¿Cuántos clientes tenemos?"
💳 finance_outstanding_invoices	Facturas pendientes	"Facturas sin pagar de ACME Corp"

🏦 Treasury - Tesorería (5 herramientas)

Herramienta	Descripción	Caso de Uso
✅ treasury_check	Verifica salud de API tesorería	Estado del servicio de tesorería
💵 treasury_cash_flow	Flujo de caja por períodos	"Flujo de caja mensual del 2025"
🏦 treasury_bank_accounts	Lista cuentas bancarias y saldos	"¿Cuál es nuestro saldo total?"
📈 treasury_projections	Proyecciones futuras	"Proyección para 6 meses"
📑 treasury_movements	Movimientos detallados	"Transacciones de enero a marzo"

📊 Tax - Impuestos y Fiscalidad (4 herramientas)

Herramienta	Descripción	Caso de Uso
✅ tax_check	Verifica salud de API impuestos	Estado del servicio fiscal
🧾 tax_vat_calculation	Cálculo IVA trimestral (303)	"IVA del Q1 2025"
💼 tax_irpf_calculation	Cálculo IRPF (130/111)	"IRPF del segundo trimestre"
📅 tax_upcoming_deadlines	Vencimientos fiscales	"Próximos vencimientos 60 días"

🔒 Autenticación Inteligente

✅ Login dinámico con usuario y contraseña
✅ Refresh automático del token cuando expira
✅ Soporte 2FA (Google Authenticator)
✅ Almacenamiento seguro en memoria durante la sesión
✅ Zero-config: No necesitas renovar tokens manualmente

🚀 Instalación Rápida

Paso 1: Instalar el paquete

npm install -g cloudframework-finance-mcp

Paso 2: Configurar en Claude Desktop

Edita tu archivo de configuración de Claude:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

json

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

Paso 3: ¡Listo! Reinicia Claude Desktop

Ahora puedes conversar con tus datos financieros en lenguaje natural.

💡 Ejemplos de Uso

Autenticación y Setup

👤 Usuario: "Login con mi usuario usuario@ejemplo.com y contraseña MiPassword123"
🤖 Claude: Usa finance_login → ✅ Login exitoso

👤 Usuario: "¿Está funcionando la API de finanzas?"
🤖 Claude: Usa finance_check → ✅ API operativa, versión 2.1.0

Consultas sobre Clientes

👤 Usuario: "¿Cuántos clientes tenemos en total?"
🤖 Claude: Usa finance_client_stats → "Tienes 847 clientes activos"

👤 Usuario: "Muéstrame los primeros 10 clientes activos"
🤖 Claude: Usa finance_list_clients → Lista con detalles completos

👤 Usuario: "Busca clientes que contengan 'Tecnología' en el nombre"
🤖 Claude: Usa finance_list_clients con query="Tecnología"

Gestión de Facturas

👤 Usuario: "¿Qué facturas tiene pendientes ACME Corporation?"
🤖 Claude: Usa finance_outstanding_invoices →
   📄 Factura #2024-001: 1,250.00€ (vencida)
   📄 Factura #2024-089: 3,500.00€ (vence en 5 días)

   Total pendiente: 4,750.00€

👤 Usuario: "Muéstrame todas las facturas pendientes del CIF B12345678"
🤖 Claude: Usa finance_outstanding_invoices con vat_id="B12345678"

Gestión de Tesorería

👤 Usuario: "¿Cuál es el flujo de caja mensual de este año?"
🤖 Claude: Usa treasury_cash_flow con period="monthly"

👤 Usuario: "Muéstrame todas nuestras cuentas bancarias y sus saldos"
🤖 Claude: Usa treasury_bank_accounts →
   🏦 Cuenta BBVA *1234: 45,230.50€
   🏦 Cuenta Santander *5678: 28,150.00€
   💰 Total: 73,380.50€

👤 Usuario: "Dame la proyección de tesorería para los próximos 12 meses"
🤖 Claude: Usa treasury_projections con months_ahead=12

👤 Usuario: "¿Qué movimientos tuvimos en febrero 2025?"
🤖 Claude: Usa treasury_movements con from_date="2025-02-01", to_date="2025-02-28"

Consultas Fiscales

👤 Usuario: "Calcula el IVA del primer trimestre de 2025"
🤖 Claude: Usa tax_vat_calculation →
   📊 Modelo 303 - Q1 2025:
   - IVA Repercutido: 15,200.00€
   - IVA Soportado: 8,350.00€
   - IVA a Ingresar: 6,850.00€

👤 Usuario: "¿Cuánto IRPF debo pagar este trimestre?"
🤖 Claude: Usa tax_irpf_calculation →
   💼 Modelo 130/111:
   - Retenciones ventas: 3,500.00€
   - Retenciones gastos: 1,200.00€
   - A ingresar: 2,300.00€

👤 Usuario: "¿Qué vencimientos fiscales tengo próximamente?"
🤖 Claude: Usa tax_upcoming_deadlines →
   📅 Próximos vencimientos:
   - 20/01/2025: Modelo 303 (IVA Q4)
   - 30/01/2025: Modelo 130 (IRPF Q4)
   - 20/04/2025: Modelo 303 (IVA Q1)

Análisis y Reportes

👤 Usuario: "Dame un resumen de la situación financiera"
🤖 Claude:
   1. Usa finance_client_stats → Obtiene total de clientes
   2. Para cada cliente relevante:
      - Usa finance_outstanding_invoices → Suma facturas pendientes

   📊 Resumen:
   - Clientes activos: 847
   - Facturas pendientes totales: 125,340.00€
   - Cliente con mayor deuda: ACME Corp (15,200.00€)

🎯 Casos de Uso Reales

1. Gestión Diaria de Cuentas por Cobrar

Antes: Entrar al sistema, buscar cliente por cliente, exportar Excel, analizar... Ahora: "¿Qué clientes tienen facturas vencidas de más de 30 días?"

2. Atención al Cliente

Antes: Buscar en múltiples pantallas, copiar datos, redactar email... Ahora: "Genera un email para ACME Corp sobre sus facturas pendientes"

3. Reportes Ejecutivos

Antes: Consultas SQL, hojas de cálculo, gráficos manuales... Ahora: "Dame el top 10 de clientes por facturación pendiente"

4. Auditoría y Compliance

Antes: Exportar datos, revisar manualmente, documentar... Ahora: "Verifica que todos los clientes activos tienen CIF válido"

🔧 Configuración Avanzada

Variables de Entorno

Variable	Descripción	Requerido
`CLOUDFRAMEWORK_API_URL`	URL de la API	✅ Sí
`CLOUDFRAMEWORK_X_WEB_KEY`	Clave de autenticación web	✅ Sí
`CLOUDFRAMEWORK_PLATFORM`	Código de plataforma	✅ Sí
`CLOUDFRAMEWORK_USER`	Usuario por defecto	✅ Sí
`CLOUDFRAMEWORK_X_DS_TOKEN`	Token estático (opcional)	❌ No

Autenticación: Dos Modos

Modo 1: Login Dinámico (Recomendado)

No configures CLOUDFRAMEWORK_X_DS_TOKEN
Usa la herramienta finance_login en Claude
El token se refresca automáticamente
Más seguro y flexible

Modo 2: Token Estático

Configura CLOUDFRAMEWORK_X_DS_TOKEN en las variables de entorno
No necesitas hacer login
El token debe renovarse manualmente cuando expire

🛠️ Desarrollo y Testing

Probar el Servidor

bash

# Clonar el repositorio
git clone https://github.com/CloudFramework-io/cloudframework-finance-mcp.git
cd cloudframework-finance-mcp

# Instalar dependencias
npm install

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

# Ejecutar tests
npm test

# Abrir inspector MCP (interfaz web)
npm run inspector

Inspector MCP

El inspector te permite probar las herramientas sin Claude Desktop:

npm run inspector

Abre http://localhost:6274 en tu navegador.

📚 API Reference

finance_login

Realiza login con usuario y contraseña.

Parámetros:

user (string, required): Email o nombre de usuario
password (string, required): Contraseña
google_authenticator_code (string, optional): Código 2FA

Retorna:

json

{
  "success": true,
  "user": {
    "name": "Usuario Ejemplo",
    "email": "usuario@ejemplo.com",
    "organizations": [...],
    "privileges": [...]
  },
  "token_expires_in": 3600
}

finance_check

Verifica el estado de la API.

Parámetros: Ninguno

Retorna:

json

{
  "status": "ok",
  "version": "2.1.0",
  "platform": "mi_plataforma",
  "endpoints": [...]
}

finance_list_clients

Lista clientes con paginación y filtros.

Parámetros:

limit (number, optional): Máximo de registros (default: 50)
offset (number, optional): Saltar registros (default: 0)
status (string, optional): 'active' | 'inactive' | 'all'
query (string, optional): Buscar por nombre

Retorna:

json

{
  "clients": [
    {
      "id": "uuid",
      "name": "ACME Corporation",
      "vat_id": "B12345678",
      "status": "active",
      ...
    }
  ],
  "total": 847,
  "limit": 50,
  "offset": 0
}

finance_client_stats

Obtiene estadísticas de clientes.

Parámetros: Ninguno

Retorna:

json

{
  "total_clients": 847,
  "active_clients": 820,
  "inactive_clients": 27,
  "distribution": {...}
}

finance_outstanding_invoices

Consulta facturas pendientes de un cliente.

Parámetros:

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

Nota: Se requiere al menos name o vat_id.

Retorna:

json

{
  "client": "ACME Corporation",
  "invoices": [
    {
      "invoice_number": "2024-001",
      "amount": 1250.00,
      "currency": "EUR",
      "due_date": "2024-01-15",
      "days_overdue": 10,
      ...
    }
  ],
  "total_outstanding": 4750.00
}

🔐 Seguridad

✅ Tokens se almacenan solo en memoria (nunca en disco)
✅ Soporte nativo para 2FA
✅ HTTPS obligatorio para todas las conexiones
✅ Sin logs de credenciales
✅ Refresh automático de tokens (no se almacenan expirados)

🤝 Contribuir

Las contribuciones son bienvenidas. Para contribuir:

Fork el repositorio
Crea una rama feature (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add AmazingFeature')
Push a la rama (git push origin feature/AmazingFeature)
Abre un Pull Request

📞 Soporte

¿Necesitas ayuda?

📧 Email: support@cloudframework.io
🐛 Issues: GitHub Issues
📖 Docs: CloudFramework Docs
💬 Community: Discord

📄 Licencia

MIT License - Ver LICENSE para más detalles.

🔗 Enlaces Útiles

Hecho con ❤️ por CloudFramework

Si este proyecto te resulta útil, considera darle una ⭐ en GitHub

fran-herrera-cloudfw/cloudframework-finance-mcp

CloudFramework Finance MCP Server 💰

¿Qué es esto?

🌟 Características Principales

14 Herramientas Organizadas en 3 Categorías

💰 Finance - Gestión Financiera (5 herramientas)

🏦 Treasury - Tesorería (5 herramientas)

📊 Tax - Impuestos y Fiscalidad (4 herramientas)

🔒 Autenticación Inteligente

🚀 Instalación Rápida

Paso 1: Instalar el paquete

Paso 2: Configurar en Claude Desktop

Paso 3: ¡Listo! Reinicia Claude Desktop

💡 Ejemplos de Uso

Autenticación y Setup

Consultas sobre Clientes

Gestión de Facturas

Gestión de Tesorería

Consultas Fiscales

Análisis y Reportes

🎯 Casos de Uso Reales

1. Gestión Diaria de Cuentas por Cobrar

2. Atención al Cliente

3. Reportes Ejecutivos

4. Auditoría y Compliance

🔧 Configuración Avanzada

Variables de Entorno

Autenticación: Dos Modos

Modo 1: Login Dinámico (Recomendado)

Modo 2: Token Estático

🛠️ Desarrollo y Testing

Probar el Servidor

Inspector MCP

📚 API Reference

finance_login

finance_check

finance_list_clients

finance_client_stats

finance_outstanding_invoices

🔐 Seguridad

🤝 Contribuir

📞 Soporte

📄 Licencia

🔗 Enlaces Útiles

fran-herrera-cloudfw/
cloudframework-finance-mcp