io.github.varaprasadreddy9676/huly-mcp

Official

by varaprasadreddy9676 · TypeScript

MCP server for Huly — manage projects, issues, documents and more via natural language.

Manage projects, issues, and documents in Huly using natural language.

README.md14 KBView on GitHub

huly-mcp-sdk

The most complete MCP server for Huly — the open-source project management platform.

Connects Claude Desktop (and any MCP-compatible client) directly to your Huly workspace. Manage projects, issues, milestones, components, documents, labels, and more — all via natural language.

Tools (36 total)

Category	Tool	Description
Projects	`list_projects`	List all projects in the workspace
	`get_project`	Get project details + available statuses
	`create_project`	Create a new tracker project with a unique identifier
Issues	`list_issues`	List issues with optional status / priority filters
	`get_issue`	Get full details of an issue (e.g. `PROJ-42`)
	`create_issue`	Create a new issue
	`update_issue`	Update title, status, priority, assignee, due date, component, milestone
	`delete_issue`	Permanently delete an issue by identifier
Comments	`add_comment`	Add a comment to an issue
	`list_comments`	List all comments on an issue (includes IDs for `delete_comment`)
	`delete_comment`	Delete a specific comment by ID
Time Tracking	`log_time`	Log hours spent on an issue
Labels	`list_labels`	List all labels with color + usage count
	`create_label`	Create a new label with an optional hex color
	`add_label`	Add a label to an issue (auto-creates if it doesn't exist)
	`remove_label`	Remove a label from an issue
Relations	`add_relation`	Mark two issues as related (bidirectional)
	`add_blocked_by`	Mark an issue as blocked by another issue
	`set_parent`	Set or clear the parent epic of an issue
Members	`list_members`	List workspace members
Milestones	`list_milestones`	List milestones for a project
	`create_milestone`	Create a milestone with a target date and status
Components	`list_components`	List components (sub-areas) in a project
	`create_component`	Create a new component with optional lead
Documents	`list_teamspaces`	List document teamspaces
	`create_teamspace`	Create a new teamspace (top-level document folder)
	`list_documents`	List documents in a teamspace
	`delete_document`	Permanently delete a document by ID
	`get_document`	Get document metadata + content
	`create_document`	Create a new document in a teamspace
	`update_document`	Write Markdown content to a document — Mermaid diagrams render natively
	`link_document`	Link a document to an issue — appears in the Relations panel
Search	`search_issues`	Full-text search across all issues

Requirements

Node.js >= 20
A Huly account — huly.app (cloud) or self-hosted

Quick Start

bash

npx huly-mcp-sdk setup

This 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.

Your workspace slug is the part of your Huly URL after the domain: huly.app/myteam → slug is myteam.

Compatible Clients

The same MCP server works across all major AI coding tools. Pick your client.

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:
json
"HULY_EMAIL": "your@email.com",
"HULY_PASSWORD": "yourpassword",
"HULY_WORKSPACE": "your-workspace-slug"
See Manual Auth for details on both options.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

json

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

Restart Claude Desktop after saving.

Claude Code (CLI)

bash

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

Or scope it to a single project only:

bash

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

Verify it's connected: claude mcp list

Cursor

Create or edit ~/.cursor/mcp.json:

json

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

Restart Cursor. The tools appear in the Agent panel under MCP.

Windsurf (Codeium)

Create or edit ~/.codeium/windsurf/mcp_config.json:

json

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

Restart Windsurf. MCP tools are available to the Cascade AI panel.

VS Code — Cline extension

Install the Cline extension
Open Cline settings → MCP Servers → Edit MCP Settings
Add:

json

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

VS Code — Continue extension

Install the Continue extension
Edit ~/.continue/config.json and add to the mcpServers array:

json

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

Zed

Edit ~/.config/zed/settings.json and add a context_servers entry:

json

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

OpenAI Codex CLI

Edit ~/.codex/config.json and add to mcpServers:

json

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

Any other MCP-compatible client

The server uses standard stdio transport. If your tool supports MCP, the config pattern is always the same:

command: npx
args: ["huly-mcp-sdk"]
env: HULY_TOKEN + HULY_WORKSPACE

Consult your tool's MCP documentation for the exact config file location.

Alternative (avoid npx cold-start): Clone and build once, then point directly at the compiled binary:
bash
git clone https://github.com/varaprasadreddy9676/huly-mcp.git
cd huly-mcp && npm install && npm run build
Replace "command": "npx", "args": ["huly-mcp-sdk"] with "command": "node", "args": ["/absolute/path/to/huly-mcp/dist/index.js"] in any config above.

Example Prompts

Projects & issues:

"Create a new project called 'Mobile App' with identifier MOBILE"
"List all in-progress issues in the PROJ project"
"Create a high-priority issue in PROJ titled 'Fix login timeout'"
"Update PROJ-42 status to Done, assign it to Sarah, and move it to the Auth component"
"Search for issues related to authentication"
"Add a comment to PROJ-15 saying the fix is deployed"
"List all comments on PROJ-42 to see the discussion"

Milestones & components:

"Create a milestone 'v2.0 Launch' in PROJ with target date 2026-06-01"
"List milestones for the PROJ project"
"Create a component called 'Auth' in PROJ"
"List all components in PROJ"

Labels & relations:

"Add the label 'bug' to PROJ-42"
"Create a label called 'backend' with color #3b82f6"
"Mark PROJ-55 as blocked by PROJ-12"
"Set PROJ-42 as a subtask of PROJ-5"

Time tracking:

"Log 2.5 hours on PROJ-42 for the database refactor"

Documents:

"List all documents in the Engineering teamspace"
"Create a document called 'API Design' in the Engineering teamspace"
"Update the API Design document with this Markdown: ..."
"Add a Mermaid architecture diagram to the EP1 document"
"Link document abc123 to issue PROJ-42"
"Delete the second comment on PROJ-15"

Document Content

Reading: `get_document`

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:

json

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

For self-hosted Huly, set HULY_FRONT_URL to your own front service URL (e.g. http://localhost:8083).

Writing: `update_document`

update_document accepts a documentId and a markdown string and writes rich structured content directly to the document — no manual editing required.

Supported Markdown:

Element	Syntax
Headings	`#`, `##`, `###`
Bold / inline code	`bold`, `code`
Paragraphs	plain text
Bullet lists	`- item`
Pipe tables	`\| col \| col \|`
Code blocks	```lang
Mermaid diagrams	```mermaid — stored as Huly's native `mermaid` node type so diagrams render as interactive visuals in the editor

Example:

code

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

The Mermaid block renders as a live interactive diagram in Huly's document editor — not as a code block.

Bulk CSV Import

Import many issues at once from a CSV file — useful for migrating from other tools:

bash

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

CSV format:

csv

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

Required column: title. Optional: priority (Urgent/High/Medium/Low), status (must match a status name in the project), dueDate (YYYY-MM-DD).

Manual Auth

Create a .env file in the project root (or pass via env in your client config):

Option A — Email + password (recommended):

Works if you have a password set on your Huly account (Profile → Security → Change password).

bash

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

Option B — Token:

bash

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

To get a token: go to huly.app → open browser DevTools → Application → Local Storage → https://huly.app → copy the token value.

Tokens expire after some time. If you get an auth error, switch to email + password auth or refresh the token from DevTools.

Self-hosted Huly:

bash

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

Architecture

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)
Lazy init — connects on the first tool call so auth errors surface clearly in Claude
Dual auth — OTP token (works for Google/GitHub SSO) or email + password
Stdio transport — standard MCP transport compatible with Claude Desktop and any MCP client

Changelog

v0.5.6 — delete_document

New: delete_document — permanently delete a document by ID

v0.5.5 — create_teamspace

New: create_teamspace — create a new document teamspace (top-level folder for organising documents by project or team)

v0.5.2 — delete_comment + link_document

New: delete_comment — delete a specific comment from an issue by ID; list_comments now includes comment IDs in its output
New: link_document — link a Huly document to an issue; the document appears in the Relations panel on the issue

v0.5.0 — Document Writing + Bug Fixes

New: update_document — write Markdown to any Huly document programmatically; \``mermaid` blocks use Huly's native node type and render as interactive diagrams
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
Fix: create_project — sets members: [currentUser] so newly created projects are immediately visible in the Huly UI

v0.4.0

log_time, list_comments, component/milestone assignment on update_issue

v0.3.1

get_document, create_document

v0.3.0

create_project, create_milestone, assignee support on issues

License

Eclipse Public License 2.0

Install

Configuration

Environment variables

HULY_TOKENrequiredsecret

Huly workspace token — get from huly.app DevTools → Application → Local Storage → token

HULY_WORKSPACErequired

Your Huly workspace slug (the part after huly.app/ in your URL, e.g. 'myteam')

HULY_FRONT_URL

Optional — set to https://front.huly.app to enable reading document content

claude_desktop_config.json

{
  "mcpServers": {
    "huly-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "huly-mcp-sdk@0.5.4"
      ],
      "env": {
        "HULY_TOKEN": "<YOUR_HULY_TOKEN>",
        "HULY_WORKSPACE": "<YOUR_HULY_WORKSPACE>",
        "HULY_FRONT_URL": "<YOUR_HULY_FRONT_URL>"
      }
    }
  }
}

huly-mcp-sdk

Tools (36 total)

Requirements

Quick Start

Compatible Clients

Claude Desktop

Claude Code (CLI)

Cursor

Windsurf (Codeium)

VS Code — Cline extension

VS Code — Continue extension

Zed

OpenAI Codex CLI

Any other MCP-compatible client

Example Prompts

Document Content

Reading: get_document

Writing: update_document

Bulk CSV Import

Manual Auth

Architecture

Changelog

v0.5.6 — delete_document

v0.5.5 — create_teamspace

v0.5.2 — delete_comment + link_document

v0.5.0 — Document Writing + Bug Fixes

v0.4.0

v0.3.1

v0.3.0

Links

License

Install

Configuration

Reading: `get_document`

Writing: `update_document`