huly-mcp-selfhost

Huly for AI agents. An MCP server for Huly — self-hosted or Huly Cloud — that lets Claude and other agents work in your workspaces: issues, epics, milestones, documents, chat, inbox, planner, test management and more. 227 tools, built for agent workflows and to spend as few tokens as possible.

Website · Quick start · Tools · Claude Code plugin · Changelog

Highlights

• Everything in Huly: tracker, documents, chat, inbox, activity, planner, calendar, GitHub PRs, contacts, drive, cards, templates, test management, recruiting, CRM, HR and more — plus read access to any Huly class.

• Made for agents: one-call overviews (my_day, standup, project_report, get_issue_context), start_work → finish_work, plans → epics with sub-issues, specs and meeting notes → issues, claims for parallel agents, and huly-mcp watch to hand issues to Claude from Huly.

• Few tokens: tools come in toolsets (default ≈11k tokens, everything ≈24k), optionally loaded on demand; pin a workspace for −10 %; compact outputs; wrong parameters are rejected with the valid list instead of silently ignored.

• Safe by default: every change names its workspace, risky tools ask first, writes can be limited to projects, optional audit log — and undo_changes reverses your last changes.

• Small and quick to install: one self-contained package of ~4 MB (900 kB download) — no 180 dependencies to fetch on the first npx.

• No telemetry. The server talks to your Huly server and nothing else: no analytics, no usage tracking, nothing to opt out of. (The only other request, the npm version check, runs when you call check_setup.)

• Claude Code plugin: /huly:setup asks once per repo how Huly is used there and writes the rules; skill, hooks and /huly:* commands. Guides and a setup prompt for every other MCP client too.

• Self-hosted first: document and description content, file uploads and internal URLs work on huly-selfhost; one account, all its workspaces.

Related MCP server: huly-mcp

Tokens, measured

What the model reads — measured on a real self-hosted project (≈60 issues):

Lists default to open items, empty fields are left out, and one call answers what would otherwise take four or five. Per call and question: costs.md.

Compared with another popular Huly MCP server

Same self-hosted Huly, same questions, the best parameters on both sides, measured 2026-11-11. For the other server only the text content is counted, not the duplicate JSON copy it also returns. Where we return more (components), it is because we include each component's description and code paths.

Quick start

You need Node.js 20+ and a Huly account — Huly Cloud or self-hosted.

Claude Code — install the plugin, then fill in its settings when asked:

/plugin marketplace add JoKeks2023/huly-mcp
/plugin install huly@huly-mcp

Then run /huly:setup in a repository. Details: Claude Code plugin.

Claude Desktop, Cursor, VS Code, Windsurf, Zed, … — add the server to your client's MCP config:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "huly-mcp-selfhost"],
      "env": {
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "your-password"
      }
    }
  }
}

• Self-hosted Huly: add "HULY_ACCOUNTS_URL": "https://huly.example.com/_accounts" and "HULY_FRONT_URL": "https://huly.example.com".

• Google/GitHub login (no password): run npx huly-mcp-selfhost setup and use HULY_TOKEN instead — see Authentication.

• One workspace? Add "HULY_WORKSPACE": "<slug>" — fewer tokens.

Config file locations and examples for each client: Compatible clients.

Server for a team or remote clients — huly-mcp-selfhost http or the Docker image; everyone logs in with their own Huly account in the browser (OAuth): see Team server over HTTP.

Then ask: "What's on my plate today?", "Plan the login redesign as an epic in WEB", "Write release notes for v1.2". More in Example prompts.

Claude Code plugin

The repo is also a Claude Code plugin marketplace. The plugin bundles the MCP server with a workflow skill, hooks and commands:

/plugin marketplace add JoKeks2023/huly-mcp
/plugin install huly@huly-mcp

Note: the plugin starts the npm package at exactly its own version (e.g. huly-mcp-selfhost@3.5.1; the plugin directory does not accept version ranges), so a plugin update brings the matching server. To try a local checkout instead: npm run build, then point plugin/.mcp.json at dist/index.js and start claude --plugin-dir ./plugin.

Claude Code then asks for your Huly settings (e-mail + password or token, and for self-hosted Huly the accounts and front URL; passwords and tokens go to the OS keychain).

Without the plugin, the same server works in Claude Code as a plain MCP server (see below); the MCP prompts (setup, start, finish, plan, triage, standup) and guide resources are available there too.

Command line

Every tool also works from the terminal — for scripts, CI and quick looks without a chat. Same login (HULY_* environment or --env-file), same safety rules (write scope, audit log, confirmation for hard-to-undo changes).

npm install -g huly-mcp-selfhost          # or: npx huly-mcp-selfhost <command>

huly-mcp tools issue                      # find tools
huly-mcp help list_issues                 # parameters, types, allowed values, defaults
huly-mcp get_issue PROJ-12                # one required parameter can be given directly
huly-mcp list_issues --project PROJ --due overdue --assignee null
huly-mcp create_issue -w acme --project PROJ --title "Fix login" --description-file notes.md
huly-mcp bulk_update_issues --identifiers PROJ-1 --identifiers PROJ-2 --status-name Done --yes
huly-mcp my_day --format json | jq -r .text

• Parameters come from the same schemas the MCP server sends to Claude, so help is always current. Names work as --project-identifier or --projectIdentifier; common short forms (--project, --status, --milestone, …) too. Values are read by type: numbers, true/false, null to clear, repeat a flag for lists, JSON for nested values. --json '{…}' or --input file.json (- = stdin) pass everything at once; --<text-param>-file reads a text value from a file.

• Hard-to-undo tools (deletes, bulk changes, moves) ask in a terminal; in scripts they run only with --yes.

• Exit codes: 0 ok · 1 the tool failed or was cancelled · 2 wrong usage (unknown tool or option — with a "did you mean …").

• Output: the tool's Markdown; --format json gives {"ok", "tool", "text"} (errors too). The Huly SDK's own logging is silenced; HULY_DEBUG=1 shows it on stderr.

• Shell completion for tools, options and allowed values: eval "$(huly-mcp completion zsh)" (or bash) in your shell profile.

Tools (227 total, grouped in toolsets)

All tools except list_workspaces take a workspace argument — required for every change, optional for reads when only one workspace is available.

Toolsets

Every tool schema is sent to the model in each session (Claude Desktop loads all of them up front), so tools are grouped and only the default toolsets are enabled unless you choose otherwise:

HULY_TOOLSETS=all                       # everything
HULY_TOOLSETS=tracker,documents,planner # just these ('core' = list_workspaces, check_setup and undo_changes, always on)

Load on demand (HULY_DYNAMIC_TOOLSETS=1): HULY_TOOLSETS becomes the starting set, and Claude loads more toolsets itself via enable_toolsets. Called without arguments, it lists every toolset with its tools; called with names, it loads them and tells the client that the tool list changed. With HULY_TOOLSETS=agent,inbox a session starts at ≈1.8k tokens instead of ≈9–11k. This needs a client that reloads the tool list on notifications/tools/list_changed: it is tested with the MCP SDK client, but not yet verified in Claude Desktop. Without the variable, nothing changes.

Context cost of tools/list (≈3.5 chars/token):

For comparison, 2.2.0 needed ≈12.8k tokens for 64 tools. Using one workspace? Set HULY_WORKSPACE — the workspace argument then disappears from every tool (−10%). Claude Code loads MCP tools on demand, so there even HULY_TOOLSETS=all costs little up front.

Agent workflow

Tools, resources and prompts for AI agents working on Huly issues (toolset agent):

Resources — huly://<workspace>/issue/<PROJ-12> and huly://<workspace>/document/<id>. Your open assigned issues are listed, so in Claude Code you can @-mention them. Guides for agents in any client: huly://guide/workflow (how to work with Huly), huly://guide/costs (cheapest call per question) and huly://guide/onboarding (bringing a project into Huly) and huly://guide/features (which Huly feature to use for what, and which toolset it needs) — the same text as the plugin skill.

Prompts — setup (ask how Huly is used for a project and write the rules for your project instructions), start, finish, plan, triage, standup (in Claude Code: /mcp__huly__start …).

Guard rails (environment):

Huly hands work to Claude: huly-mcp watch

huly-mcp watch turns Huly into the place where you give Claude work. It polls for open issues that carry a label (--label claude) or are assigned to the account it runs as (--assigned, the default), and for each one:

1. claims the issue (claim_issue), so a second watcher or agent skips it,

2. runs a command for it — by default claude -p in the current directory, with this MCP server attached and a prompt that says: read the issue, do the work, hand back with finish_work,

3. releases the claim if the run did not (finish_work releases it), and comments on the issue if the run failed or timed out.

cd ~/code/my-repo
npx huly-mcp-selfhost watch --workspace acme --project WEB --label claude --dry-run   # what would run
npx huly-mcp-selfhost watch --workspace acme --project WEB --label claude             # poll every 60 s

• Each issue runs once. A state file (~/.huly-mcp/watch-<workspace>.json) remembers it. To run it again, remove the label and add it again.

• The command is yours. --command takes any program; the placeholders {prompt} {issue} {title} {workspace} {agent} {trigger} {mcpConfig} are filled in per argument — no shell is involved, so issue titles cannot inject shell commands. The run also gets HULY_ISSUE, HULY_ISSUE_TITLE and HULY_WORKSPACE in its environment. Examples: a GitHub Action (--command "gh workflow run agent.yml -f issue={issue}"), or Claude with more tools (--command "claude -p {prompt} --mcp-config {mcpConfig} --allowedTools mcp__huly,Bash(npm test),Edit").

• Default command: claude -p {prompt} --mcp-config {mcpConfig} --strict-mcp-config --allowedTools mcp__huly --permission-mode acceptEdits. {mcpConfig} is a temporary MCP config that starts this server limited to the watched workspace; the credentials are passed through the environment, not written to the file.

• Unattended means careful. Runs get HULY_CONFIRM=strict unless you set it: deletes and other risky tools are refused, because nobody is there to confirm them. HULY_WRITE_PROJECTS limits which projects are watched and changed. Issue text reaches the agent as instructions — only watch projects whose writers you trust.

• Its own identity. Give the agent its own Huly account (invite e.g. claude@your-domain to the workspace) and start the watcher with that account's credentials (--env-file agent.env with HULY_EMAIL/HULY_PASSWORD or HULY_TOKEN). Then you hand work to Claude by assigning an issue to that user, and every comment, status change and claim shows up under its name instead of yours. --agent <name> (or HULY_AGENT_NAME) names it in claims.

• Other options: --interval <sec>, --timeout <min> (default 60), --once, --cwd <dir>, --prompt <template>, --state <file>. huly-mcp watch --help lists them all.

CI test results into Huly: huly-mcp junit

huly-mcp junit report.xml --project "App" imports a JUnit XML report as a test run in Huly's test management. Almost every test runner writes JUnit XML (Jest/Vitest with a JUnit reporter, pytest --junitxml, go-junit-report, Gradle, Maven Surefire, xcpretty). Suites and cases that do not exist yet are created; failed tests keep their message and stack trace. Then ask Claude "What is flaky in App?" (get_test_report) or "File bugs for today's failures in PROJ" (create_issue_from_test_result).

# .github/workflows/test.yml (after the test step)
- name: Report to Huly
  if: always()
  run: npx -y huly-mcp-selfhost junit reports/junit.xml --project "App" --run "CI ${{ github.ref_name }} #${{ github.run_number }}"
  env:
    HULY_URL: ${{ secrets.HULY_URL }}
    HULY_TOKEN: ${{ secrets.HULY_TOKEN }}
    HULY_WORKSPACE: my-workspace

Options: --run <name>, --parent-suite <suite>, --no-create (only existing cases), --fail-on-failures (exit code 1 when tests failed), --dry-run, --workspace. huly-mcp junit --help lists them.

Tool reference

Workspaces (one account, several workspaces)

A single Huly account can belong to several workspaces — e.g. a personal one and a team one. This server logs in once with your account credentials and discovers every workspace that account can access via the account service (getUserWorkspaces()). You don't configure a workspace in the environment.

• list_workspaces returns name, slug and id of every available workspace.

• Every other tool takes a workspace argument — the slug, the name or the id (case-insensitive): list_projects(workspace="jokeks2023"), get_issue(workspace="acme", identifier="PROJ-1"), log_time(workspace="jokeks2023", identifier="WEB-12", hours=2).

• Changes always require workspace. Every tool that creates, updates, deletes, links, sends, attaches or logs something has workspace as a required argument — the server never falls back to an implicit, default or "last used" workspace for a write.

• Reads may omit workspace only if exactly one workspace is available. With several, the call fails and lists the options.

• IDs are per workspace. PROJ-1, a document id or a comment id identifies something only together with its workspace — the same id can exist in two workspaces. Pass the same workspace you got the id from.

• Each workspace gets its own lazily opened, cached WebSocket connection with its own workspace token (via selectWorkspace()), so workspaces never share state.

Workspace slug: the part of the Huly URL after the domain: huly.app/workbench/myteam → myteam. You don't need to look it up — list_workspaces (or npx huly-mcp-selfhost setup) prints it.

HULY_WORKSPACE: pins the server to that one workspace. Tools then have no workspace argument at all, which saves ~10% of the tool-list tokens. Leave it unset to use all workspaces of the account.

Configuration

Authentication

Create a .env file in the project root (or pass via env in your client config). No workspace is needed in either option.

Option A — Email + password (recommended):

Works if you have a password set on your Huly account (Profile → Security → Change password).

HULY_EMAIL=your@email.com
HULY_PASSWORD=yourpassword

Option B — Token (SSO accounts: Google/GitHub):

npx huly-mcp-selfhost setup                                  # Huly Cloud
npx huly-mcp-selfhost setup --url https://huly.example.com   # self-hosted

The wizard asks for your Huly address (unless --url or HULY_ACCOUNTS_URL is set), sends a one-time code to your email and lists the workspaces the account can access (a discovery test). It then prints the token and the URLs to paste into your client — for the Claude Code plugin: /plugin → huly → configure. In a checkout of this repo, npm run setup does the same and saves the token as HULY_TOKEN in .env.

HULY_TOKEN=your-token-here

A token copied from the browser (DevTools → Application → Local Storage → token) also works, but may be scoped to the single workspace open in that tab. If the account service refuses to list workspaces for such a token, the server falls back to that one workspace. Use npx huly-mcp-selfhost setup for full multi-workspace discovery.

Tokens expire after some time. If you get an auth error, run npx huly-mcp-selfhost setup again or switch to email + password.

Option C — API token (Huly → Settings → API tokens; in Huly's development branch since 2026-08, not yet in every release or self-hosted install): bound to one workspace, with an expiry date, revocable without changing your password — the best choice for agents and CI. Use it as HULY_TOKEN. The server keeps it to its own workspace (even where Huly itself would allow switching), checks the expiry up front, and check_setup warns two weeks before it runs out. Tested against Huly's token format, not yet against a live server that issues such tokens.

Something not working? Ask Claude to run check_setup: version (and whether a newer one exists), login, workspaces, whether the front URL is reachable and which settings are active — without printing secrets.

Self-hosted Huly:

HULY_ACCOUNTS_URL=https://your-huly-instance.com/_accounts   # login + workspace discovery
HULY_FRONT_URL=https://your-huly-instance.com                # document content + file uploads

Compatible clients

The same MCP server works across all major AI coding tools. All examples use email + password and the npm package via npx; for SSO accounts replace the two credentials with "HULY_TOKEN": "your-token" (see Authentication). To run a local build instead, replace npx + args with node + ["/absolute/path/to/huly-mcp/dist/index.js"].

Self-hosted: add HULY_ACCOUNTS_URL and HULY_FRONT_URL to every env block below.

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "huly-mcp-selfhost"],
      "env": {
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "your-password"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code (CLI)

claude mcp add huly \
  -e HULY_EMAIL=you@example.com \
  -e HULY_PASSWORD=your-password \
  -- npx -y huly-mcp-selfhost

Add --scope project (writes .mcp.json, shared with the repo — don't commit secrets) or --scope user (all your projects) after add huly. Verify with claude mcp list.

Cursor

Create or edit ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "huly-mcp-selfhost"],
      "env": {
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "your-password"
      }
    }
  }
}

The tools appear in the Agent panel under MCP.

Windsurf

Create or edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "huly-mcp-selfhost"],
      "env": {
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "your-password"
      }
    }
  }
}

Refresh the MCP servers in the Cascade panel.

VS Code — Cline

Cline → MCP Servers → Installed → Configure MCP Servers (opens cline_mcp_settings.json):

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "huly-mcp-selfhost"],
      "env": {
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "your-password"
      },
      "disabled": false
    }
  }
}

VS Code / JetBrains — Continue

Add to ~/.continue/config.yaml (MCP tools are available in Agent mode):

mcpServers:
  - name: huly
    command: npx
    args: ["-y", "huly-mcp-selfhost"]
    env:
      HULY_EMAIL: you@example.com
      HULY_PASSWORD: your-password

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "huly": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "huly-mcp-selfhost"],
      "env": {
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "your-password"
      }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.huly]
command = "npx"
args = ["-y", "huly-mcp-selfhost"]
env = { HULY_EMAIL = "you@example.com", HULY_PASSWORD = "your-password" }

or: codex mcp add huly --env HULY_EMAIL=you@example.com --env HULY_PASSWORD=your-password -- npx -y huly-mcp-selfhost

Any other MCP-compatible client

The server uses standard stdio transport:

• command: npx with args ["-y", "huly-mcp-selfhost"], or node with ["/absolute/path/to/huly-mcp/dist/index.js"]

• env: HULY_EMAIL + HULY_PASSWORD (or HULY_TOKEN); self-hosted also HULY_ACCOUNTS_URL + HULY_FRONT_URL — see Configuration

For network access (HTTP/SSE) use the Docker image.

Running the server

npx (recommended)

Every client example uses "command": "npx", "args": ["-y", "huly-mcp-selfhost"]. Pin a version (huly-mcp-selfhost@3.5.1) if you want updates only when you choose.

From source

git clone https://github.com/JoKeks2023/huly-mcp.git
cd huly-mcp
npm ci && npm run build

Then use "command": "node", "args": ["/absolute/path/to/huly-mcp/dist/index.js"].

Docker

For deployments where the MCP server needs to be reachable over the network (behind a reverse proxy, remote MCP clients, etc.) rather than launched locally per-client, a prebuilt image is published to Docker Hub and GHCR for every release, for linux/amd64 and linux/arm64:

docker pull jokeks2023/huly-mcp:latest   # latest release; also :3, :3.1, :3.1.0
# also mirrored at ghcr.io/jokeks2023/huly-mcp:latest
# :edge = latest build from main

Or with Compose — copy .env.example to .env, fill in your credentials (no workspace needed), then:

docker compose up -d

The container wraps the server with mcp-proxy to expose it over HTTP/SSE at :8000/sse, since standard MCP stdio transport can't be reached over a network directly. Behind a reverse proxy or on a public hostname, set MCP_ALLOWED_HOSTS to the host name(s) clients use, e.g. MCP_ALLOWED_HOSTS=huly-mcp.example.com. Otherwise mcp-proxy only accepts localhost and answers 421 Invalid Host header. See Dockerfile / docker-compose.yml.

Team server over HTTP

huly-mcp-selfhost http serves MCP over Streamable HTTP at /mcp (health check /healthz) — no proxy, one long-lived session per client, so logins and connections are reused (the first call of a session takes ~0.2 s). In Docker: MCP_TRANSPORT=http.

npx huly-mcp-selfhost http --host 0.0.0.0 --port 8000

Everyone with their own Huly account. A client sends its own login as headers; the session then acts as that person:

claude mcp add --transport http huly https://huly-mcp.example.com/mcp \
  --header "X-Huly-Token: <your token>"            # or X-Huly-Email + X-Huly-Password
  # optional: --header "X-Huly-Workspace: acme"    # pin one workspace (fewer tokens)

Log in with Huly (OAuth). Set MCP_OAUTH_SECRET (openssl rand -hex 32) and MCP_PUBLIC_URL (the HTTPS address clients reach, e.g. https://huly-mcp.example.com). Then people simply add https://huly-mcp.example.com/mcp in their AI app — Claude Code (claude mcp add --transport http huly …), Claude's custom connectors and other OAuth-capable MCP clients — and log in in the browser with their own Huly account: e-mail + password, or a one-time code by e-mail for Google/GitHub accounts. One server, as many people as you like, nobody handles tokens.

• Stateless: registrations, codes and tokens are sealed with AES-256-GCM under MCP_OAUTH_SECRET — no database, logins survive restarts. Changing the secret logs everyone out.

• The Huly password goes only to your Huly server; the server keeps just the resulting Huly token, inside the sealed tokens. Access tokens last 1 hour, refresh tokens 30 days and work once (rotation). Login attempts are throttled per address.

• The protocol parts (client registration, PKCE, token endpoint, metadata) are the MCP SDK's own; this server adds the login page and the tokens.

• X-Huly-Workspace still pins a workspace. In OAuth mode /mcp needs the OAuth token; MCP_AUTH_TOKEN and the X-Huly-* login headers are for the other mode.

One shared account. The server's own HULY_* login is only used behind a bearer token — set MCP_AUTH_TOKEN and give clients Authorization: Bearer <token>. Without it an open port would act as that account, so the server refuses and asks for per-user headers instead. With MCP_AUTH_TOKEN set, every request needs the bearer token, also when it brings its own login.

Set MCP_ALLOWED_HOSTS to the host names clients use (DNS-rebinding protection). Use HTTPS (reverse proxy) as soon as logins travel over a network. Idle sessions close after 30 minutes.

Example prompts

Workspaces:

• "Which Huly workspaces do I have?"

• "List the projects in my Acme workspace"

• "In the jokeks2023 workspace, log 2 hours on WEB-12"

Projects & issues:

• "Create a new project called 'Mobile App' with identifier MOBILE"

• "List all in-progress issues in the PROJ project"

• "Create a high-priority issue in PROJ titled 'Fix login timeout'"

• "Update PROJ-42 status to Done, assign it to Sarah, and move it to the Auth component"

• "Search for issues related to authentication"

• "Add a comment to PROJ-15 saying the fix is deployed"

• "List all comments on PROJ-42 to see the discussion"

Milestones & components:

• "Create a milestone 'v2.0 Launch' in PROJ with target date 2026-06-01"

• "List milestones for the PROJ project"

• "Create a component called 'Auth' in PROJ"

• "List all components in PROJ"

• "How far along is milestone v2.0 Launch in PROJ?"

• "Move the v2.0 Launch milestone to 2026-07-15 and set it to In Progress"

• "Delete milestone 'Beta' in PROJ and move its issues to 'v2.0 Launch'"

Planning & bulk work:

• "Which issues in milestone v2.0 Launch carry the label 'bug' and are still unassigned?"

• "Set PROJ-12, PROJ-13 and PROJ-20 to In Progress and put them into milestone v2.0 Launch"

• "Show me the sub-issue tree of PROJ-1 and how far along it is"

• "How many hours did we log on PROJ in October, per person?"

• "Move PROJ-42 to the OPS project"

Inbox, planner, calendar:

• "What's new in my inbox? Mark everything about PROJ-12 as read"

• "Create a to-do 'Review PR' on PROJ-7 due Friday and block 45 minutes tomorrow at 9"

• "What's on my calendar this week?"

• "Show the history of PROJ-12 — who moved it to Done?"

• "Which pull requests are waiting for review in PROJ?"

Labels & relations:

• "Add the label 'bug' to PROJ-42"

• "Create a label called 'backend' with color #3b82f6"

• "Mark PROJ-55 as blocked by PROJ-12"

• "Set PROJ-42 as a subtask of PROJ-5"

Time tracking:

• "Log 2.5 hours on PROJ-42 for the database refactor"

Documents:

• "List all documents in the Engineering teamspace"

• "Create a document called 'API Design' in the Engineering teamspace"

• "Update the API Design document with this Markdown: ..."

• "Add a Mermaid architecture diagram to the EP1 document"

• "Link document abc123 to issue PROJ-42"

• "Delete the second comment on PROJ-15"

Document content

Reading: get_document

get_document always returns full metadata (title, teamspace, comments, snapshots). To also fetch and display the text content, set the optional HULY_FRONT_URL env var:

"env": {
  "HULY_EMAIL": "...",
  "HULY_PASSWORD": "...",
  "HULY_FRONT_URL": "https://front.huly.app"
}

HULY_FRONT_URL only serves document/description content and file uploads — each request uses the token of the workspace named in the tool call. It plays no part in login or workspace discovery (that is HULY_ACCOUNTS_URL).

For self-hosted Huly, set HULY_FRONT_URL to your own front service URL (e.g. http://localhost:8083).

Writing: update_document

update_document accepts a documentId and a markdown string and writes rich structured content directly to the document — no manual editing required.

Self-hosted note: Document content (and, as of this fork, issue descriptions — see below) is stored as a MarkupBlobRef blob. Huly Cloud uploads these through a dedicated "datalake" microservice at a fixed URL; huly-selfhost (v0.7.x) does not run that service — blob storage goes through front's own, older /files endpoint instead. If HULY_FRONT_URL is set, this fork uploads through that self-hosted contract automatically; if it's unset, it falls back to Huly Cloud's datalake (the original, upstream behavior). No separate flag needed — HULY_FRONT_URL doubles as the self-host/cloud switch for both reading and writing.

Supported Markdown:

Example:

update_document({
  documentId: "abc123",
  markdown: `# Service Flow\n\n` +
    `## Architecture\n\n` +
    "```mermaid\n" +
    "flowchart TD\n" +
    "  A([User]) --> B[Browse Catalogue]\n" +
    "  B --> C[Pay via Razorpay]\n" +
    "  C --> D[Order Confirmed]\n" +
    "```\n\n" +
    "## Business Rules\n\n" +
    "- Payment required before confirmation\n" +
    "- All orders synced to HIS\n"
})

The Mermaid block renders as a live interactive diagram in Huly's document editor — not as a code block.

Bulk CSV Import

Import many issues at once from a CSV file — useful for migrating from other tools:

npm run build
node scripts/import-csv.js tasks.csv PROJ --workspace=myteam

The target workspace is required (--workspace=<slug>, or HULY_WORKSPACE as a fallback), since the script writes data. Credentials come from the environment as for the server.

CSV format:

title,priority,status,dueDate
Fix login bug,High,In Progress,2025-04-01
Add dark mode,Medium,,
Improve performance,Urgent,,2025-05-01

Required column: title. Optional: priority (Urgent/High/Medium/Low), status (must match a status name in the project), dueDate (YYYY-MM-DD).

Architecture

HULY_EMAIL + HULY_PASSWORD  (or HULY_TOKEN)
          ↓
   account login (once)              account-level client: getUserWorkspaces(), selectWorkspace()
          ↓
   getUserWorkspaces()  → workspace discovery (cached)
          ↓
   WorkspaceConnectionManager
     ├── workspace A: selectWorkspace(A) → endpoint + token → WebSocket (cached)
     ├── workspace B: selectWorkspace(B) → endpoint + token → WebSocket (cached)
     └── …                                workspace-level client (workspace token): getWorkspaceMembers()
          ↓
   MCP tools (each call names its workspace)

• One login, many workspaces — the account session is shared; each workspace gets its own long-lived connection via @hcengineering/server-client (model load takes 1–3 s, so connections are reused, not opened per call)

• Lazy — nothing connects until the first tool call, and a workspace connects only when first used, so auth errors surface clearly in the client

• No current workspace — there is no global or "last used" workspace; see Workspaces

• Stdio transport — standard MCP transport; the Docker image adds HTTP/SSE via mcp-proxy

See src/connection.ts.

Development and CI

npm ci && npm run build && npm test

npm run build type-checks (tsc --noEmit) and bundles src/ with all dependencies into one readable file, dist/index.js (esbuild, not minified), plus dist/guides/. The published package therefore has no runtime dependencies; everything in package.json is a dev dependency. Tests run on the TypeScript sources (tsx).

GitHub Actions check every pull request:

Security reports: see SECURITY.md.

test/repo.test.ts keeps the docs honest: tool counts in this README, the site and DOCKERHUB.md must match the registry, the version must match everywhere, and the plugin must be well-formed.

Releasing:

1. Move the Unreleased entries in CHANGELOG.md under ### X.Y.Z — date.

2. Bump the version in package.json, server.json, plugin/.claude-plugin/plugin.json, plugin/.mcp.json (exact npx version) and src/server.ts. The tests check that they agree.

3. Merge, then tag vX.Y.Z on main. The rest runs by itself.

Environments and secrets:

• Environment release (tags v* only): used by release.yml. npm Trusted Publishing names this environment.

• Environment sandbox: used by the nightly live jobs.

Secrets:

• PERSONAL_DATA_PATTERNS: private terms that must never appear in the repo, one regex per line.

• NPM_TOKEN: fallback only, until Trusted Publishing is set up on npmjs.com.

• In the environment sandbox: HULY_SMOKE_WORKSPACE, HULY_SMOKE_PROJECT, HULY_SMOKE_EMAIL + HULY_SMOKE_PASSWORD (or HULY_SMOKE_TOKEN), HULY_SMOKE_ACCOUNTS_URL, HULY_SMOKE_FRONT_URL: a throwaway workspace for the nightly live test. Without them the live jobs skip.

Changelog

See CHANGELOG.md.

Credits

Started as a fork of varaprasadreddy9676/huly-mcp (npm huly-mcp-sdk) by SaiVaraprasad Medapati and grown from its 33 tools to 227, with self-hosted support, toolsets, agent workflow and the Claude Code plugin. Published separately as huly-mcp-selfhost. Not affiliated with Huly Labs.

Links

• Website: https://jokeks2023.github.io/huly-mcp/

• Source and issues: https://github.com/JoKeks2023/huly-mcp

• npm: https://www.npmjs.com/package/huly-mcp-selfhost · Docker: https://hub.docker.com/r/jokeks2023/huly-mcp · MCP Registry: io.github.JoKeks2023/huly-mcp-selfhost

• Security: SECURITY.md

License

Eclipse Public License 2.0