Getting Started

Getting Started

Requirements

• Node.js ≥ 20 (for npx or a local build), or Docker
• A Huly account on huly.app or a self-hosted huly-selfhost instance
• For email + password login: a password set on the Huly account (Profile → Security → Change password). SSO-only accounts (Google/GitHub) use a token instead, see Authentication.

Three ways to run it

Mode	When	Transport
npx	Local AI client on your machine	stdio
Clone + build	Local, running from source or a branch	stdio
Docker	Server reachable over the network (remote MCP)	HTTP (streamable HTTP + SSE) via mcp-proxy — see Docker Deployment

npx

npx -y huly-mcp-selfhost

The package has three executables: huly-mcp-selfhost and huly-mcp both start the server, and huly-mcp-setup runs the token wizard. The huly-mcp-selfhost executable exists from 2.0.0 on. With huly-mcp-selfhost@1.0.0, npx huly-mcp-selfhost fails with "could not determine executable to run". That version is also the old single-workspace release, so use 2.0.0 or later.

Clone and build

git clone https://github.com/JoKeks2023/huly-mcp.git
cd huly-mcp
npm install
npm run build          # → dist/index.js

Your client then runs node /absolute/path/to/huly-mcp/dist/index.js.

Connect a client

Every stdio client needs the same three things: a command, its arguments and the environment. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Claude Code:

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

The README has ready-made configs for Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, Zed and Codex. For self-hosted Huly add HULY_ACCOUNTS_URL and HULY_FRONT_URL, see Self-Hosted Huly.

No workspace is configured anywhere. The server finds your workspaces itself, see Multi-Workspace.

First steps in the client

1. Ask for your workspaces. "Which Huly workspaces do I have?" calls list_workspaces:

   ## Workspaces (2)
   
   - **Acme Team** — slug: `acmeteam` — id: `3f2b9c1e-…`
   - **Personal** — slug: `personal` — id: `8a41d7e0-…`
   
   Pass the slug (or name/id) as `workspace` to other tools.
   

2. Work in a named workspace. "List the projects in my personal workspace" calls list_projects(workspace="personal").

3. Changes always name the workspace. "Log 2 hours on WEB-12 in acmeteam" calls log_time(workspace="acmeteam", identifier="WEB-12", hours=2). If you don't make the workspace clear, the server's instructions tell the agent to ask you rather than guess.

Check it works without a client

npm run setup logs in (email one-time code) and lists every workspace the account can access. That is a quick check that credentials, HULY_ACCOUNTS_URL and workspace discovery work. See Setup wizard.