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:

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)

Productos (2)

Facturas de Venta (8)

Facturas de Compra (6)

Presupuestos (6)

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"

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

Contribuir

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

Licencia

MIT - APOGEA Consultores