Huly MCP服务器

Huly MCP Server

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

Why This Exists

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 Codex, Claude Code, VS Code, n8n, and any MCP client.

Documentation Map

• Install: add the package to a project or run it with npx.
• Quick Start: configure Huly authentication.
• Integrations: connect Codex, Claude Code, HTTP clients, or Docker.
• Configuration Reference: environment variables and workspace behavior.
• Network Configurations: local, remote, proxy, and access-gateway setups.
• Maintenance: repair scripts for known data consistency issues.
• Development and Publishing: tests, linting, and package publishing.
• API Reference: available MCP tools and response conventions.
• SDK Capability Audit: supported lifecycles, known gaps, and coverage gates are tracked in docs/SDK_CAPABILITY_AUDIT.md.

Install

From npm

npm install @bgx4k3p/huly-mcp-server

Or run directly with npx:

npx @bgx4k3p/huly-mcp-server

From source

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

Quick Start

Authentication

Configure Huly access first, then choose one integration in the next section. You can authenticate with either email/password or a token.

Email and Password

export HULY_URL=https://your-huly-instance.com
export HULY_EMAIL=your@email.com
export HULY_PASSWORD=your-password
export HULY_WORKSPACE=your-workspace

Token (recommended)

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

npx -y @bgx4k3p/huly-mcp-server --get-token \
  -e your@email.com \
  -p your-password \
  -u https://your-huly-instance.com

From a source checkout, use node src/index.mjs --get-token with the same flags.

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.

For local stdio clients, the project config examples below set HULY_WORKSPACE per repo. Optionally set HULY_PROJECT when a repository maps cleanly to one Huly project. After connecting a client, call get_huly_context first to verify that the workspace, project, URL host, and auth mode are what you expect.

Integrations

Use stdio for local coding agents and Streamable HTTP for remote clients or automation systems.

Codex (project-scoped stdio)

Codex supports MCP servers from config.toml. For project-specific Huly workspaces, generate a repo-local Codex config layer with literal routing values:

npx -y @bgx4k3p/huly-mcp-server --init-codex \
  --url https://your-huly-instance.com \
  --workspace my-workspace

Optionally set a default project identifier for project-scoped tools:

npx -y @bgx4k3p/huly-mcp-server --init-codex \
  --url https://your-huly-instance.com \
  --workspace my-workspace \
  --project PROJ

This creates .codex/config.toml:

[mcp_servers.huly]
command = "npx"
args = ["-y", "@bgx4k3p/huly-mcp-server"]
env_vars = ["HULY_TOKEN"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.huly.env]
HULY_URL = "https://your-huly-instance.com"
HULY_WORKSPACE = "my-workspace"
HULY_PROJECT = "PROJ"

Keep secrets like HULY_TOKEN in your user environment. Write non-secret routing values (HULY_URL, HULY_WORKSPACE, and optionally HULY_PROJECT) literally in each Codex project config so every repo, workspace folder, or editor project points to the intended Huly instance. This avoids accidentally inheriting a stale editor environment such as HULY_URL=http://localhost:8087. HULY_PROJECT is optional; when present, tools that naturally operate inside one project can omit the project argument. Explicit tool arguments still win.

If you intentionally want project routing to come from environment variables, use the matching *-env flags instead:

npx -y @bgx4k3p/huly-mcp-server --init-codex \
  --url-env HULY_URL \
  --workspace-env HULY_WORKSPACE \
  --project-env HULY_PROJECT

That writes the routing variables to Codex env_vars instead of literal values under [mcp_servers.huly.env].

Omitting --url leaves HULY_URL as a runtime environment reference. The generator does not read and copy the current shell's HULY_URL value into the project config unless you pass it explicitly with --url.

.codex/ is local machine configuration and should not be committed to a public repository. Keep project-specific Codex config private unless you have intentionally sanitized it for sharing.

After starting a fresh Codex session in the project, run get_huly_context. It returns sanitized runtime context: default workspace, default project, Huly URL host, auth mode, and package version.

Codex may show local stdio MCP servers as unauthenticated in /mcp. That label refers to MCP-level authentication, not Huly authentication. Use get_huly_context to confirm the downstream Huly auth mode is token or email_password.

Claude Code (project-scoped stdio)

Generate .mcp.json for Claude Code with literal routing values:

npx -y @bgx4k3p/huly-mcp-server --init-claude \
  --url https://your-huly-instance.com \
  --workspace my-workspace

Or route through environment variables instead:

npx -y @bgx4k3p/huly-mcp-server --init-claude \
  --url-env HULY_URL \
  --workspace-env HULY_WORKSPACE \
  --project-env HULY_PROJECT

When --url is omitted, --init-claude --workspace my-workspace writes HULY_URL as ${HULY_URL}.

Or add the server manually from a local source checkout:

claude mcp add huly \
  -e HULY_URL=https://your-huly-instance.com \
  -e HULY_TOKEN=your-token \
  -e HULY_WORKSPACE=my-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": "${HULY_URL}",
        "HULY_TOKEN": "${HULY_TOKEN}",
        "HULY_WORKSPACE": "my-workspace"
      }
    }
  }
}

For project-specific workspaces, keep secrets in environment variables. Use literal routing values when the repo maps to one Huly instance/workspace, or *-env flags when you want the runtime environment to select them. HULY_PROJECT is optional; set it only when the repo maps cleanly to one Huly project:

"env": {
  "HULY_URL": "${HULY_URL}",
  "HULY_TOKEN": "${HULY_TOKEN}",
  "HULY_WORKSPACE": "my-workspace",
  "HULY_PROJECT": "PROJ"
}

Or with email/password:

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

Generate Both Project Configs

npx -y @bgx4k3p/huly-mcp-server --init-all \
  --url https://your-huly-instance.com \
  --workspace my-workspace

With an optional default project:

npx -y @bgx4k3p/huly-mcp-server --init-all \
  --url https://your-huly-instance.com \
  --workspace my-workspace \
  --project PROJ

Or generate both configs with routing values read from runtime environment variables:

npx -y @bgx4k3p/huly-mcp-server --init-all \
  --url-env HULY_URL \
  --workspace-env HULY_WORKSPACE \
  --project-env HULY_PROJECT

--init-claude creates or updates .mcp.json while preserving other MCP servers. --init-codex creates .codex/config.toml for trusted Codex projects while preserving unrelated Codex settings. Existing Huly entries are not replaced unless --force is passed.

Streamable HTTP (n8n, VS Code, remote clients)

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

The image runs the server on Node.js 26 and the default Alpine variant. It serves MCP over HTTP on port 3001 by default; the command can be overridden for stdio. This runtime choice does not affect npm/npx installations, which use the host's supported Node.js version. Dependencies are installed at build time; npm is removed from the runtime image.

docker build --pull -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

Verify the Connection

In any MCP client, call get_huly_context first. It confirms the active workspace, optional project, Huly URL host, auth mode, and package version without exposing secrets.

Then ask your MCP client things like:

• "List my issues in the PROJ 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}.

Configuration Reference

Environment Variables

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

Compact responses are minified and omit unreviewed raw SDK fields under extra, while preserving documented null and empty values. Set _meta["com.huly/responseMode"] on one tool call to override its mode. HTTP clients can set Huly-Response-Mode while creating a session; this is captured for that session only. raw returns full SDK fields as minified JSON.

Tool profiles reduce the catalog sent to the model at session startup. full exposes all 91 tools, project exposes the 64 workspace/project tools, and read exposes 39 read-only tools. For Claude research/review sessions, set HULY_TOOL_PROFILE=read; use project when the session must edit issues, and use full only for workspace/account administration. Calls outside the active profile fail instead of being silently routed.

HTTP Server Authentication

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 does not use this token — stdio is inherently local.

Multi-Workspace

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.

Network Configurations

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

Protected deployments and access gateways

If your Huly deployment sits behind an identity-aware proxy or access gateway that expects extra request headers, configure those headers with environment variables. This works for Cloudflare Access service tokens, oauth2-proxy, Authelia, GCP IAP, and custom API gateways.

The configured headers are added to Huly-bound HTTP requests and to the WebSocket upgrade. Huly authentication is still separate: keep using HULY_TOKEN or HULY_EMAIL/HULY_PASSWORD for Huly itself.

JSON form:

HULY_OUTBOUND_HEADERS_JSON='{"X-Service-Token":"abc123","X-Tenant":"team-foo"}'

Discrete form (one env var per header — easier for secret managers):

HULY_OUTBOUND_HEADER_X_SERVICE_TOKEN=abc123
HULY_OUTBOUND_HEADER_X_TENANT=team-foo

Header names from discrete env vars are normalized by stripping the prefix and replacing _ with - (HULY_OUTBOUND_HEADER_X_API_KEY → X-API-KEY). HTTP header names are case-insensitive, so the wire result is equivalent to any pretty-cased form your gateway documents.

Example: Cloudflare Access service token

HULY_OUTBOUND_HEADER_CF_ACCESS_CLIENT_ID=xxx.access
HULY_OUTBOUND_HEADER_CF_ACCESS_CLIENT_SECRET=yyy

Scope and operator responsibility

Headers are sent to HULY_URL and to every origin advertised in Huly's own /config.json response (accounts, collaborator, transactor, files, upload, rekoni, etc.). You are responsible for ensuring those advertised origins are services you control and trust to receive these headers.

Outbound header values are bearer-style credentials. If /config.json advertises a *_URL pointing at a third-party origin you do not control, such as a public CDN or vendor SaaS, the configured headers will be transmitted there. Review your Huly server's /config.json before enabling this feature.

Authorization, Cookie, and Proxy-Authorization are rejected at startup — they would collide with Huly's own bearer token. Use a gateway that signals identity via a separate header.

Fallback for gateways without service-token support

Prefer header-based service authentication. Use bypass policies only as a last resort, scoped narrowly to Huly API paths, and only when you accept that those paths are reachable without the gateway's identity check:

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

Testing

Uses Node.js built-in node:test and node:assert — no test framework dependencies. The live integration suite runs twice: once with WebSocket transport and once with REST transport. Focused unit suites cover dispatch, MCP tool metadata, and project config generation.

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

Test coverage:

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

Maintenance

Maintenance scripts live in the repository scripts/ directory. They are source-checkout tools and are not included in the published npm package.

Repair Reported Time Totals

Versions before 2.4.3 could write string-concatenated reportedTime values when logging time against issues that already had string numeric fields. The repair script recomputes each issue's reportedTime from its TimeSpendReport records, which are the source of truth.

Always review the dry-run first:

node scripts/repair-reported-time.mjs

Apply after reviewing the output:

node scripts/repair-reported-time.mjs --apply

Optional filters:

node scripts/repair-reported-time.mjs --workspace=my-workspace
node scripts/repair-reported-time.mjs --workspace=my-workspace --project=PROJ

Back up Huly data before applying repairs in production.

Development and Publishing

For local development:

npm install
npm run lint
node --test test/initCodex.test.mjs test/mcpShared.test.mjs

The custom pack script bundles only the Huly SDK packages needed at runtime and prunes UI/frontend bloat from the published tarball:

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

Architecture

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 (Codex, Claude Code)
  server.mjs    # MCP Streamable HTTP entry point (n8n, VS Code, remote)
  initCodex.mjs # Project config helpers for Codex and Claude Code
  index.mjs     # CLI entry point — --get-token, --init-* modes + MCP re-export

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

Response Format

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

API Reference

Full list of all MCP tools available through this server.

Account and Workspace Management

Invites

Integrations, Mailboxes, Social IDs, Subscriptions

Projects

Issues

Stored Issue Templates

These tools manage persistent Huly templates, including embedded child templates, labels, task types, related documents, and descriptions. The Huly UI can use these templates to create issues. create_issues_from_template is the separate predefined workflow generator.

Preserve returned child IDs when editing child templates. Empty assignee, component, or milestone values clear those fields. An empty task type resets to the project's default type.

Project members and owners accept exact member names or account UUIDs. Creation always includes the creator as a member and owner. Updates replace supplied sets; use include: ["members", "owners", "defaults"] to read them back. A project must retain an owner, and a private project must retain an owner who is also a member. Removing a member also removes their project-role assignments.

Labels

Relations

Components

Milestones

Members

Comments

Time Tracking

Metadata

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.

Projections and explicit expansions

list_issues and get_issue accept fields for base-field projection and include for granular expansions. Supported expansions are description, comments, activity, timeReports, relations, blockedBy, and children. Each collection has an independent limit (default 20, maximum 100) and returns *Count/*Truncated metadata. List description previews default to 500 characters; use description_preview_chars: 0 for full list descriptions. get_issue returns the complete description by default and never silently truncates it.

Compact issue lists use a concise default field projection, while raw lists retain the complete base-field set. include is the only expansion mechanism; there is no broad-detail boolean shortcut.

Projects accept include: [milestones, components, labels, members, owners, defaults] and fetch only the selected related collections. Milestones accept include: [issues]; issues_limit defaults to 20 and caps at 100, with issuesCount and issuesTruncated in the result.

For measured Claude parent/subagent patterns, optional MCP tool scoping, and prompt examples, see Token-efficient Claude workflows. For the breaking v3 API changes, see the v3 upgrade guide; the release validation matrix records the regression gates.

CRUD Coverage

Issue Templates

Use create_issues_from_template:

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

Security

The Huly SDK brings transitive Tiptap 2 and Svelte 4 dependencies with moderate advisories. Their published fixes require major versions outside the SDK's supported dependency ranges. This server does not render Svelte components, but it does process rich text through Huly's Tiptap packages; these findings must not be dismissed as universally unexploitable. See SECURITY.md for the current dependency assessment.

License

MIT