Home

huly-mcp-selfhost — technical documentation

huly-mcp-selfhost is an MCP server that connects AI clients (Claude Desktop, Claude Code, Cursor, …) to Huly — Huly Cloud or a self-hosted huly-selfhost instance. It talks to Huly through the native @hcengineering/* SDK over WebSocket and exposes 48 tools for issues, projects, documents, chat, attachments, statuses, organizations and more.

The README is the quick-start. This wiki is the detailed technical reference.

Versions These pages describe the multi-workspace release. It is included in:

• main and the Docker image jokeks2023/huly-mcp:latest (since PR #1)
• npm huly-mcp-selfhost 2.0.0 and later

huly-mcp-selfhost@1.0.0 is the older single-workspace release: it requires HULY_WORKSPACE and has no huly-mcp-selfhost executable. 2.0.0 is a major version because tools that change data now require workspace.

Pages

Page	What you find there
Getting Started	Install, first run, connecting a client
Authentication	Email + password, HULY_TOKEN, account token vs. workspace token
Multi-Workspace	One login, many workspaces: discovery, routing, isolation, rules for writes
Configuration	Every environment variable
Tools	Complete tool reference with workspace requirements and examples
Architecture	Account client, connection manager, workspace clients, WebSocket, /files storage
Security	Token handling, no credentials in URLs or tool results, remote deployment
Self-Hosted Huly	Using huly-selfhost: accounts URL, front URL, blob storage
Docker Deployment	Container image, mcp-proxy, .env, remote MCP
Development	Building, tests, adding tools, helper scripts
Troubleshooting	Error messages and what they mean

In one paragraph

You give the server account credentials (HULY_EMAIL + HULY_PASSWORD, or HULY_TOKEN). It logs in once, asks the account service which workspaces this account can use (getUserWorkspaces()), and opens a separate, cached WebSocket connection per workspace the first time a tool needs it (selectWorkspace()). There is no "current workspace": every tool names its target with a workspace argument, and every tool that changes data must name it. See Multi-Workspace.

Links

• Repository: https://github.com/JoKeks2023/huly-mcp
• npm: https://www.npmjs.com/package/huly-mcp-selfhost
• Docker Hub: https://hub.docker.com/r/jokeks2023/huly-mcp (mirrored at ghcr.io/jokeks2023/huly-mcp)
• Upstream (original project): https://github.com/varaprasadreddy9676/huly-mcp