huly-mcp

A local MCP server that lets Claude manage your Huly issues, time tracking, and planner.

huly-mcp connects Claude to a self-hosted Huly instance over the Model Context Protocol. You point it at your instance, and Claude can read your issues, see what you are scheduled to work on right now, log time, change status, and leave comments, all from a normal conversation. It runs locally as a small Node process and authenticates as you.

This project is an experiment in AI-maintained open source: autonomously built, tested, and refined by AI with human oversight.

What it does

The server exposes a focused set of tools rather than one for every Huly feature:

Tool	What it does
current_issue	The issue scheduled in your planner for right now (the active calendar work slot covering the current time), falling back to the next upcoming slot.
list_issues	Your assigned issues, open by default, filterable by project and status.
get_issue	Full detail for one issue: description, status, estimate, time spent, time logs, and comments.
plan_issue	Add an issue to your planner and optionally schedule it onto your calendar. Scheduling an issue moves it to In Progress, so this doubles as "start working on this."
log_time	Record actual time spent on an issue.
edit_time_log / delete_time_log	Amend or remove a time entry.
set_estimate	Set or change an issue's estimated hours.
update_issue	Change status, priority, assignee, title, or due date, and optionally leave a comment in the same call.
comment	Post a comment on an issue.
week_summary	Hours logged this week against a weekly budget (10 hours by default).
create_issue	Create a new issue in a project.
list_projects	List the projects in the workspace.

Setup

Requires Node.js 20 or newer.

git clone https://github.com/nvms/huly-mcp.git
cd huly-mcp
npm install

The server reads four environment variables:

Variable	Meaning
HULY_URL	The base URL of your Huly instance, for example https://huly.example.com/.
HULY_EMAIL	Your Huly login email.
HULY_PASSWORD	Your Huly password.
HULY_WORKSPACE	The workspace URL name (the slug in the workspace URL, not its display name).

Connect it to Claude

Add the server to your MCP client configuration. For Claude Desktop or Claude Code, that looks like:

{
  "mcpServers": {
    "huly": {
      "command": "node",
      "args": ["/absolute/path/to/huly-mcp/src/index.js"],
      "env": {
        "HULY_URL": "https://huly.example.com/",
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "your-password",
        "HULY_WORKSPACE": "your-workspace"
      }
    }
  }
}

The connection is made lazily on the first tool call, so the server starts even if the instance is briefly unreachable, and a dropped connection reconnects on the next request.

Verify the connection

A read-only smoke check confirms the server can reach your instance and read your data without changing anything. Copy the env template, fill it in, and run it:

cp .env.example .env
# edit .env with your values
node --env-file=.env scripts/smoke.js

It prints your identity, projects, open issues, current planner slot, and week summary, then exits. It never creates, updates, or deletes anything.

Examples

Once connected, you talk to Claude normally:

• "What should I be working on right now?" reads your planner and tells you the issue scheduled for the current time.
• "Show me my open issues" lists what is assigned to you.
• "What does AFS-4 say?" reads the issue, including its description and any comments left for you.
• "Grab IQ-4 from the backlog and start on it" schedules it into your planner, which moves it to In Progress.
• "Log 90 minutes against IQ-7 for the search work" records the time; the issue's reported time updates automatically.
• "How many hours have I logged this week?" totals your time against your weekly budget.
• "Mark IQ-7 done and add a note that the limit is now 30" changes the status and posts the comment in one step.

Because the server authenticates as you, every comment and change is attributed to your account.

Notes on Huly versions

huly-mcp talks to Huly's transactor and account services directly, so it works across the 0.6 and 0.7 lines without depending on a version-specific high-level client. Identity, issues, time tracking, comments, and the planner all behave the same way.

One capability depends on the server version: writing an issue's rich-text description requires the collaborator service, which is only compatible on newer instances. When the running instance does not accept a description write, create_issue and update_issue preserve the text you provided by posting it as a comment instead, and tell you they did so. Reading descriptions works on every version.

License

MIT