MCP server providing full coverage of the Huly SDK — issues, projects, workspaces, members, and account management. Two transports: stdio for local tools and Streamable HTTP for remote clients. Tested against self-hosted Huly. May also work with Huly Cloud (not yet tested).

Huly has no public API. The only programmatic access is through their JavaScript SDK, which connects via WebSocket. This server wraps that SDK and exposes MCP tools over both stdio and Streamable HTTP transports — compatible with Claude Code, VS Code, n8n, and any MCP client.

npm install @bgx4k3p/huly-mcp-server

Or run directly with npx:

npx @bgx4k3p/huly-mcp-server

git clone https://github.com/bgx4k3p/huly-mcp-server.git
cd huly-mcp-server
npm install

The Huly SDK has workspace: protocol references in transitive dependencies on the npm registry. The custom pack script bundles only the needed SDK packages and prunes UI bloat (32MB to 4MB):

npm run pack
npm publish bgx4k3p-huly-mcp-server-<version>.tgz --access public

You can authenticate with either email/password or a token.

export HULY_URL=https://your-huly-instance.com
export [email protected]
export HULY_PASSWORD=your-password
export HULY_WORKSPACE=your-workspace

Get a token from your Huly credentials — no env vars needed beforehand:

node src/index.mjs --get-token -e [email protected] -p your-password -u https://your-huly-instance.com

Then use it:

export HULY_URL=https://your-huly-instance.com
export HULY_TOKEN=<paste-token-from-above>
export HULY_WORKSPACE=your-workspace

The token does not expire. You can store it in a secrets manager and stop exposing your password in environment variables.

After cloning and running npm install, register the server:

claude mcp add huly \
  -e HULY_URL=https://your-huly-instance.com \
  -e HULY_TOKEN=your-token \
  -e HULY_WORKSPACE=your-workspace \
  -- node /absolute/path/to/huly-mcp-server/src/index.mjs

Or add to your .mcp.json manually (token auth — recommended):

{
  "mcpServers": {
    "huly": {
      "command": "node",
      "args": ["/path/to/huly-mcp-server/src/index.mjs"],
      "env": {
        "HULY_URL": "https://your-huly-instance.com",
        "HULY_TOKEN": "${HULY_TOKEN}",
        "HULY_WORKSPACE": "${HULY_WORKSPACE}"
      }
    }
  }
}

Or with email/password:

{
  "mcpServers": {
    "huly": {
      "command": "node",
      "args": ["/path/to/huly-mcp-server/src/index.mjs"],
      "env": {
        "HULY_URL": "https://your-huly-instance.com",
        "HULY_EMAIL": "${HULY_EMAIL}",
        "HULY_PASSWORD": "${HULY_PASSWORD}",
        "HULY_WORKSPACE": "${HULY_WORKSPACE}"
      }
    }
  }
}

Then ask Claude things like:

• "List my issues in the OPS project"
• "Create a bug report for the login page crash"
• "Summarize the PROJ project — what's overdue?"
• "Break down this feature into subtasks using the feature template"

All tools have detailed descriptions optimized for AI agents. MCP Resources are also available at huly://projects/{id} and huly://issues/{id}.

Start the HTTP MCP server:

npm run start:server
# MCP endpoint: http://localhost:3001/mcp
# Health check: http://localhost:3001/health

Any MCP client that supports Streamable HTTP can connect to http://localhost:3001/mcp. This includes n8n (v1.88+), VS Code, and other MCP-compatible tools.

To secure the endpoint, set a bearer token:

MCP_AUTH_TOKEN=your-secret npm run start:server

Clients must then include Authorization: Bearer your-secret in requests.

docker build -t huly-mcp-server .

# Streamable HTTP server (recommended)
docker run -d \
  -p 3001:3001 \
  -e HULY_URL=https://your-huly-instance.com \
  -e HULY_TOKEN=your-token \
  -e HULY_WORKSPACE=my-workspace \
  huly-mcp-server

# MCP stdio mode
docker run -i \
  -e HULY_URL=https://your-huly-instance.com \
  -e HULY_TOKEN=your-token \
  -e HULY_WORKSPACE=my-workspace \
  huly-mcp-server node src/mcp.mjs

*HULY_WORKSPACE is required for MCP stdio mode. For HTTP mode it can be omitted if every request specifies a workspace via the tool arguments.

The HTTP server optionally requires a bearer token. This protects your server from unauthorized access — it's separate from Huly's own authentication.

# Generate a token
openssl rand -hex 32

# Start with auth enabled
MCP_AUTH_TOKEN=your-token-here npm run start:server

If MCP_AUTH_TOKEN is not set, auth is disabled (fine for local-only usage).

MCP stdio mode (Claude Code) does not use this token — stdio is inherently local.

All tools accept an optional workspace parameter. The connection pool caches clients by workspace slug with configurable TTL:

{"tool": "list_projects", "arguments": {"workspace": "workspace-a"}}

If omitted, the HULY_WORKSPACE env var is used as the default.

Uses Node.js built-in node:test and node:assert — no test framework dependencies. Tests run twice: once with WebSocket transport, once with REST transport.

npm test              # Both transports (ws + rest)
npm run test:ws       # WebSocket only
npm run test:rest     # REST only

194 tests across 101 suites:

100% dispatch coverage — every tool's params are traced end-to-end through the dispatch table to the client method.

• Local: HULY_URL=http://localhost:8087
• Remote: HULY_URL=https://huly.example.com
• Behind nginx proxy: Point to the proxy port

If Huly is behind Cloudflare Access with MFA, create a bypass Application for /_* or these individual paths:

• /_accounts
• /_transactor
• /_collaborator
• /_rekoni
• /config.json

src/
  client.mjs    # HulyClient — all business logic and SDK calls
  helpers.mjs   # Shared constants, markup conversion, JSDOM polyfills
  dispatch.mjs  # Tool-to-method dispatch table
  pool.mjs      # Connection pool — caches clients by workspace with TTL
  mcpShared.mjs # Shared MCP server factory — tool definitions + resources
  mcp.mjs       # MCP stdio entry point (Claude Code)
  server.mjs    # MCP Streamable HTTP entry point (n8n, VS Code, remote)
  index.mjs     # CLI entry point — --get-token mode + MCP re-export

Claude Code  -> stdio           -> mcp.mjs    -> mcpShared.mjs -> pool -> client -> Huly SDK
n8n / remote -> Streamable HTTP -> server.mjs -> mcpShared.mjs -> pool -> client -> Huly SDK

All read operations return known fields at the top level with resolved, human-readable values (e.g., status names instead of IDs, formatted dates). Any additional fields from the Huly SDK that aren't explicitly mapped appear in an extra object — this future-proofs the API so new SDK fields are visible without a code update.

{
  "id": "PROJ-42",
  "title": "Fix the bug",
  "status": "In Progress",
  "priority": "High",
  "type": "Task",
  "parent": "PROJ-10",
  "childCount": 3,
  "createdOn": 1719700000000,
  "completedAt": null,
  "extra": {
    "_id": "69bab168...",
    "_class": "tracker:class:Issue",
    "space": "69b819b7...",
    "kind": "tracker:taskTypes:Issue"
  }
}

Text fields (description, comment) support three input formats via descriptionFormat / format parameter:

• markdown (default) — rendered as rich text in the Huly UI
• html — raw HTML, converted to rich text
• plain — stored as unformatted text

Full list of all MCP tools available through this server.

Text format: All text fields default to markdown. Set descriptionFormat (or format for comments) to "markdown", "html", or "plain". Content is passed through unmodified -- the format tells Huly how to render it.

Several read tools support an include_details boolean parameter that fetches related data in a single call:

Use create_issues_from_template:

Templates use task types like Epic/Bug when available, falling back to the workspace default type otherwise.

npm audit reports moderate vulnerabilities in Svelte (SSR XSS). These come from Huly SDK transitive dependencies — the SDK shares packages with Huly's web frontend. MCP server never renders HTML or uses Svelte. The vulnerabilities are not exploitable in this context.

MIT