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)

Requirements

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

Quick Start

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

Copy

"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

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

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:

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:

{
  "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:

{
  "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

1. Install the Cline extension
2. Open Cline settings → MCP Servers → Edit MCP Settings
3. Add:

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

VS Code — Continue extension

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

{
  "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:

{
  "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:

{
  "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

Copy

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:

"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:

Example: