{
  "markdown": "# huly-mcp-sdk\n\n> The most complete MCP server for [Huly](https://huly.app) — the open-source project management platform.\n\nConnects **Claude Desktop** (and any [MCP](https://modelcontextprotocol.io)-compatible client) directly to your Huly workspace. Manage projects, issues, milestones, components, documents, labels, and more — all via natural language.\n\n---\n\n## Tools (36 total)\n\n| Category | Tool | Description |\n|----------|------|-------------|\n| **Projects** | `list_projects` | List all projects in the workspace |\n| | `get_project` | Get project details + available statuses |\n| | `create_project` | Create a new tracker project with a unique identifier |\n| **Issues** | `list_issues` | List issues with optional status / priority filters |\n| | `get_issue` | Get full details of an issue (e.g. `PROJ-42`) |\n| | `create_issue` | Create a new issue |\n| | `update_issue` | Update title, status, priority, assignee, due date, component, milestone |\n| | `delete_issue` | Permanently delete an issue by identifier |\n| **Comments** | `add_comment` | Add a comment to an issue |\n| | `list_comments` | List all comments on an issue (includes IDs for `delete_comment`) |\n| | `delete_comment` | Delete a specific comment by ID |\n| **Time Tracking** | `log_time` | Log hours spent on an issue |\n| **Labels** | `list_labels` | List all labels with color + usage count |\n| | `create_label` | Create a new label with an optional hex color |\n| | `add_label` | Add a label to an issue (auto-creates if it doesn't exist) |\n| | `remove_label` | Remove a label from an issue |\n| **Relations** | `add_relation` | Mark two issues as related (bidirectional) |\n| | `add_blocked_by` | Mark an issue as blocked by another issue |\n| | `set_parent` | Set or clear the parent epic of an issue |\n| **Members** | `list_members` | List workspace members |\n| **Milestones** | `list_milestones` | List milestones for a project |\n| | `create_milestone` | Create a milestone with a target date and status |\n| **Components** | `list_components` | List components (sub-areas) in a project |\n| | `create_component` | Create a new component with optional lead |\n| **Documents** | `list_teamspaces` | List document teamspaces |\n| | `create_teamspace` | Create a new teamspace (top-level document folder) |\n| | `list_documents` | List documents in a teamspace |\n| | `delete_document` | Permanently delete a document by ID |\n| | `get_document` | Get document metadata + content |\n| | `create_document` | Create a new document in a teamspace |\n| | `update_document` | Write Markdown content to a document — Mermaid diagrams render natively |\n| | `link_document` | Link a document to an issue — appears in the Relations panel |\n| **Search** | `search_issues` | Full-text search across all issues |\n\n---\n\n## Requirements\n\n- Node.js >= 20\n- A Huly account — [huly.app](https://huly.app) (cloud) or self-hosted\n\n---\n\n## Quick Start\n\n```bash\nnpx huly-mcp-sdk setup\n```\n\nThis runs the interactive setup wizard — sends a one-time code to your email (works for Google/GitHub SSO accounts too) and writes your `.env` file automatically.\n\n**Your workspace slug** is the part of your Huly URL after the domain: `huly.app/`**`myteam`** → slug is `myteam`.\n\n---\n\n## Compatible Clients\n\nThe same MCP server works across all major AI coding tools. Pick your client.\n\n> **Auth note:** All config examples below use `HULY_TOKEN`. If you have issues with token expiry, use email + password instead — just replace the `env` block with:\n> ```json\n> \"HULY_EMAIL\": \"your@email.com\",\n> \"HULY_PASSWORD\": \"yourpassword\",\n> \"HULY_WORKSPACE\": \"your-workspace-slug\"\n> ```\n> See [Manual Auth](#manual-auth) for details on both options.\n\n---\n\n### Claude Desktop\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"huly\": {\n      \"command\": \"npx\",\n      \"args\": [\"huly-mcp-sdk\"],\n      \"env\": {\n        \"HULY_TOKEN\": \"your-token\",\n        \"HULY_WORKSPACE\": \"your-workspace-slug\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n---\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add huly -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk\n```\n\nOr scope it to a single project only:\n\n```bash\nclaude mcp add huly --scope project -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk\n```\n\nVerify it's connected: `claude mcp list`\n\n---\n\n### Cursor\n\nCreate or edit `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"huly\": {\n      \"command\": \"npx\",\n      \"args\": [\"huly-mcp-sdk\"],\n      \"env\": {\n        \"HULY_TOKEN\": \"your-token\",\n        \"HULY_WORKSPACE\": \"your-workspace-slug\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor. The tools appear in the Agent panel under MCP.\n\n---\n\n### Windsurf (Codeium)\n\nCreate or edit `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"huly\": {\n      \"command\": \"npx\",\n      \"args\": [\"huly-mcp-sdk\"],\n      \"env\": {\n        \"HULY_TOKEN\": \"your-token\",\n        \"HULY_WORKSPACE\": \"your-workspace-slug\"\n      }\n    }\n  }\n}\n```\n\nRestart Windsurf. MCP tools are available to the Cascade AI panel.\n\n---\n\n### VS Code — Cline extension\n\n1. Install the [Cline extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)\n2. Open Cline settings → **MCP Servers** → **Edit MCP Settings**\n3. Add:\n\n```json\n{\n  \"huly\": {\n    \"command\": \"npx\",\n    \"args\": [\"huly-mcp-sdk\"],\n    \"env\": {\n      \"HULY_TOKEN\": \"your-token\",\n      \"HULY_WORKSPACE\": \"your-workspace-slug\"\n    }\n  }\n}\n```\n\n---\n\n### VS Code — Continue extension\n\n1. Install the [Continue extension](https://marketplace.visualstudio.com/items?itemName=Continue.continue)\n2. Edit `~/.continue/config.json` and add to the `mcpServers` array:\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"huly\",\n      \"command\": \"npx\",\n      \"args\": [\"huly-mcp-sdk\"],\n      \"env\": {\n        \"HULY_TOKEN\": \"your-token\",\n        \"HULY_WORKSPACE\": \"your-workspace-slug\"\n      }\n    }\n  ]\n}\n```\n\n---\n\n### Zed\n\nEdit `~/.config/zed/settings.json` and add a `context_servers` entry:\n\n```json\n{\n  \"context_servers\": {\n    \"huly\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"huly-mcp-sdk\"],\n        \"env\": {\n          \"HULY_TOKEN\": \"your-token\",\n          \"HULY_WORKSPACE\": \"your-workspace-slug\"\n        }\n      }\n    }\n  }\n}\n```\n\n---\n\n### OpenAI Codex CLI\n\nEdit `~/.codex/config.json` and add to `mcpServers`:\n\n```json\n{\n  \"mcpServers\": {\n    \"huly\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"huly-mcp-sdk\"],\n      \"env\": {\n        \"HULY_TOKEN\": \"your-token\",\n        \"HULY_WORKSPACE\": \"your-workspace-slug\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### Any other MCP-compatible client\n\nThe server uses standard **stdio transport**. If your tool supports MCP, the config pattern is always the same:\n\n- **command:** `npx`\n- **args:** `[\"huly-mcp-sdk\"]`\n- **env:** `HULY_TOKEN` + `HULY_WORKSPACE`\n\nConsult your tool's MCP documentation for the exact config file location.\n\n> **Alternative (avoid npx cold-start):** Clone and build once, then point directly at the compiled binary:\n> ```bash\n> git clone https://github.com/varaprasadreddy9676/huly-mcp.git\n> cd huly-mcp && npm install && npm run build\n> ```\n> Replace `\"command\": \"npx\", \"args\": [\"huly-mcp-sdk\"]` with `\"command\": \"node\", \"args\": [\"/absolute/path/to/huly-mcp/dist/index.js\"]` in any config above.\n\n---\n\n<img width=\"932\" height=\"401\" alt=\"image\" src=\"https://github.com/user-attachments/assets/0f9d9a74-ca1e-4884-bd6a-918c0fb8ddbd\" />\n\n## Example Prompts\n\n**Projects & issues:**\n- *\"Create a new project called 'Mobile App' with identifier MOBILE\"*\n- *\"List all in-progress issues in the PROJ project\"*\n- *\"Create a high-priority issue in PROJ titled 'Fix login timeout'\"*\n- *\"Update PROJ-42 status to Done, assign it to Sarah, and move it to the Auth component\"*\n- *\"Search for issues related to authentication\"*\n- *\"Add a comment to PROJ-15 saying the fix is deployed\"*\n- *\"List all comments on PROJ-42 to see the discussion\"*\n\n**Milestones & components:**\n- *\"Create a milestone 'v2.0 Launch' in PROJ with target date 2026-06-01\"*\n- *\"List milestones for the PROJ project\"*\n- *\"Create a component called 'Auth' in PROJ\"*\n- *\"List all components in PROJ\"*\n\n**Labels & relations:**\n- *\"Add the label 'bug' to PROJ-42\"*\n- *\"Create a label called 'backend' with color #3b82f6\"*\n- *\"Mark PROJ-55 as blocked by PROJ-12\"*\n- *\"Set PROJ-42 as a subtask of PROJ-5\"*\n\n**Time tracking:**\n- *\"Log 2.5 hours on PROJ-42 for the database refactor\"*\n\n**Documents:**\n- *\"List all documents in the Engineering teamspace\"*\n- *\"Create a document called 'API Design' in the Engineering teamspace\"*\n- *\"Update the API Design document with this Markdown: ...\"*\n- *\"Add a Mermaid architecture diagram to the EP1 document\"*\n- *\"Link document abc123 to issue PROJ-42\"*\n- *\"Delete the second comment on PROJ-15\"*\n\n---\n\n## Document Content\n\n### Reading: `get_document`\n\n`get_document` always returns full metadata (title, teamspace, comments, snapshots). To also fetch and display the **text content**, set the optional `HULY_FRONT_URL` env var:\n\n```json\n\"env\": {\n  \"HULY_TOKEN\": \"...\",\n  \"HULY_WORKSPACE\": \"myteam\",\n  \"HULY_FRONT_URL\": \"https://front.huly.app\"\n}\n```\n\nFor **self-hosted** Huly, set `HULY_FRONT_URL` to your own front service URL (e.g. `http://localhost:8083`).\n\n### Writing: `update_document`\n\n`update_document` accepts a `documentId` and a `markdown` string and writes rich structured content directly to the document — no manual editing required.\n\n**Supported Markdown:**\n\n| Element | Syntax |\n|---------|--------|\n| Headings | `#`, `##`, `###` |\n| Bold / inline code | `**bold**`, `` `code` `` |\n| Paragraphs | plain text |\n| Bullet lists | `- item` |\n| Pipe tables | `\\| col \\| col \\|` |\n| Code blocks | ` ```lang ` |\n| **Mermaid diagrams** | ` ```mermaid ` — stored as Huly's native `mermaid` node type so diagrams render as interactive visuals in the editor |\n\n**Example:**\n\n```\nupdate_document({\n  documentId: \"abc123\",\n  markdown: `# Service Flow\\n\\n` +\n    `## Architecture\\n\\n` +\n    \"```mermaid\\n\" +\n    \"flowchart TD\\n\" +\n    \"  A([User]) --> B[Browse Catalogue]\\n\" +\n    \"  B --> C[Pay via Razorpay]\\n\" +\n    \"  C --> D[Order Confirmed]\\n\" +\n    \"```\\n\\n\" +\n    \"## Business Rules\\n\\n\" +\n    \"- Payment required before confirmation\\n\" +\n    \"- All orders synced to HIS\\n\"\n})\n```\n\nThe Mermaid block renders as a live interactive diagram in Huly's document editor — not as a code block.\n\n---\n\n## Bulk CSV Import\n\nImport many issues at once from a CSV file — useful for migrating from other tools:\n\n```bash\nnode scripts/import-csv.js tasks.csv PROJ\n```\n\n**CSV format:**\n\n```csv\ntitle,priority,status,dueDate\nFix login bug,High,In Progress,2025-04-01\nAdd dark mode,Medium,,\nImprove performance,Urgent,,2025-05-01\n```\n\nRequired column: `title`. Optional: `priority` (Urgent/High/Medium/Low), `status` (must match a status name in the project), `dueDate` (YYYY-MM-DD).\n\n---\n\n## Manual Auth\n\nCreate a `.env` file in the project root (or pass via `env` in your client config):\n\n**Option A — Email + password (recommended):**\n\nWorks if you have a password set on your Huly account (Profile → Security → Change password).\n\n```bash\nHULY_EMAIL=your@email.com\nHULY_PASSWORD=yourpassword\nHULY_WORKSPACE=your-workspace-slug\n```\n\n**Option B — Token:**\n\n```bash\nHULY_WORKSPACE=your-workspace-slug\nHULY_TOKEN=your-token-here\n```\n\nTo get a token: go to [huly.app](https://huly.app) → open browser DevTools → Application → Local Storage → `https://huly.app` → copy the `token` value.\n\n> Tokens expire after some time. If you get an auth error, switch to email + password auth or refresh the token from DevTools.\n\n**Self-hosted Huly:**\n\n```bash\nHULY_ACCOUNTS_URL=https://your-huly-instance.com/account\nHULY_FRONT_URL=https://your-huly-instance.com\n```\n\n---\n\n## Architecture\n\n- **Single long-lived WebSocket connection** — connects once per process via `@hcengineering/server-client`, not per tool call (model load takes 1–3 s, so this keeps tools fast)\n- **Lazy init** — connects on the first tool call so auth errors surface clearly in Claude\n- **Dual auth** — OTP token (works for Google/GitHub SSO) or email + password\n- **Stdio transport** — standard MCP transport compatible with Claude Desktop and any MCP client\n\n---\n\n## Changelog\n\n### v0.5.6 — delete_document\n- **New: `delete_document`** — permanently delete a document by ID\n\n### v0.5.5 — create_teamspace\n- **New: `create_teamspace`** — create a new document teamspace (top-level folder for organising documents by project or team)\n\n### v0.5.2 — delete_comment + link_document\n- **New: `delete_comment`** — delete a specific comment from an issue by ID; `list_comments` now includes comment IDs in its output\n- **New: `link_document`** — link a Huly document to an issue; the document appears in the Relations panel on the issue\n\n### v0.5.0 — Document Writing + Bug Fixes\n- **New: `update_document`** — write Markdown to any Huly document programmatically; `\\`\\`\\`mermaid` blocks use Huly's native node type and render as interactive diagrams\n- **Fix: `IssueStatus` queries** — statuses are stored globally in Huly (`core:space:Model`), not per-project; removed incorrect space filter that caused *\"no statuses found\"* errors on `create_issue`, `update_issue`, and `list_issues`\n- **Fix: `create_project`** — sets `members: [currentUser]` so newly created projects are immediately visible in the Huly UI\n\n### v0.4.0\n- `log_time`, `list_comments`, component/milestone assignment on `update_issue`\n\n### v0.3.1\n- `get_document`, `create_document`\n\n### v0.3.0\n- `create_project`, `create_milestone`, assignee support on issues\n\n---\n\n## Links\n\n- npm: https://www.npmjs.com/package/huly-mcp-sdk\n- GitHub: https://github.com/varaprasadreddy9676/huly-mcp\n- MCP Registry: https://registry.modelcontextprotocol.io (search \"huly-mcp\")\n\n---\n\n## License\n\n[Eclipse Public License 2.0](https://www.eclipse.org/legal/epl-2.0/)\n",
  "bytes": 13953,
  "sha": "b45f75c3fb4d773753b5c5c9bcf667eee63ff3de316aaf0c9508497dc1869827",
  "repo_slug": "varaprasadreddy9676/huly-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_varaprasadreddy9676_huly_mcp_621c5d7b/readme"
}