dearlordylord/huly-mcp

**Huly MCP** is a feature-complete MCP server for Huly integration. Published on npm as @firfi/huly-mcp.
It connects to Huly Platform deployments and should also work with the Platform Collective and TraceX forks. Intabia 0.8.33 / model 0.8.4 has been compatibility-tested; known gaps are tracked in issue #279. Fork support remains unofficial.
Huly CLI Alternative
Looking for a Huly CLI, terminal-native Huly integration, or a scripting and automation alternative to running an MCP server? Huly CLI is a feature-complete command-line interface for Huly, published as @firfi/huly-cli, with full Huly operation parity with Huly MCP. It exposes the same Huly operations as native, schema-aware commands with human-readable or JSON output, file-backed inputs, uploads, and downloads.
Huly MCP and Huly CLI are maintained together in this monorepo and derive from the same shared operation registry, keeping operation inputs, outputs, warnings, and typed failures aligned. See the Huly CLI documentation for the complete generated command reference, or browse CLI examples, Huly automation patterns, and the Huly MCP vs CLI comparison.
Installation
Node.js requirement
Huly MCP requires **Node.js 22.19.0 or later**. MCP clients do not provide a Node.js runtime: node, npx,
and the #!/usr/bin/env node package executable resolve Node.js from the environment in which the MCP client
runs. Check that environment before installation:
If an MCP client starts Huly MCP with an older runtime, Huly MCP initializes a diagnostic-only MCP surface instead
of loading the incompatible application. Its server instructions and get_huly_startup_diagnostic tool report the
detected executable and required version, and the same unsupported Node.js runtime diagnostic is written to
stderr. Upgrade Node.js or configure the MCP server command to use the absolute path of a compatible Node.js
executable, then restart the MCP server. Huly operations remain unavailable until the runtime is upgraded.
The standard configuration uses a Huly API token and works with most MCP clients:
Prefer a managed API token created in Huly account settings when the target deployment supports it. Managed tokens
are bound to one workspace, assigned an expiry, and can be revoked without changing the account password. They still
inherit the account's full rights in that workspace, so use a dedicated integration account with only the workspace
role, space memberships, and data access the automation needs. Older Huly deployments may not expose managed token
settings; email/password authentication remains available as a compatibility fallback.
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:
Or add it directly to ~/.codex/config.toml:
Claude Code
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.
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:
Pi
Pi requires an MCP adapter. Install it, then use Huly MCP in auto mode with the four proxy tools
promoted into Pi's native tool list:
See the Pi setup guide for the user-global configuration, optional
TOOLSETS/TOOLS native pins, and verification steps.
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: