huly-mcp

huly-mcp-sdk

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

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

---

ツール（合計 36 個）

カテゴリ	ツール	説明
プロジェクト	list_projects	ワークスペース内のすべてのプロジェクトを一覧表示します
	get_project	プロジェクトの詳細と利用可能なステータスを取得します
	create_project	一意の識別子を持つ新しいトラッカープロジェクトを作成します
課題	list_issues	ステータスや優先度で任意に絞り込んで課題を一覧表示します
	get_issue	課題（例：PROJ-42）の詳細をすべて取得します
	create_issue	新しい課題を作成します
	update_issue	タイトル、ステータス、優先度、担当者、期限、コンポーネント、マイルストーンを更新します
	delete_issue	識別子を指定して課題を完全に削除します
コメント	add_comment	課題にコメントを追加します
	list_comments	課題のコメントをすべて一覧表示します（delete_comment 用の ID を含みます）
	delete_comment	ID を指定して特定のコメントを削除します
時間管理	log_time	課題に費やした時間を記録します
ラベル	list_labels	色と使用回数を含むすべてのラベルを一覧表示します
	create_label	16 進数カラーを任意で指定して、新しいラベルを作成します
	add_label	課題にラベルを追加します（存在しない場合は自動的に作成します）
	remove_label	課題からラベルを削除します
関連付け	add_relation	2 つの課題を関連付けます（双方向）
	add_blocked_by	ある課題が別の課題によってブロックされていることを設定します
	set_parent	課題の親エピックを設定または解除します
メンバー	list_members	ワークスペースのメンバーを一覧表示します
マイルストーン	list_milestones	プロジェクトのマイルストーンを一覧表示します
	create_milestone	目標日とステータスを指定してマイルストーンを作成します
コンポーネント	list_components	プロジェクト内のコンポーネント（サブ領域）を一覧表示します
	create_component	リードを任意で指定して、新しいコンポーネントを作成します
ドキュメント	list_teamspaces	ドキュメントのチームスペースを一覧表示します
	create_teamspace	新しいチームスペース（最上位のドキュメントフォルダー）を作成します
	list_documents	チームスペース内のドキュメントを一覧表示します
	delete_document	ID を指定してドキュメントを完全に削除します
	get_document	ドキュメントのメタデータと内容を取得します
	create_document	チームスペースに新しいドキュメントを作成します
	update_document	ドキュメントに Markdown コンテンツを書き込みます — Mermaid 図はネイティブにレンダリングされます
	link_document	ドキュメントを課題にリンクします — 「関連」パネルに表示されます
検索	search_issues	すべての課題を対象に全文検索します

---

要件

• 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": "[email protected]",
"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 を再起動します。ツールは MCP の下にある Agent パネルに表示されます。

---

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 として、Mobile App という新しいプロジェクトを作成して」
• 「PROJ プロジェクトの進行中の課題をすべて一覧表示して」
• 「PROJ に、タイトルを Fix login timeout とする優先度の高い課題を作成して」
• 「PROJ-42 のステータスを Done に更新し、Sarah に割り当てて、Auth コンポーネントに移動して」
• 「認証に関連する課題を検索して」
• 「PROJ-15 に、修正がデプロイされたというコメントを追加して」
• 「PROJ-42 のコメントをすべて一覧表示して、議論の内容を確認して」

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

• 「目標日を 2026-06-01 として、PROJ に 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 というドキュメントを作成して」
• 「次の Markdown で API Design ドキュメントを更新して：…」
• 「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：

要素	構文
見出し	#、##、###
太字／インラインコード	**bold**、`code`
段落	プレーンテキスト
箇条書き	- item
パイプテーブル	| col | col |
コードブロック	```lang
Mermaid 図	```mermaid — Huly のネイティブな mermaid ノードタイプとして保存されるため、エディターでインタラクティブなビジュアルとして表示されます

例：

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）。

[email protected]
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～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