huly-mcp-sdk

El servidor MCP más completo para Huly — la plataforma de gestión de proyectos de código abierto.

Conecta Claude Desktop (y cualquier cliente compatible con MCP) directamente a tu espacio de trabajo de Huly. Gestiona proyectos, incidencias, hitos, componentes, documentos, etiquetas y más, todo mediante lenguaje natural.

Herramientas (36 en total)

Related MCP server: Huly MCP Server

Requisitos

• Node.js >= 20

• Una cuenta de Huly — huly.app (nube) o autoalojada

Inicio rápido

npx huly-mcp-sdk setup

Esto ejecuta el asistente de configuración interactivo: envía un código de un solo uso a tu correo (también funciona para cuentas SSO de Google/GitHub) y escribe tu archivo .env automáticamente.

El slug de tu workspace es la parte de tu URL de Huly después del dominio: huly.app/myteam → el slug es myteam.

Clientes compatibles

El mismo servidor MCP funciona en todas las principales herramientas de codificación con IA. Elige tu cliente.

Nota de autenticación: Todos los ejemplos de configuración a continuación usan HULY_TOKEN. Si tienes problemas con la expiración del token, usa correo electrónico + contraseña en su lugar — solo reemplaza el bloque env con:

"HULY_EMAIL": "your@email.com",
"HULY_PASSWORD": "yourpassword",
"HULY_WORKSPACE": "your-workspace-slug"

Consulta Autenticación manual para más detalles sobre ambas opciones.

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Reinicia Claude Desktop después de guardar.

Claude Code (CLI)

claude mcp add huly -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk

O limítalo a un solo proyecto:

claude mcp add huly --scope project -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk

Verifica que está conectado: claude mcp list

Cursor

Crea o edita ~/.cursor/mcp.json:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Reinicia Cursor. Las herramientas aparecen en el panel de Agente bajo MCP.

Windsurf (Codeium)

Crea o edita ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Reinicia Windsurf. Las herramientas MCP están disponibles en el panel de IA Cascade.

VS Code — extensión Cline

1. Instala la extensión Cline

2. Abre la configuración de Cline → Servidores MCP → Editar configuración MCP

3. Añade:

{
  "huly": {
    "command": "npx",
    "args": ["huly-mcp-sdk"],
    "env": {
      "HULY_TOKEN": "your-token",
      "HULY_WORKSPACE": "your-workspace-slug"
    }
  }
}

VS Code — extensión Continue

1. Instala la extensión Continue

2. Edita ~/.continue/config.json y añade al array mcpServers:

{
  "mcpServers": [
    {
      "name": "huly",
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  ]
}

Zed

Edita ~/.config/zed/settings.json y añade una entrada context_servers:

{
  "context_servers": {
    "huly": {
      "command": {
        "path": "npx",
        "args": ["huly-mcp-sdk"],
        "env": {
          "HULY_TOKEN": "your-token",
          "HULY_WORKSPACE": "your-workspace-slug"
        }
      }
    }
  }
}

OpenAI Codex CLI

Edita ~/.codex/config.json y añade a mcpServers:

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Cualquier otro cliente compatible con MCP

El servidor usa el transporte stdio estándar. Si tu herramienta admite MCP, el patrón de configuración es siempre el mismo:

• comando: npx

• args: ["huly-mcp-sdk"]

• env: HULY_TOKEN + HULY_WORKSPACE

Consulta la documentación MCP de tu herramienta para conocer la ubicación exacta del archivo de configuración.

Alternativa (evitar el arranque en frío de npx): Clona y compila una vez, y luego apunta directamente al binario compilado:

git clone https://github.com/varaprasadreddy9676/huly-mcp.git
cd huly-mcp && npm install && npm run build

Reemplaza "command": "npx", "args": ["huly-mcp-sdk"] con "command": "node", "args": ["/absolute/path/to/huly-mcp/dist/index.js"] en cualquier configuración anterior.

Ejemplos de prompts

Proyectos e incidencias:

• "Crea un nuevo proyecto llamado 'Mobile App' con identificador MOBILE"

• "Lista todas las incidencias en progreso del proyecto PROJ"

• "Crea una incidencia de alta prioridad en PROJ titulada 'Corregir el tiempo de espera de inicio de sesión'"

• "Actualiza PROJ-42 a estado Hecho, asígnala a Sarah y muévela al componente Auth"

• "Busca incidencias relacionadas con autenticación"

• "Añade un comentario a PROJ-15 diciendo que el arreglo está desplegado"

• "Lista todos los comentarios de PROJ-42 para ver la discusión"

Hitos y componentes:

• "Crea un hito 'Lanzamiento v2.0' en PROJ con fecha objetivo 2026-06-01"

• "Lista los hitos del proyecto PROJ"

• "Crea un componente llamado 'Auth' en PROJ"

• "Lista todos los componentes de PROJ"

Etiquetas y relaciones:

• "Añade la etiqueta 'bug' a PROJ-42"

• "Crea una etiqueta llamada 'backend' con color #3b82f6"

• "Marca PROJ-55 como bloqueada por PROJ-12"

• "Establece PROJ-42 como subtarea de PROJ-5"

Seguimiento de tiempo:

• "Registra 2.5 horas en PROJ-42 para la refactorización de la base de datos"

Documentos:

• "Lista todos los documentos del teamspace de Ingeniería"

• "Crea un documento llamado 'Diseño de API' en el teamspace de Ingeniería"

• "Actualiza el documento 'Diseño de API' con este Markdown: ..."

• "Añade un diagrama de arquitectura Mermaid al documento EP1"

• "Vincula el documento abc123 a la incidencia PROJ-42"

• "Elimina el segundo comentario de PROJ-15"

Contenido del documento

Lectura: get_document

get_document siempre devuelve los metadatos completos (título, teamspace, comentarios, instantáneas). Para también obtener y mostrar el contenido de texto, establece la variable de entorno opcional HULY_FRONT_URL:

"env": {
  "HULY_TOKEN": "...",
  "HULY_WORKSPACE": "myteam",
  "HULY_FRONT_URL": "https://front.huly.app"
}

Para Huly autoalojado, establece HULY_FRONT_URL a la URL de tu servicio front (p. ej. http://localhost:8083).

Escritura: update_document

update_document acepta un documentId y una cadena markdown y escribe contenido estructurado enriquecido directamente en el documento, sin necesidad de edición manual.

Markdown admitido:

Ejemplo:

update_document({
  documentId: "abc123",
  markdown: `# Service Flow\n\n` +
    `## Architecture\n\n` +
    "```mermaid\n" +
    "flowchart TD\n" +
    "  A([User]) --> B[Browse Catalogue]\n" +
    "  B --> C[Pay via Razorpay]\n" +
    "  C --> D[Order Confirmed]\n" +
    "```\n\n" +
    "## Business Rules\n\n" +
    "- Payment required before confirmation\n" +
    "- All orders synced to HIS\n"
})

El bloque Mermaid se renderiza como un diagrama interactivo en vivo en el editor de documentos de Huly, no como un bloque de código.

Importación CSV masiva

Importa muchas incidencias a la vez desde un archivo CSV — útil para migrar desde otras herramientas:

node scripts/import-csv.js tasks.csv PROJ

Formato CSV:

title,priority,status,dueDate
Fix login bug,High,In Progress,2025-04-01
Add dark mode,Medium,,
Improve performance,Urgent,,2025-05-01

Columna obligatoria: title. Opcionales: priority (Urgente/Alta/Media/Baja), status (debe coincidir con un nombre de estado del proyecto), dueDate (AAAA-MM-DD).

Autenticación manual

Crea un archivo .env en la raíz del proyecto (o pásalo mediante env en la configuración de tu cliente):

Opción A — Correo electrónico + contraseña (recomendada):

Funciona si tienes una contraseña establecida en tu cuenta de Huly (Perfil → Seguridad → Cambiar contraseña).

HULY_EMAIL=your@email.com
HULY_PASSWORD=yourpassword
HULY_WORKSPACE=your-workspace-slug

Opción B — Token:

HULY_WORKSPACE=your-workspace-slug
HULY_TOKEN=your-token-here

Para obtener un token: ve a huly.app → abre las herramientas de desarrollador del navegador → Aplicación → Almacenamiento local → https://huly.app → copia el valor de token.

Los tokens expiran después de un tiempo. Si recibes un error de autenticación, cambia a autenticación con correo + contraseña o actualiza el token desde las herramientas de desarrollador.

Huly autoalojado:

HULY_ACCOUNTS_URL=https://your-huly-instance.com/account
HULY_FRONT_URL=https://your-huly-instance.com

Arquitectura

• Conexión WebSocket única y de larga duración — se conecta una vez por proceso mediante @hcengineering/server-client, no por llamada de herramienta (la carga del modelo tarda 1–3 s, por lo que esto mantiene las herramientas rápidas)

• Inicialización perezosa — se conecta en la primera llamada de herramienta para que los errores de autenticación se muestren claramente en Claude

• Autenticación dual — token OTP (funciona para SSO de Google/GitHub) o correo + contraseña

• Transporte stdio — transporte MCP estándar compatible con Claude Desktop y cualquier cliente MCP

Registro de cambios

v0.5.6 — delete_document

• Nuevo: delete_document — elimina permanentemente un documento por ID

v0.5.5 — create_teamspace

• Nuevo: create_teamspace — crea un nuevo teamspace de documentos (carpeta de nivel superior para organizar documentos por proyecto o equipo)

v0.5.2 — delete_comment + link_document

• Nuevo: delete_comment — elimina un comentario específico de un issue por ID; list_comments ahora incluye los IDs de comentarios en su salida

• Nuevo: link_document — vincula un documento de Huly a un issue; el documento aparece en el panel de Relaciones del issue

v0.5.0 — Escritura de Documentos + Correcciones de Errores

• Nuevo: update_document — escribe Markdown en cualquier documento de Huly programáticamente; los bloques \``mermaid` usan el tipo de nodo nativo de Huly y se renderizan como diagramas interactivos

• Corrección: consultas IssueStatus — los estados se almacenan globalmente en Huly (core:space:Model), no por proyecto; se eliminó el filtro de espacio incorrecto que causaba errores de "no se encontraron estados" en create_issue, update_issue y list_issues

• Corrección: create_project — establece members: [currentUser] para que los proyectos recién creados sean visibles inmediatamente en la interfaz de Huly

v0.4.0

• log_time, list_comments, asignación de componente/hito en update_issue

v0.3.1

• get_document, create_document

v0.3.0

• create_project, create_milestone, soporte de asignado en issues

Enlaces

• npm: https://www.npmjs.com/package/huly-mcp-sdk

• GitHub: https://github.com/varaprasadreddy9676/huly-mcp

• Registro MCP: https://registry.modelcontextprotocol.io (buscar "huly-mcp")

Licencia

Eclipse Public License 2.0