Huly MCP

Talk to your Huly workspace from Claude — issues, projects, milestones, documents, calendar, tests, attachments and more, all as MCP tools.

~130 tools · 14 domains · Claude Desktop ready (.mcpb) · 4 PM skills included

---

What is this?

huly-mcp is a Model Context Protocol server that exposes the Huly workspace API to any MCP-aware client (Claude Desktop, Claude Code, etc.). Once installed, Claude can read and mutate your Huly workspace conversationally — no UI, no CLI, just natural-language requests.

You: create a high-priority issue in PROJ titled "Fix login bug" and assign to me
Claude: ✓ Created PROJ-43 — "Fix login bug" (priority: high, assignee: [email protected])

What it covers

Domain	Operations
Tracker	Projects · Issues (+ sub-issues, relations, labels) · Comments · Milestones · Components · Templates · Statuses · Task types
Labels	Global labels CRUD · Tag categories
Time	Log time · Start/stop timers · Per-issue and project-wide reports (with assignee breakdown)
Documents	Teamspaces · Documents (markdown content via collaborator) · Doc↔issue links · Inline comments
Calendar	Events · Recurring events (RFC5545 RRULE) · Work slots
Test Management	Suites · Cases · Plans · Plan items · Runs · Results — full CRUD + execute-plan flow
Cards	Card spaces · Master tags · Cards (with markdown content)
Files	Upload to blob storage · Attach to any object (issue/document/etc.) · Pin · Download URL
Custom Fields	List · Read values · Set values (with mixin path)
Activity & Search	Audit trail · Fulltext search
Notifications	List · Mark-all-read

For the full per-tool inventory see FEATURES.md, and for input/output schemas see HULY_SPEC.md.

---

Getting Started

1. Prerequisites

• Node.js ≥ 18
• A Huly account
• An API token — generate one at: Huly → Settings → API Tokens → Generate token
• Your workspace slug — the last segment of https://huly.app/workbench/<slug>

2. Install the MCP plugin in Claude Desktop

The fastest path is the prebuilt .mcpb bundle:

Huly Huly workspace assistant — manage issues, projects, milestones, time, documents and more from Claude. v1.0.0 · ~130 tools · stdio · mcp/huly.mcpb

1. Download mcp/huly.mcpb from this repo (or run npm run bundle to build it yourself).
2. Open Claude Desktop → Settings → Extensions → Install from file and choose huly.mcpb.
3. Fill in the install dialog:
   • Huly URL — https://huly.app (or your self-hosted URL)
   • API Token — the token you generated
   • Workspace Slug — e.g. my-team
   • Account Email — used to resolve me when assigning issues
   • Disable TLS verification — leave blank unless you're behind a corporate MITM proxy
4. Restart Claude Desktop. Try: "List my projects in Huly."

3. (Optional) Use with Claude Code

Add this to your Claude Code MCP config (see mcp/claude_desktop_config.example.json for the full template):

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/huly-mcp/mcp/server.ts"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug",
        "HULY_EMAIL": "[email protected]"
      }
    }
  }
}

4. (Optional) Run locally for development

git clone <repo-url> huly-mcp && cd huly-mcp
npm install
cp .env.example .env
# edit .env: HULY_URL / HULY_TOKEN / HULY_WORKSPACE / HULY_EMAIL
npm run mcp     # starts the MCP server on stdio

---

PM Skills (Claude Code)

Four Claude Code skills under skills/ sit on top of the MCP tools and turn the raw API into PM-friendly workflows:

Skill	What it does
/pm-overview <PROJECT>	Single-screen project health snapshot — issues by status / priority / assignee, milestone state, recent activity.
/standup <PROJECT>	Daily standup digest (project-level by default) — yesterday's logged time, today's plate, blockers — paste-ready for Slack.
/pm-risks <PROJECT>	Risk radar — overdue, sprint-at-risk, unassigned high-priority, stuck in-progress, bottlenecks, over-budget.
/pm-status-report <PROJECT>	Comprehensive stakeholder report — exec summary, key metrics, milestones, velocity, team performance, full task list grouped by component and broken down by status, bottlenecks, risks, recommendations.

Install (one-time):

# Globally — available in every Claude Code session
ln -sfn "$(pwd)/skills/pm-overview"       ~/.claude/skills/pm-overview
ln -sfn "$(pwd)/skills/standup"           ~/.claude/skills/standup
ln -sfn "$(pwd)/skills/pm-risks"          ~/.claude/skills/pm-risks
ln -sfn "$(pwd)/skills/pm-status-report"  ~/.claude/skills/pm-status-report

(For project-local install, replace ~/.claude/skills with <project>/.claude/skills.)

---

Repo layout

huly-mcp/
├── icon.png                    # plugin icon
├── core/                       # shared command + lib code (imported by the MCP server)
│   ├── commands/               # one file per domain (tracker, comments, calendar, tests, …)
│   └── lib/                    # client, env, hcengineering interop, markup, resolvers
├── mcp/
│   ├── server.ts               # MCP server source — wires ~130 huly_* tools
│   ├── manifest.json           # MCPB manifest (user_config + env wiring)
│   ├── huly.mcpb               # prebuilt installable bundle
│   ├── build/                  # esbuild output (regenerated by `npm run bundle`)
│   └── claude_desktop_config.example.json
├── skills/
│   ├── pm-overview/SKILL.md
│   ├── standup/SKILL.md
│   ├── pm-risks/SKILL.md
│   └── pm-status-report/SKILL.md
├── FEATURES.md                 # full tool inventory + coverage matrix
├── HULY_SPEC.md                # per-tool JSON schemas
├── package.json
└── tsconfig.json

---

Build from source

After editing mcp/server.ts or anything under core/:

npm run bundle     # → regenerates mcp/build/ and mcp/huly.mcpb

Reinstall the new huly.mcpb in Claude Desktop to pick up changes.

---

Server logs & debugging

Claude Desktop writes logs to ~/Library/Logs/Claude/mcp-server-huly.log (macOS).

The server logs:

• Startup line with HULY_URL, workspace, email, token prefix, and any HTTP_PROXY / NODE_EXTRA_CA_CERTS env vars.
• Each tool call (name, args, latency, success/failure).
• On error, the full error.cause chain — DNS code, TLS reason, etc. — surfaced in both the log and the tool response payload.

Behind a corporate proxy

If you see SELF_SIGNED_CERT_IN_CHAIN or similar TLS errors:

1. Preferred: set NODE_EXTRA_CA_CERTS to the path of your proxy's CA bundle.
2. Last resort: set the huly_insecure_tls user_config to "1" — disables certificate verification for this MCP server only.

---

Troubleshooting

Symptom	Fix
HULY_* env var not set	Fill in the Claude Desktop install dialog, or set .env (local dev).
Cannot find module '@hcengineering/api-client'	Run npm install at the repo root.
Workspace not found	HULY_WORKSPACE must match the slug after /workbench/ exactly (case-sensitive).
401 / auth error	Token expired — regenerate at Huly → Settings → API Tokens and reinstall the bundle.
fetch failed	Check mcp-server-huly.log for the caused by → line — surfaces ENOTFOUND / ECONNREFUSED / TLS reasons.

---

License

MIT — feel free to fork, patch, and ship.

---

Built for Huly · Powered by MCP