cloudframework-finance-mcp

CloudFramework Finance MCP Server 💰

<div align="center">

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

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

</div>

---

¿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)

🏦 Treasury - Tesorería (5 herramientas)

📊 Tax - Impuestos y Fiscalidad (4 herramientas)

🔒 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

{
  "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 [email protected] 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

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

# 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:

{
  "success": true,
  "user": {
    "name": "Usuario Ejemplo",
    "email": "[email protected]",
    "organizations": [...],
    "privileges": [...]
  },
  "token_expires_in": 3600
}

finance_check

Verifica el estado de la API.

Parámetros: Ninguno

Retorna:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

📞 Soporte

¿Necesitas ayuda?

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Docs: CloudFramework Docs
• 💬 Community: Discord

📄 Licencia

MIT License - Ver LICENSE para más detalles.

🔗 Enlaces Útiles

• npm Package
• GitHub Repository
• CloudFramework
• Model Context Protocol
• Claude Desktop

---

<div align="center">

Hecho con ❤️ por CloudFramework

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

</div>