Holded集成服务

holded-mcp-server

Servidor MCP (Model Context Protocol) para integrar Holded con Claude Code, Claude Desktop y cualquier cliente MCP compatible.

Expone 50 herramientas (tools) que cubren: facturas de venta, facturas de compra, presupuestos, contactos y productos de la API de facturación de Holded, el módulo CRM (leads y embudos de venta) y el módulo Equipo (empleados y control horario).

Desarrollado por APOGEA Consultores (Agustí Jardí).

Requisitos previos

• Node.js >= 18 (descargar)
• Git (descargar)
• API Key de Holded (ver Cómo obtener la API Key)
• Claude Code o Claude Desktop instalado

Instalación

Opción A — Instalador .exe (recomendado, sin requisitos)

Descarga holded-mcp.exe (o genéralo con npm run build:exe) y haz doble clic:

1. Pide la API key de Holded (y la valida en vivo contra la API).
2. Instala el ejecutable en C:\Holded-MCP\ (no necesita Node.js: lo lleva embebido).
3. Te deja elegir dónde registrarlo — Claude Code (~/.claude.json), Claude Desktop (detecta las 3 variantes de Windows: instalador clásico, Local y Microsoft Store) o todos —, con backup previo de cada config y escritura atómica.
4. Se da de alta en "Agregar o quitar programas" para desinstalarlo desde Windows.

Reinicia Claude (Desktop: salir del todo desde la bandeja del sistema) y listo.

El mismo .exe es también el desinstalador: doble clic → opción [3] Desinstalar (o desde "Agregar o quitar programas"). Elimina las entradas de las configs de Claude (con backup), el registro de Windows y la carpeta C:\Holded-MCP. Si pierdes el exe, consulta MANUAL_UNINSTALL.md.

Otros comandos del exe: holded-mcp.exe status (dónde está registrado), register, install, uninstall.

Opción B — Manual con Node.js

# 1. Clonar el repositorio
git clone https://github.com/JardiMargalefAgusti/holded-mcp-server.git
cd holded-mcp-server

# 2. Instalar dependencias
npm install

# 3. Compilar
npm run build

Tras estos pasos, el servidor estará listo en build/index.js.

Configuración

Con Claude Code

Añade la siguiente entrada al fichero .mcp.json de tu proyecto (o a ~/.claude.json para que esté disponible en todos los proyectos):

{
  "mcpServers": {
    "holded": {
      "command": "node",
      "args": ["/ruta/absoluta/a/holded-mcp-server/build/index.js"],
      "env": {
        "HOLDED_API_KEY": "tu_api_key_aqui"
      }
    }
  }
}

Windows: usa rutas con doble barra \\, por ejemplo: "args": ["C:\\Users\\usuario\\holded-mcp-server\\build\\index.js"]

Reinicia Claude Code y comprueba que funciona con el comando /mcp — el servidor holded debe aparecer como connected.

Con Claude Desktop

Edita el fichero de configuración de Claude Desktop:

Añade dentro de "mcpServers":

"holded": {
  "command": "node",
  "args": ["/ruta/absoluta/a/holded-mcp-server/build/index.js"],
  "env": {
    "HOLDED_API_KEY": "tu_api_key_aqui"
  }
}

Reinicia Claude Desktop para que detecte el nuevo servidor.

Tools disponibles (50)

Contactos (4)

Productos (2)

Facturas de Venta (8)

Facturas de Compra (7)

Presupuestos (6)

CRM — Embudos (5)

CRM — Leads (12)

Equipo (6)

Nota sobre vacaciones: la API pública de Holded no expone la gestión de ausencias/vacaciones (solo desde la interfaz web). La ficha del empleado sí incluye su política de ausencias (timeOffPolicyId) y quién se las supervisa (timeOffSupervisors).

Ejemplos de uso

Una vez conectado, puedes hacer peticiones en lenguaje natural a Claude:

• "Busca el contacto Empresa ABC en Holded"
• "Lista mis facturas de venta del último mes"
• "Crea una factura para el cliente X con 2 horas de consultoría a 80 EUR/hora"
• "Registra el pago de la factura F-2026-001 por 4.235 EUR"
• "Envía el presupuesto P-2026-003 al email cliente@empresa.com"
• "Muéstrame las facturas de compra pendientes de pago"
• "Crea un lead para Empresa ABC en el embudo Comercial y añade una nota con lo hablado hoy"
• "Mueve el lead de Empresa XYZ a la etapa Negociación"

Cómo obtener la API Key de Holded

1. Inicia sesión en Holded
2. Ve a Configuración (icono engranaje) > Desarrolladores
3. Haz click en Nueva API Key
4. Copia la clave generada y úsala como HOLDED_API_KEY

Seguridad: La API key da acceso a los datos de facturación de tu cuenta de Holded. Guárdala siempre como variable de entorno y nunca la incluyas directamente en el código fuente.

Desarrollo

npm run dev        # Compilación en modo watch (detecta cambios automáticamente)
npm run build      # Compilación completa
npm test           # Tests del parcheador de configs de Claude (node:test)
npm run build:exe  # Genera dist-exe/holded-mcp.exe (tsc + esbuild + @yao-pkg/pkg)

El .exe es autocontenido (Node 22 embebido, ~80 MB) y actúa como instalador, desinstalador y servidor MCP según cómo se invoque: doble clic → menú; serve (lo que lanza Claude) → servidor por stdio. El binario se instala con nombre versionado (holded-mcp-1.1.0.exe) para que las actualizaciones nunca choquen con un exe en uso por Claude.

Estructura del proyecto

src/
├── index.ts              # Entry point para Node (llama a runServer)
├── server.ts             # runServer(): McpServer + registro de tools + stdio
├── main.ts               # Entry point del .exe (instalador/desinstalador/serve)
├── claude-config.ts      # Parcheo de configs de Claude (testeado)
├── claude-config.test.ts # Tests del parcheador (npm test)
├── holded-client.ts      # Cliente HTTP para la API de Holded (retry 429)
├── types/
│   └── holded.ts         # Interfaces TypeScript
└── tools/
    ├── contacts.ts       # 4 tools de contactos
    ├── products.ts       # 2 tools de productos
    ├── invoices.ts       # 8 tools de facturas de venta
    ├── purchases.ts      # 7 tools de facturas de compra
    ├── estimates.ts      # 6 tools de presupuestos
    ├── crm.ts            # 17 tools de CRM (leads y embudos)
    └── team.ts           # 6 tools de equipo (empleados y fichajes)

Stack técnico

• Runtime: Node.js >= 18
• Lenguaje: TypeScript (strict mode)
• SDK: @modelcontextprotocol/sdk v1.27+
• Validación: zod v4
• Transporte: stdio (JSON-RPC)
• HTTP: fetch nativo (Node 18+)

Solución de problemas

Contribuir

Las contribuciones son bienvenidas. Abre un issue o envía un pull request.

Licencia

MIT - APOGEA Consultores