huly-mcp-sdk

Самый полный MCP-сервер для Huly — платформы управления проектами с открытым исходным кодом.

Подключает Claude Desktop (и любой MCP-совместимый клиент) напрямую к вашему рабочему пространству Huly. Управляйте проектами, задачами, компонентами, вехами, документами, метками и многим другим — всё на естественном языке.

Инструменты (всего 36)

Related MCP server: Huly MCP Server

Требования

• Node.js >= 20

• Учётная запись Huly — huly.app (облако) или self-hosted

Быстрый старт

npx huly-mcp-sdk setup

Запустите интерактивный мастер настройки — он отправит одноразовый код на вашу почту (работает с Google/GitHub SSO) и автоматически создаст файл .env.

Ваш slug рабочего пространства — это часть URL Huly после домена: huly.app/myteam → slug = myteam.

Совместимые клиенты

Один и тот же MCP-сервер работает со всеми основными AI-инструментами кодинга. Выберите свой.

Примечание по авторизации: Во всех примерах ниже используется HULY_TOKEN. Если токен истёк, используйте email + пароль — просто замените блок env на:

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

См. Ручная авторизация для подробностей по обоим вариантам.

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"
      }
    }
  }
}

Перезапустите Claude Desktop после сохранения.

Claude Code (CLI)

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

Или ограничьте область действия одним проектом:

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

Проверьте подключение: claude mcp list

Cursor

Создайте или отредактируйте ~/.cursor/mcp.json:

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

Перезапустите Cursor. Инструменты появятся в панели Agent в разделе MCP.

Windsurf (Codeium)

Создайте или отредактируйте ~/.codeium/windsurf/mcp_config.json:

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

Перезапустите Windsurf. Инструменты MCP доступны в панели Cascade AI.

VS Code — расширение Cline

1. Установите расширение Cline

2. Откройте настройки Cline → MCP Servers → Edit MCP Settings

3. Добавьте:

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

VS Code — расширение Continue

1. Установите расширение Continue

2. Отредактируйте ~/.continue/config.json и добавьте в массив mcpServers:

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

Zed

Отредактируйте ~/.config/zed/settings.json и добавьте запись в 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

Отредактируйте ~/.codex/config.json и добавьте в mcpServers:

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

Любой другой MCP-совместимый клиент

Сервер использует стандартный stdio-транспорт. Если ваш инструмент поддерживает MCP, конфигурация всегда одинакова:

• command: npx

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

• env: HULY_TOKEN + HULY_WORKSPACE

Обратитесь к документации вашего инструмента по MCP для точного расположения файла конфигурации.

Альтернатива (избежать npx-загрузки): Клонируйте и соберите один раз, затем указывайте напрямую на скомпилированный бинарник:

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

Замените "command": "npx", "args": ["huly-mcp-sdk"] на "command": "node", "args": ["/absolute/path/to/huly-mcp/dist/index.js"] в любой конфигурации выше.

Примеры запросов

Проекты и задачи:

• «Создай новый проект с названием Mobile App и идентификатором MOBILE»

• «Покажи все задачи в статусе in-progress в проекте PROJ»

• «Создай задачу с высоким приоритетом в PROJ с названием "Fix login timeout"»

• «Обнови PROJ-42: статус Done, исполнитель Sarah, компонент Auth»

• «Найди задачи, связанные с аутентификацией»

• «Добавь комментарий к PROJ-15: фикс задеплоен»

• «Покажи все комментарии к PROJ-42, чтобы изучить обсуждение»

Вехи и компоненты:

• «Создай веху "v2.0 Launch" в PROJ с целевой датой 2026-06-01»

• «Покажи вехи проекта PROJ»

• «Создай компонент Auth в PROJ»

• «Покажи все компоненты в PROJ»

Метки и связи:

• «Добавь метку bug к PROJ-42»

• «Создай метку backend с цветом #3b82f6»

• «Отметь PROJ-55 как заблокированную задачей PROJ-12»

• «Сделай PROJ-42 подзадачей PROJ-5»

Учёт времени:

• «Запиши 2.5 часа на PROJ-42 за рефакторинг базы данных»

Документы:

• «Покажи все документы в командном пространстве Engineering»

• «Создай документ "API Design" в командном пространстве Engineering»

• «Обнови документ API Design этим Markdown: ...»

• «Добавь Mermaid-диаграмму архитектуры в документ EP1»

• «Привяжи документ abc123 к задаче PROJ-42»

• «Удали второй комментарий к PROJ-15»

Содержимое документов

Чтение: get_document

get_document всегда возвращает полные метаданные (название, командное пространство, комментарии, снимки). Чтобы также получить и отобразить текстовое содержимое, задайте необязательную переменную окружения HULY_FRONT_URL:

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

Для self-hosted Huly укажите HULY_FRONT_URL как URL вашего front-сервиса (например, http://localhost:8083).

Запись: update_document

update_document принимает documentId и строку markdown и записывает rich-структурированный контент прямо в документ — без ручного редактирования.

Поддерживаемый Markdown:

Пример:

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"
})

Блок Mermaid отображается как живая интерактивная диаграмма в редакторе документов Huly — а не как блок кода.

Массовый импорт из CSV

Импортируйте много задач сразу из CSV-файла — удобно при миграции из других инструментов:

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

Формат CSV:

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

Обязательная колонка: title. Необязательные: priority (Urgent/High/Medium/Low), status (должен совпадать с названием статуса в проекте), dueDate (ГГГГ-ММ-ДД).

Ручная авторизация

Создайте файл .env в корне проекта (или передайте через env в конфигурации клиента):

Вариант A — Email + пароль (рекомендуется):

Работает, если у вас задан пароль для учётной записи Huly (Профиль → Безопасность → Сменить пароль).

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

Вариант B — Токен:

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

Чтобы получить токен: перейдите на huly.app → откройте DevTools браузера → Application → Local Storage → https://huly.app → скопируйте значение token.

Токены истекают через некоторое время. Если получите ошибку авторизации, переключитесь на email + пароль или обновите токен через DevTools.

Self-hosted Huly:

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

Архитектура

• Одно долгоживущее WebSocket-соединение — подключается один раз на процесс через @hcengineering/server-client, а не при каждом вызове инструмента (загрузка модели занимает 1–3 с, поэтому это сохраняет скорость инструментов)

• Ленивая инициализация — подключение происходит при первом вызове инструмента, чтобы ошибки авторизации чётко отображались в Claude

• Двойная авторизация — OTP-токен (работает с Google/GitHub SSO) или email + пароль

• Stdio-транспорт — стандартный MCP-транспорт, совместимый с Claude Desktop и любым MCP-клиентом

Журнал изменений

v0.5.6 — delete_document

• Новое: delete_document — необратимо удаляет документ по ID

v0.5.5 — create_teamspace

• Новое: create_teamspace — создаёт новый teamspace для документов (папку верхнего уровня для организации документов по проекту или команде)

v0.5.2 — delete_comment + link_document

• Новое: delete_comment — удаляет конкретный комментарий из задачи по ID; list_comments теперь включает ID комментариев в свой вывод

• Новое: link_document — привязывает документ Huly к задаче; документ появляется на панели Relations задачи

v0.5.0 — Запись документов + Исправления ошибок

• Новое: update_document — программно записывает Markdown в любой документ Huly; блоки \``mermaid` используют встроенный тип узлов Huly и отображаются как интерактивные диаграммы

• Исправление: запросы IssueStatus — статусы хранятся в Huly глобально (core:space:Model), а не для каждого проекта; удалён некорректный фильтр по пространству, который приводил к ошибкам "статусы не найдены" в create_issue, update_issue и list_issues

• Исправление: create_project — задаёт members: [currentUser], чтобы новые проекты сразу были видны в интерфейсе Huly

v0.4.0

• log_time, list_comments, назначение компонента/вехи в update_issue

v0.3.1

• get_document, create_document

v0.3.0

• create_project, create_milestone, поддержка исполнителей в задачах

Ссылки

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

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

• MCP Registry: https://registry.modelcontextprotocol.io (ищите "huly-mcp")

Лицензия

Eclipse Public License 2.0