Huly Mcp

Huly MCP

[](https://www.npmjs.com/package/@firfi/huly-mcp) [](https://www.npmjs.com/package/@firfi/huly-mcp) [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io) [](https://www.typescriptlang.org/) [](https://glama.ai/mcp/servers/@dearlordylord/huly-mcp) [](https://github.com/dearlordylord/huly-mcp)[](https://monadical.com)

Huly MCP is a feature-complete MCP server for Huly integration. Published on npm as @firfi/huly-mcp.

Installation

The standard configuration works with most MCP clients:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Tool Exposure Defaults

By default (HULY_TOOL_MODE=auto), Huly MCP optimizes for current MCP clients by avoiding a 470-tool eager list. Exact claude-code sessions receive native Huly tools. Codex, Cursor, Windsurf, Copilot, OpenCode, Claude AI/Desktop-style clients, and unknown clients receive a small proxy surface: list_tool_categories, search_tools, get_tool_schema, and invoke_tool.

Exact native tool names still dispatch when a client calls them directly, but many clients only call tools returned by tools/list. Set HULY_TOOL_MODE=native to make every Huly tool appear first-class, or use TOOLSETS / TOOLS to pin frequently used native tools while keeping proxy discovery available.

Codex

Use Codex's MCP manager:

codex mcp add huly \
  --env HULY_URL=https://huly.app \
  --env HULY_EMAIL=your@email.com \
  --env HULY_PASSWORD=yourpassword \
  --env HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest

Or add it directly to ~/.codex/config.toml:

[mcp_servers.huly]
command = "npx"
args = ["-y", "@firfi/huly-mcp@latest"]

[mcp_servers.huly.env]
HULY_URL = "https://huly.app"
HULY_EMAIL = "your@email.com"
HULY_PASSWORD = "yourpassword"
HULY_WORKSPACE = "yourworkspace"

Claude Code

claude mcp add huly \
  -e HULY_URL=https://huly.app \
  -e HULY_EMAIL=your@email.com \
  -e HULY_PASSWORD=yourpassword \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest

Or add to ~/.claude.json using the standard config above.

Claude Desktop

Add the standard config to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

VS Code

Add with Command Palette → "MCP: Add Server", or put this in a VS Code MCP config such as .vscode/mcp.json. Do not commit workspace config files that contain real credentials.

{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Cursor

Add the standard config to ~/.cursor/mcp.json, or via Settings → Tools & Integrations → New MCP Server.

Windsurf

Add the standard config to your Windsurf MCP configuration file.

OpenCode

Open the global configuration file (~/.config/opencode/opencode.json) and merge this entry into your config:

{
  "mcp": {
    "huly": {
      "type": "local",
      "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
      "environment": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Updating

The @latest tag asks the package runner for the newest version. Some MCP clients keep server processes or resolved installs alive, so restart or re-add the server when updating:

| Client | How to update | |--------|--------------| | Codex | codex mcp remove huly then re-add with the install command above. If your password has shell-sensitive characters, edit ~/.codex/config.toml directly instead | | Claude Code | claude mcp remove huly then re-add with the install command above | | Claude Desktop | Restart the app (it runs npx on startup) | | VS Code / Cursor | Restart the MCP server from the command palette/configured client or reload the window | | OpenCode | Restart OpenCode or start a new session after config changes | | npx (manual) | npx -y @firfi/huly-mcp@latest — the -y flag auto-confirms install prompts |

HTTP Transport

By default, the server uses stdio transport. For HTTP transport (Streamable HTTP):

HULY_URL=https://huly.app \
HULY_EMAIL=your@email.com \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @firfi/huly-mcp@latest

Server listens on http://127.0.0.1:3000/mcp by default.

Configure with MCP_HTTP_PORT and MCP_HTTP_HOST:

MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-mcp@latest

HTTP MCP Protocol Support

The HTTP server supports both the existing SDK initialize-compatible Streamable HTTP flow and the 2026 stateless HTTP flow at the same /mcp endpoint. Dispatch is per request:

• Requests with MCP-Protocol-Version: 2026-07-28, matching _meta.io.modelcontextprotocol/protocolVersion, or server/discover use the 2026 stateless dispatcher.
• Requests without 2026 protocol signals continue through the SDK transport for compatibility with existing clients.

The 2026 path requires one JSON-RPC message per POST, Accept: application/json, text/event-stream, Mcp-Method, method-specific Mcp-Name, and per-request _meta.io.modelcontextprotocol/* client metadata. Huly credentials are still configured separately through env vars or supported x-huly-* headers.

For hosted or tunneled HTTP deployments, you can require an MCP endpoint bearer token:

MCP_TRANSPORT=http \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
npx -y @firfi/huly-mcp@latest

HTTP clients must then send:

Authorization: Bearer 

MCP_AUTH_TOKEN protects only the MCP HTTP /mcp endpoint. It is unrelated to HULY_TOKEN, does not authenticate to Huly, and does not replace HULY_EMAIL / HULY_PASSWORD / HULY_TOKEN. Huly credentials are still required through process env vars or, for hosted URL deployments, the supported x-huly-* headers. Stdio deployments do not use MCP_AUTH_TOKEN.

Hosted HTTP Header Configuration

For hosted URL deployments, keep the server process configured with MCP_TRANSPORT=http. A hosting layer can forward per-session Huly credentials as request headers, so one hosted server can serve different Huly workspaces without process-wide HULY_* env vars.

Supported v1 headers:

| Header | Required | Description | |--------|----------|-------------| | x-huly-url | Yes | Huly instance URL | | x-huly-workspace | Yes | Workspace identifier | | x-huly-token | Yes | Huly API token | | x-huly-connection-timeout | No | Connection timeout in ms |

If any x-huly-* header is present, all required headers must be present. Missing values are not filled from environment variables. Email/password auth is not supported in hosted header configuration v1.

For a Smithery publish schema example, see [docs/SMITHERYURLPUBLISH.md](docs/SMITHERYURLPUBLISH.md).

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | HULY_URL | Yes | Huly instance URL | | HULY_EMAIL | Auth | Account email | | HULY_PASSWORD | Auth | Account password | | HULY_TOKEN | Auth* | API token (alternative to email/password) | | HULY_WORKSPACE | Yes | Workspace identifier | | HULY_CONNECTION_TIMEOUT | No | Connection timeout in ms. Omit to use the package default. | | MCP_TRANSPORT | No | Transport type: stdio (default) or http | | MCP_HTTP_PORT | No | HTTP server port (falls back to PORT, then 3000) | | MCP_HTTP_HOST | No | HTTP server host. Omit to bind to the package default loopback host. | | MCP_AUTH_TOKEN | No | Optional bearer token required by HTTP clients for /mcp. This protects the MCP endpoint only; it is not a Huly API token. | | HULY_TOOL_MODE | No | Tool exposure mode: auto (default), native, or proxy. auto keeps exact claude-code native and resolves Codex, Cursor, Windsurf, Copilot, opencode, Claude AI, and unknown clients to proxy mode. | | PROXY_OUTPUT_STRICT | No | Proxy candidate strictness: false (default) keeps proxy discovery broad; true makes active TOOLSETS / TOOLS a hard allow-list for proxy search, schema lookup, and invocation. | | TOOLSETS | No | Comma-separated tool categories to expose. If neither TOOLSETS nor TOOLS is set, all native Huly tools are exposed. Example: issues,projects,search | | TOOLS | No | Comma-separated exact tool names to expose in addition to selected toolsets. Example: list_documents,create_issue |

*Auth: Provide either HULY_EMAIL + HULY_PASSWORD or HULY_TOKEN.

Built-in Diagnostic Tools

get_version returns the current server version and latest npm version.

get_huly_context returns sanitized runtime/configuration context for the current MCP session without connecting to Huly. It reports package version, transport, auth mode, sanitized Huly URL origin/host/protocol, workspace, timeout, config sources, native tool scope filtering, and resolved native/proxy tool exposure. Tokens, passwords, email values, credential headers, URL paths, URL query strings, and URL credentials are never returned.

MCP Resources

The server exposes read-only MCP Resources as JSON context for clients that support resources/read.

| Template | Name | Description | MIME Type | |----------|------|-------------|-----------| | huly://projects/{project} | huly-project | Read full details for a Huly tracker project by project identifier, for example huly://projects/HULY. | application/json | | huly://issues/{issue} | huly-issue | Read full details for a Huly issue by full issue identifier, for example huly://issues/HULY-123. | application/json | | huly://projects/{project}/issues/{issue} | huly-project-issue | Read full details for a Huly issue by project identifier and issue number, for example huly://projects/HULY/issues/123. | application/json |

resources/list returns concrete active project resources. Issue resources are template-based: use resources/templates/list to discover supported issue URI templates, then read a known issue URI.

Backlog

Feature backlog and SDK parity notes live in [docs/BACKLOG.md](docs/BACKLOG.md).

Available Tools

When resolved tool exposure is proxy, clients see the built-in tools plus these proxy meta-tools. Native Huly tools are then discovered and invoked through the proxy candidate catalog. Exact native tool names also dispatch when a client calls them directly, subject to PROXY_OUTPUT_STRICT scope rules, but hidden native tools are not advertised through tools/list.

Proxy Meta-Tools

| Tool | Description | |------|-------------| | list_tool_categories | Lists Huly tool categories available through this proxy. Use this first when you need a broad map of capabilities before searching for a specific Huly tool. | | search_tools | Searches the current proxy-visible Huly tool catalog by tool name, category, description, and parameter names. Returns exact tool names plus required and optional parameter names for single-call follow-up with gettoolschema or invoketool. | | get_tool_schema | Returns the exact input and output schema for one proxy-visible Huly tool. Use this before invoketool when you are not certain about required argument names or result shape. | | invoke_tool | Invokes one proxy-visible Huly tool by exact name with its arguments. This tool can call read or write Huly operations; check gettoolschema and the target tool annotations when safety matters. |

TOOLSETS categories: projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendar, time tracking, search, associations, activity, notifications, workspace, approvals, boards, cards, collaborators, custom-fields, drive, inventory, labels, leads, templates, planner, preferences, processes, recruiting, sdk-discovery, spaces, tag-categories, tags, task-management, test-management, user-statuses, views, virtual-office

Projects

| Tool | Description | |------|-------------| | list_project_target_preferences | List low-level per-project tracker target preference records. These Huly ProjectTargetPreference records are attached to projects and used by tracker UI/workflows to remember target-related preference props. Omit project to list recent preferences across projects, or pass a project identifier to inspect one project's preference. Props are SDK-open key/value payloads. | | upsert_project_target_preference | Create or update the low-level ProjectTargetPreference record for a project. This refreshes usedOn and merges SDK-open target preference props by key. Use for tracker SDK parity or advanced administration; ordinary project and issue workflows usually do not need this tool. | | list_projects | List all Huly projects. Returns projects sorted by name. Supports filtering by archived status. | | get_project | Get full details of a Huly project including its statuses. Returns project name, description, archived flag, default status, and all available statuses. | | list_statuses | List all issue statuses for a Huly project with workflow category and default info. Returns status name, category, and isDefault. Use this to discover valid statuses before creating or updating issues. | | create_project | Create a new Huly tracker project. Idempotent: returns existing project if one with the same identifier already exists (created=false). Identifier must be 1-5 uppercase alphanumeric chars starting with a letter. | | update_project | Update a Huly project. Only provided fields are modified. Set description to null to clear it. | | delete_project | Permanently delete a Huly project. All issues, milestones, and components in this project will be orphaned. This action cannot be undone. |

Issues

| Tool | Description | |------|-------------| | preview_deletion | Preview the impact of deleting a Huly entity before actually deleting it. Shows affected sub-entities, relations, and warnings. Supports issues, projects, components, and milestones. Use this to understand cascade effects before calling a delete operation. | | list_components | List components in a Huly project. Components organize issues by area/feature. Returns components sorted by modification date (newest first). | | get_component | Retrieve full details for a Huly component. Use this to view component content and metadata. | | create_component | Create a new component in a Huly project. Components help organize issues by area/feature. Description supports markdown. Markdown links to current-workspace Huly browse URLs with class, id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. Returns the created component ID and label. | | update_component | Update fields on an existing Huly component. Only provided fields are modified. Description supports markdown. Markdown links to current-workspace Huly browse URLs with class, id, and label become native Huly references; external URLs and other-workspace browse URLs stay normal links. | | set_issue_component | Set or clear the component on a Huly issue. Pass null for component to clear it. | | delete_component | Permanently delete a Huly component. This action cannot be undone. | | `list_issu

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dearlordylord
• Source: dearlordylord/huly-mcp
• License: MIT
• Homepage: https://huly-mcp.dearlordylord.com

Install and usage instructions live in the source repository linked above.