settings— hook

<p align="center"> <img src="./icon.png" alt="Huly MCP" width="160" height="160" /> </p>

<h1 align="center">Huly MCP</h1>

<p align="center"> Talk to your <a href="https://huly.io">Huly</a> workspace from Claude — issues, projects, milestones, documents, calendar, tests, attachments and more, all as MCP tools. </p>

<p align="center"> <b>~130 tools</b> · <b>14 domains</b> · <b>Claude Desktop ready (.mcpb)</b> · <b>4 PM skills included</b> </p>

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

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:

<table> <tr> <td width="120" align="center"><img src="./icon.png" alt="Huly" width="96" height="96" /></td> <td> <b>Huly</b><br/> Huly workspace assistant — manage issues, projects, milestones, time, documents and more from Claude.<br/> _{v1.0.0 · ~130 tools · stdio · <code>mcp/huly.mcpb</code>} </td> </tr> </table>

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

1. 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:

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

License

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

<p align="center"> Built for <a href="https://huly.io">Huly</a> · Powered by <a href="https://modelcontextprotocol.io">MCP</a> </p>