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.
• Development and Publishing: tests, linting, and package publishing.
• API Reference: available MCP tools and response conventions.

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

For backward compatibility, omitting --url also 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

For backward compatibility, --init-claude --workspace my-workspace still 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

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

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

Variable	Required	Default	Description
Huly Connection
HULY_URL	No	http://localhost:8087	Huly instance URL
HULY_TOKEN	No	-	Auth token (alternative to email/password)
HULY_EMAIL	No	-	Huly login email (required if no token)
HULY_PASSWORD	No	-	Huly login password (required if no token)
HULY_WORKSPACE	Yes*	-	Default workspace slug
HULY_PROJECT	No	-	Optional default project identifier for project-scoped tools
HULY_TRANSPORT	No	ws	SDK transport: ws (WebSocket) or rest (REST API)
HULY_POOL_TTL_MS	No	1800000	Connection pool TTL in ms (30 min)
HULY_OUTBOUND_HEADERS_JSON	No	-	JSON object of extra headers for protected Huly origins
HULY_OUTBOUND_HEADER_*	No	-	One extra outbound header per env var, with _ converted to -
HTTP Server
PORT	No	3001	HTTP server port (auto-assigns if taken)
MCP_AUTH_TOKEN	No	-	Bearer token for HTTP auth (disabled if unset)
HULY_RATE_LIMIT	No	200	Max requests per minute per IP
ALLOWED_ORIGINS	No	*	CORS allowed origins (comma-separated)

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

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:

Suite	Description
Unit	Constants, ID parsing, rate limiting, auth logic
Integration	Full CRUD lifecycle against live Huly
Dispatch	Schema to dispatch to client param forwarding for all tools
MCP metadata	Tool registration, get_huly_context, default project schemas
Project config	--init-claude, --init-codex, --init-all helpers
Account-level	Workspaces, profile, social IDs
Mock	Destructive ops, token auth via mocks
Streamable HTTP	MCP protocol over HTTP: init, tools, resources, auth, rate limiting

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

---

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

Tool	Description
get_huly_context	Show sanitized runtime context: default workspace, default project, Huly URL host, auth mode, and package version
list_workspaces	List all accessible workspaces
get_workspace_info	Get workspace details by slug
create_workspace	Create a new workspace
update_workspace_name	Rename a workspace
delete_workspace	Permanently delete a workspace
get_workspace_members	List workspace members and roles
update_workspace_role	Change a member's role
get_account_info	Get current user's account info
get_user_profile	Get current user's profile
set_my_profile	Update profile fields
change_password	Change password
change_username	Change username

Invites

Tool	Description
send_invite	Send workspace invite email
resend_invite	Resend pending invite
create_invite_link	Generate shareable invite link

Integrations, Mailboxes, Social IDs, Subscriptions

Tool	Description
list_integrations / get_integration / create_integration / update_integration / delete_integration	Full CRUD for integrations
list_mailboxes / create_mailbox / delete_mailbox	Mailbox management
find_person_by_social_key / get_social_ids / add_email_social_id	Person/social ID management
list_subscriptions	List account subscriptions

Projects

Tool	Description	Text Format
list_projects	List all projects (supports include_details)	--
get_project	Get project by identifier (supports include_details)	--
create_project	Create a new project	descriptionFormat: md/html/plain
update_project	Update project name, description, privacy, default assignee	descriptionFormat: md/html/plain
archive_project	Archive or unarchive a project	--
delete_project	Permanently delete a project	--
summarize_project	Aggregated project metrics and health	--

Issues

Tool	Description	Text Format
list_issues	List issues with filters (supports include_details)	--
get_issue	Get full issue details (supports include_details)	--
create_issue	Create a new issue	descriptionFormat: md/html/plain
update_issue	Update issue fields	descriptionFormat: md/html/plain
delete_issue	Permanently delete an issue	--
search_issues	Full-text search across projects	--
get_my_issues	Issues assigned to current user	--
batch_create_issues	Create multiple issues at once	descriptionFormat per item
move_issue	Move issue between projects	--
create_issues_from_template	Create from predefined templates	--

Labels

Tool	Description
list_labels	List all labels in the workspace
get_label	Find a label by name
create_label	Create a new label with optional color
update_label	Update label name, color, or description
delete_label	Permanently delete a label
add_label	Add a label to an issue
remove_label	Remove a label from an issue

Relations

Tool	Description
add_relation	Add bidirectional "related to" link
add_blocked_by	Add "blocked by" dependency
set_parent	Set parent issue (epic/task hierarchy)

Components

Tool	Description	Text Format
list_components	List components in a project	--
get_component	Find a component by name	--
create_component	Create a new component (optional lead)	descriptionFormat: md/html/plain
update_component	Update component name, description, or lead	descriptionFormat: md/html/plain
delete_component	Delete a component	--

Milestones

Tool	Description	Text Format
list_milestones	List milestones (supports include_details)	--
get_milestone	Get milestone details (supports include_details)	--
create_milestone	Create a new milestone	descriptionFormat: md/html/plain
update_milestone	Update milestone fields	descriptionFormat: md/html/plain
delete_milestone	Delete a milestone	--
set_milestone	Set or clear milestone on an issue	--

Members

Tool	Description
list_members	List all active workspace members
get_member	Find a member by name (fuzzy match)

Comments

Tool	Description	Text Format
list_comments	List all comments on an issue	--
get_comment	Get a specific comment by ID	--
add_comment	Add a comment to an issue	format: md/html/plain
update_comment	Update comment text	format: md/html/plain
delete_comment	Delete a comment	--

Time Tracking

Tool	Description	Text Format
log_time	Log actual time spent	descriptionFormat: md/html/plain
list_time_reports	List time reports for an issue	--
get_time_report	Get a specific time report by ID	--
delete_time_report	Delete a time report	--

Metadata

Tool	Description
list_task_types	List task types for a project
get_task_type	Find a task type by name
list_statuses	List issue statuses
get_status	Find a status by name

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.

include_details Flag

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

Tool	Extra data when include_details=true
get_issue	Comments, time reports, relations, children
list_issues	Descriptions, comments, time reports, relations, children (limit reduced to 50)
get_project	Milestones, components, labels, members
list_projects	Milestones, components, labels, members per project (limit 20)
get_milestone	Full list of issues in the milestone
list_milestones	Issues list per milestone

CRUD Coverage

Entity	Create	Read	List	Update	Delete
Project	create_project	get_project	list_projects	update_project	delete_project
Issue	create_issue	get_issue	list_issues	update_issue	delete_issue
Label	create_label	get_label	list_labels	update_label	delete_label
Component	create_component	get_component	list_components	update_component	delete_component
Milestone	create_milestone	get_milestone	list_milestones	update_milestone	delete_milestone
Comment	add_comment	get_comment	list_comments	update_comment	delete_comment
Time Report	log_time	get_time_report	list_time_reports	--	delete_time_report
Member	--	get_member	list_members	--	--
Status	--	get_status	list_statuses	--	--
Task Type	--	get_task_type	list_task_types	--	--

Issue Templates

Use create_issues_from_template:

Template	Creates
feature	Parent + design/implement/test/docs/review sub-issues
bug	Parent + reproduce/root-cause/fix/regression-test sub-issues
sprint	Planning/standup/review/retro ceremony issues
release	Parent + freeze/QA/changelog/staging/prod/verify sub-issues

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

---

Security

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.

---

License

MIT