Huly Mcp

@dugynoo/huly-mcp

Huly と連携する MCP サーバーです。23 カテゴリーにわたる 209 個のツール（課題、プロジェクト、タスク、コメント、ドキュメント、カード、チャンネル、カレンダー、時間追跡、テスト管理、プロセス、カスタムフィールド、添付ファイル、リードなど）を備えています。プロジェクトごとにスコープを設定したステータスワークフローを持つカスタムタスクタイプと、読み取り専用の Process プラグインツールに対応しています。

インストール

標準設定は、ほとんどの MCP クライアントで動作します。

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@dugynoo/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "[email protected]",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

claude mcp add huly \
  -e HULY_URL=https://huly.app \
  -e [email protected] \
  -e HULY_PASSWORD=yourpassword \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @dugynoo/huly-mcp@latest

{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@dugynoo/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "[email protected]",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

"huly": {
      "type": "local",
      "command": ["npx", "-y", "@dugynoo/huly-mcp@latest"],
      "environment": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "[email protected]",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }

更新

インストールコマンドの @latest タグを使用すると、常に最新バージョンが取得されます。ほとんどの MCP クライアントはインストール済みパッケージをキャッシュするため、再取得を強制する必要があります。

HTTP トランスポート

デフォルトでは、サーバーは stdio トランスポートを使用します。HTTP トランスポート（Streamable HTTP）を使用する場合：

HULY_URL=https://huly.app \
[email protected] \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @dugynoo/huly-mcp@latest

デフォルトでは、サーバーは http://127.0.0.1:3000/mcp でリッスンします。

MCP_HTTP_PORT と MCP_HTTP_HOST で設定します。

MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @dugynoo/huly-mcp@latest

環境変数

*認証：HULY_EMAIL と HULY_PASSWORD、または HULY_TOKEN のいずれかを指定してください。

@firfi/huly-mcp との違い

このパッケージは @firfi/huly-mcp の下流版で、次の2つの機能が追加されています。

• create_issue と update_issue の taskType パラメーター：カスタムタスクタイプ（例：Ticket、Bug、Feature）やプロジェクト単位のステータスワークフロー（Created、Awaiting approval など）を使って課題を作成できます。これがない場合、プロジェクトで独自のタスクタイプを定義していても、MCP 経由で作成した課題にはデフォルトのタスクタイプが適用されます。
• 読み取り専用の Process プラグインツール：list_processes、get_process、list_executions。Process プラグインが有効になっている Huly サーバー（v0.7.382 以降）が必要です。

オリジナルの上流版の著作権表示は LICENSE に引き継がれています。

利用可能なツール

TOOLSETS のカテゴリ： projects、issues、comments、milestones、documents、storage、attachments、contacts、channels、calendar、time tracking、search、activity、notifications、workspace、associations、cards、custom-fields、labels、leads、processes、tag-categories、task-management、test-management、user-statuses

プロジェクト

課題

コメント

マイルストーン

ドキュメント

ストレージ

添付ファイル

連絡先

チャンネル

カレンダー

時間の記録

検索

アクティビティ

通知

ワークスペース

関連付け

カード

カスタムフィールド

ラベル

リード

プロセス

タグカテゴリ

タスク管理

テスト管理

ユーザーステータス

トラブルシューティング

特殊文字を含むパスワード

Huly のパスワードに *、%、!、# などの文字が含まれている場合、シェルがこれらの文字をプロセスに渡す前に解釈するため、CLI の -e フラグで渡すと失敗することがあります。

解決方法：claude mcp add -e を使用する代わりに、MCP 設定ファイルを直接編集してください。~/.claude.json（ユーザースコープ）または .mcp.json（プロジェクトスコープ）では、JSON がすべての特殊文字をネイティブに処理します。

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "node",
      "args": ["path/to/dist/index.cjs"],
      "env": {
        "HULY_URL": "https://your-huly-instance.com",
        "HULY_EMAIL": "[email protected]",
        "HULY_PASSWORD": "p@ss*w0rd!#%",
        "HULY_WORKSPACE": "your-workspace"
      }
    }
  }
}

または、パスワード認証を完全に回避するために、メールアドレスとパスワードの代わりに HULY_TOKEN を使用してください（環境変数を参照）。

MCP クライアントに「Failed to reconnect」と表示される

MCP 設定を変更した後、一部のクライアント（Claude Code など）では、再接続するだけでなく、完全な再起動が必要です。アプリケーションを完全に終了してから、再度開いてください。

次の方法で、接続が独立して正常に機能することを確認できます。

claude mcp list  # Should show "Connected"

セルフホスト Huly：ログイン失敗の繰り返しによりアカウントがロックされる

Huly は、API 認証に 5 回失敗すると、パスワードログインをロックします。これは通常、初期設定時にパスワードの設定を誤った場合に発生します。このロックはサービスを再起動してもデータベースに保持されます。

症状：MCP サーバーから PasswordLoginLocked エラーが返され、Huly の Web UI に「パスワードログインは失敗回数が多すぎるためロックされています。アカウントのロックを解除するには OTP ログイン方式を使用してください」と表示されます（SMTP が設定されていない場合、OTP は機能しません）。

修正方法 — CockroachDB でロックカウンターをリセットします。

# Find your account UUID and check lock status
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "SELECT uuid, failed_login_attempts FROM global_account.account;"

# Reset the counter
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "UPDATE global_account.account SET failed_login_attempts = 0 WHERE uuid = '<your_account_uuid>';"

CockroachDB の認証情報は、Huly の compose.yml または docker exec <cockroach_container> env | grep COCKROACH で確認できます。

Windows 固有の注意事項

• Bash ラッパースクリプト（.env ファイルを読み込むもの）は、Windows 上で MCP クライアントから起動すると、正常に動作しない場合があります。MCP 設定 JSON で環境変数を直接設定することをおすすめします。
• SSH 経由の Docker イメージ取得は、認証情報マネージャーの問題により Windows で失敗することがあります。必要に応じて、サーバーのデスクトップからイメージを取得してください。