huly-mcp-sdk

Huly 向けの最も完全なMCPサーバー — オープンソースのプロジェクト管理プラットフォーム。

Claude Desktop（および MCP 互換の任意のクライアント）をHulyワークスペースに直接接続します。プロジェクト、課題、マイルストーン、コンポーネント、ドキュメント、ラベルなどをすべて自然言語で管理できます。

ツール（合計36）

Related MCP server: Huly MCP Server

要件

• Node.js >= 20

• Hulyアカウント — huly.app（クラウド）またはセルフホスト

クイックスタート

npx huly-mcp-sdk setup

これにより対話式セットアップウィザードが実行され、メールにワンタイムコードが送信され（Google/GitHub SSOアカウントでも機能）、.env ファイルが自動的に作成されます。

ワークスペーススラッグとは、HulyのURLのドメインより後の部分です: huly.app/myteam → スラッグは myteam です。

対応クライアント

同じMCPサーバーは、主要なAIコーディングツールすべてで動作します。クライアントを選択してください。

認証に関する注意: 以下のすべての設定例では HULY_TOKEN を使用しています。トークンの期限切れで問題が発生する場合は、代わりにメールアドレス + パスワードを使用してください — 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の新しいプロジェクトを作成"

• "PROJプロジェクトの進行中の課題をすべて一覧表示"

• "PROJに「Fix login timeout」というタイトルの優先度が高い課題を作成"

• "PROJ-42のステータスをDoneに更新し、Sarahに割り当て、Authコンポーネントに移動"

• "認証に関連する課題を検索"

• "PROJ-15に修正がデプロイされたことを伝えるコメントを追加"

• "議論を確認するため、PROJ-42のすべてのコメントを一覧表示"

マイルストーンとコンポーネント:

• "PROJに目標日2026-06-01のマイルストーン「v2.0 Launch」を作成"

• "PROJプロジェクトのマイルストーンを一覧表示"

• "PROJに「Auth」というコンポーネントを作成"

• "PROJのすべてのコンポーネントを一覧表示"

ラベルと関連:

• "PROJ-42に「bug」ラベルを追加"

• "色 #3b82f6 の「backend」というラベルを作成"

• "PROJ-55をPROJ-12によってブロックされているとマーク"

• "PROJ-42をPROJ-5のサブタスクとして設定"

時間追跡:

• "データベースリファクタリングのため、PROJ-42に2.5時間を記録"

ドキュメント:

• "Engineeringチームスペース内のすべてのドキュメントを一覧表示"

• "Engineeringチームスペースに「API Design」というドキュメントを作成"

• "API Designドキュメントを次のMarkdownで更新: ..."

• "EP1ドキュメントにMermaidアーキテクチャ図を追加"

• "ドキュメントabc123を課題PROJ-42にリンク"

• "PROJ-15の2番目のコメントを削除"

ドキュメントコンテンツ

読み取り: get_document

get_document は常に完全なメタデータ（タイトル、チームスペース、コメント、スナップショット）を返します。テキストコンテンツも取得して表示するには、オプションの HULY_FRONT_URL 環境変数を設定します:

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

セルフホストのHulyの場合、HULY_FRONT_URL を独自のフロントサービスURL（例: http://localhost:8083）に設定します。

書き込み: update_document

update_document は documentId と markdown 文字列を受け取り、リッチな構造化コンテンツをドキュメントに直接書き込みます — 手動での編集は不要です。

対応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（YYYY-MM-DD）。

手動認証

プロジェクトルートに .env ファイルを作成します（またはクライアント設定の env で渡します）:

オプションA — メールアドレス + パスワード（推奨）:

Hulyアカウントにパスワードが設定されている場合に機能します（Profile → Security → Change password）。

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 の値をコピーします。

トークンはしばらくすると期限切れになります。認証エラーが発生した場合は、メールアドレス + パスワード認証に切り替えるか、DevToolsからトークンを更新してください。

セルフホストのHuly:

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

アーキテクチャ

• 単一の長時間接続WebSocket接続 — ツール呼び出しごとではなく、プロセスごとに @hcengineering/server-client 経由で1回接続します（モデルの読み込みに1〜3秒かかるため、これによりツールが高速に保たれます）

• 遅延初期化 — 最初のツール呼び出し時に接続するため、認証エラーがClaudeで明確に表示されます

• 二重認証 — OTPトークン（Google/GitHub SSOで機能）またはメールアドレス + パスワード

• Stdioトランスポート — Claude Desktopおよび任意のMCPクライアントと互換性のある標準のMCPトランスポート

変更履歴

v0.5.6 — delete_document

• 新機能: delete_document — ドキュメントをIDで完全に削除します

v0.5.5 — create_teamspace

• 新機能: create_teamspace — 新しいドキュメントのチームスペース（プロジェクトやチームごとにドキュメントを整理するための最上位フォルダー）を作成します

v0.5.2 — delete_comment + link_document

• 新機能: delete_comment — 課題から特定のコメントをIDで削除します。list_comments の出力にコメントIDが含まれるようになりました

• 新機能: link_document — Hulyドキュメントを課題にリンクします。ドキュメントは課題のRelationsパネルに表示されます

v0.5.0 — ドキュメント書き込み + バグ修正

• 新機能: update_document — 任意のHulyドキュメントにプログラムでMarkdownを書き込みます。\``mermaid` ブロックはHulyのネイティブノードタイプを使用し、インタラクティブな図としてレンダリングされます

• 修正: IssueStatus クエリ — ステータスはHuly内でグローバルに保存されます（core:space:Model）。プロジェクトごとではありません。create_issue、update_issue、list_issues で "no statuses found" エラーを引き起こしていた誤ったスペースフィルターを削除しました

• 修正: create_project — members: [currentUser] を設定し、新しく作成したプロジェクトがHuly UIにすぐに表示されるようにしました

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