holded-mcp-server

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

Expone 25 herramientas (tools) que cubren: facturas de venta, facturas de compra, presupuestos, contactos y productos de la API de facturación de Holded.

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

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

| Sistema | Ruta del fichero | |---------|------------------| | Windows | %APPDATA%\Claude\claude_desktop_config.json | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |

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 (25)

Contactos (3)

| Tool | Descripción | |------|-------------| | holded_list_contacts | Lista todos los contactos (clientes, proveedores, etc.) | | holded_get_contact | Obtiene los detalles de un contacto por su ID | | holded_search_contacts | Busca contactos por nombre (búsqueda parcial) |

Productos (2)

| Tool | Descripción | |------|-------------| | holded_list_products | Lista todos los productos y servicios | | holded_get_product | Obtiene los detalles de un producto por su ID |

Facturas de Venta (8)

| Tool | Descripción | |------|-------------| | holded_list_invoices | Lista facturas. Filtros: fecha inicio/fin, contacto | | holded_get_invoice | Detalle completo de una factura | | holded_create_invoice | Crea una nueva factura de venta | | holded_update_invoice | Actualiza una factura existente | | holded_delete_invoice | Elimina una factura | | holded_pay_invoice | Registra un pago en una factura | | holded_send_invoice | Envía una factura por email | | holded_get_invoice_pdf | Obtiene el PDF de la factura (base64) |

Facturas de Compra (6)

| Tool | Descripción | |------|-------------| | holded_list_purchases | Lista facturas de compra (gastos) | | holded_get_purchase | Detalle de una factura de compra | | holded_create_purchase | Registra una nueva factura de compra | | holded_update_purchase | Actualiza una factura de compra | | holded_delete_purchase | Elimina una factura de compra | | holded_pay_purchase | Registra un pago a proveedor |

Presupuestos (6)

| Tool | Descripción | |------|-------------| | holded_list_estimates | Lista presupuestos. Filtros: fecha, contacto | | holded_get_estimate | Detalle de un presupuesto | | holded_create_estimate | Crea un nuevo presupuesto | | holded_update_estimate | Actualiza un presupuesto existente | | holded_delete_estimate | Elimina un presupuesto | | holded_send_estimate | Envía un presupuesto por email |

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 [email protected]"
• "Muéstrame las facturas de compra pendientes de pago"

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

Estructura del proyecto

src/
├── index.ts              # Entry point (McpServer + StdioServerTransport)
├── holded-client.ts      # Cliente HTTP para la API de Holded (retry 429)
├── types/
│   └── holded.ts         # Interfaces TypeScript
└── tools/
    ├── contacts.ts       # 3 tools de contactos
    ├── products.ts       # 2 tools de productos
    ├── invoices.ts       # 8 tools de facturas de venta
    ├── purchases.ts      # 6 tools de facturas de compra
    └── estimates.ts      # 6 tools de presupuestos

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

| Problema | Solución | |----------|----------| | El servidor no aparece en /mcp | Verifica que la ruta a build/index.js es correcta y absoluta | | Error HOLDED_API_KEY is required | Añade la variable env.HOLDED_API_KEY en la configuración MCP | | Error 401 o 403 de la API | La API key es incorrecta o ha expirado. Genera una nueva en Holded | | Error 429 (rate limit) | El servidor reintenta automáticamente. Si persiste, espera unos segundos | | No compila (npm run build falla) | Asegúrate de tener Node.js >= 18 y haber ejecutado npm install |

Contribuir

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

Licencia

MIT - APOGEA Consultores