RapidInvoice MCP Server

🚀 Servidor MCP para generar facturas profesionales desde Claude Desktop

Este servidor MCP (Model Context Protocol) permite generar facturas profesionales directamente desde Claude Desktop, integrándose con la plataforma RapidInvoice y almacenándolas en Supabase.

🌟 Características

• ✅ Generación automática de facturas con cálculo de totales e IVA

• ✅ Enlaces públicos para compartir facturas con clientes

• ✅ Integración completa con Claude Desktop

• ✅ Base de datos Supabase para almacenamiento persistente

• ✅ Validación robusta de datos con Zod

• ✅ Soporte multi-moneda (EUR por defecto)

• ✅ Control de límites de facturación por usuario

• ✅ Tokens públicos únicos con fecha de expiración configurable

🔑 Obtener User ID

Para usar este servidor MCP necesitas tu User ID de RapidInvoice:

1. Visita: www.rapidinvoice.eu

2. Inicia sesión con tu cuenta

3. Localiza tu User ID en el panel de usuario

4. Formato: user_ seguido de caracteres alfanuméricos (ej: user_32kVAR4EMgF4UYPV2oSVcBu4qV0)

5. Usa este User ID como tu api_key en la configuración

⚠️ Importante: Mantén tu User ID seguro, ya que permite generar facturas en tu cuenta.

• Node.js >= 18.0.0

• Claude Desktop instalado

• Cuenta de RapidInvoice con API Key válida

• Base de datos Supabase configurada con Prisma

📋 Requisitos Previos

🚀 Instalación

💡 Nota: Este servidor puede ejecutarse localmente para desarrollo o desplegarse en Oracle Cloud para producción.

git clone https://github.com/j03rul4nd/rapidinvoice-mcp-server.git
cd rapidinvoice-mcp-server

1. Clonar el repositorio

npm install

2. Instalar dependencias

1. Ve a www.rapidinvoice.eu

2. Inicia sesión en tu cuenta

3. En tu panel de usuario, encontrarás tu User ID (formato: user_xxxxxxxxxxxxxxxxxx)

4. Copia este User ID para usarlo como API Key

4. Configurar variables de entorno

Crea un archivo .env en la raíz del proyecto:

DATABASE_URL="postgresql://usuario:password@host:5432/database?schema=public"
API_KEY=user_xxxxxxxxxxxxxxxxxx

5. Configurar Claude Desktop

Opción A: Servidor Local (Desarrollo)

Edita el archivo de configuración de Claude Desktop:

Windows: %APPDATA%/Claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "rapidinvoice-mcp-server": {
      "command": "node",
      "args": [
        "/ruta/completa/al/proyecto/server.js",
        "--api_key=user_xxxxxxxxxxxxxxxxxx"
      ],
      "cwd": "/ruta/completa/al/proyecto"
    }
  }
}

Opción B: Servidor en Oracle Cloud (Producción)

{
  "mcpServers": {
    "rapidinvoice-mcp-server": {
      "command": "ssh",
      "args": [
        "usuario@servidor-oracle.com",
        "cd /ruta/del/servidor && node server.js --api_key=user_xxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

6. Reiniciar Claude Desktop

📖 Uso

Una vez configurado, puedes generar facturas directamente desde Claude Desktop usando prompts como:

Genera una factura para:

**Cliente:**
- Nombre: María García López  
- Email: maria.garcia@email.com
- Dirección: Calle Mayor 123, Madrid, 28001, España

**Servicios:**
- Consultoría web: 10 horas × 50€
- Desarrollo landing: 1 × 800€
- Hosting anual: 1 × 120€

**Configuración:**
- Vencimiento: 2025-10-19
- IVA: 21%
- Enlace público: 60 días

🛠️ Scripts Disponibles

# Iniciar el servidor
npm start

# Desarrollo con API key
npm run dev

# Testing con inspector MCP
npm test

# Testing con API key
npm run test-with-key

📊 Estructura del Proyecto

rapidinvoice-mcp-server/
├── server.js              # Servidor MCP principal
├── package.json           # Configuración del proyecto
├── .env                   # Variables de entorno (no incluir en git)
├── .env.example           # Ejemplo de variables de entorno
├── .gitignore            # Archivos ignorados por git
├── README.md             # Este archivo
├── prisma/               # Configuración de Prisma
│   └── schema.prisma     # Esquema de base de datos
└── logs/                 # Logs del servidor (generados automáticamente)
    └── mcp-server.log    # Log de operaciones

🔧 Herramientas Disponibles

generar_factura

Genera una nueva factura y devuelve el enlace público.

Parámetros obligatorios:

• clientName: Nombre del cliente

• clientEmail: Email del cliente

• clientAddress: Dirección del cliente

• clientCity: Ciudad del cliente

• clientPostalCode: Código postal

• clientCountry: País del cliente

• dueDate: Fecha de vencimiento (YYYY-MM-DD)

• items: Array de productos/servicios

Parámetros opcionales:

• invoiceNumber: Número de factura personalizado

• date: Fecha de emisión (por defecto: hoy)

• currency: Moneda (por defecto: EUR)

• language: Idioma (por defecto: es)

• notes: Notas adicionales

• makePublic: Hacer público (por defecto: true)

• publicExpirationDays: Días de expiración (por defecto: 30)

🔒 Seguridad

• Las API keys se pasan como parámetros de línea de comandos

• Los tokens públicos son únicos y tienen fecha de expiración

• Validación estricta de todos los datos de entrada

• Control de límites de facturación por usuario

📝 Logging

Los logs se almacenan en logs/mcp-server.log e incluyen:

• Conexiones exitosas a la base de datos

• Facturas generadas con éxito

• Errores y excepciones

• Información de debug

🤝 Contribuir

1. Fork el proyecto

2. Crea una rama para tu feature (git checkout -b feature/nueva-funcionalidad)

3. Commit tus cambios (git commit -am 'Añadir nueva funcionalidad')

4. Push a la rama (git push origin feature/nueva-funcionalidad)

5. Abre un Pull Request

📄 Licencia

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

👨‍💻 Autor

Joel Benítez Donari

• Website: RapidInvoice

• GitHub: @j03rul4nd

🐛 Reportar Issues

Si encuentras algún bug o tienes una sugerencia, por favor abre un issue.

🔗 Enlaces Relacionados

• RapidInvoice - Plataforma de facturación

• Model Context Protocol - Documentación oficial MCP

• Claude Desktop - Cliente oficial de Anthropic

• Prisma - ORM para base de datos

• Supabase - Backend as a Service

⭐ ¡No olvides dar una estrella al repo si te resulta útil!