@dugynoo/huly-mcp

MCP server for Huly integration — 209 tools across 23 categories (issues, projects, tasks, comments, documents, cards, channels, calendar, time tracking, test management, processes, custom fields, attachments, leads and more). Supports custom task types with project-scoped status workflows and read-side Process plugin tools.

Installation

The standard configuration works with most MCP clients:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@dugynoo/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Claude Code

claude mcp add huly \
  -e HULY_URL=https://huly.app \
  -e HULY_EMAIL=your@email.com \
  -e HULY_PASSWORD=yourpassword \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @dugynoo/huly-mcp@latest

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 to your user settings (.vscode/mcp.json) or use Command Palette → "MCP: Add Server":

{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@dugynoo/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

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 add this config to the mcp section.

"huly": {
      "type": "local",
      "command": ["npx", "-y", "@dugynoo/huly-mcp@latest"],
      "environment": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }

Updating

The @latest tag in the install command always fetches the newest version. Most MCP clients cache the installed package, so you need to force a re-fetch:

Client	How to update
Claude Code	claude mcp remove huly then re-add with the install command above
Claude Desktop	Restart the app (it runs npx on startup)
VS Code / Cursor	Restart the MCP server from the command palette or reload the window
npx (manual)	npx -y @dugynoo/huly-mcp@latest — the -y flag skips the cache when @latest resolves to a new version

HTTP Transport

By default, the server uses stdio transport. For HTTP transport (Streamable HTTP):

HULY_URL=https://huly.app \
HULY_EMAIL=your@email.com \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @dugynoo/huly-mcp@latest

Server listens on http://127.0.0.1:3000/mcp by default.

Configure with MCP_HTTP_PORT and MCP_HTTP_HOST:

MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @dugynoo/huly-mcp@latest

Environment Variables

Variable	Required	Description
HULY_URL	Yes	Huly instance URL
HULY_EMAIL	Auth*	Account email
HULY_PASSWORD	Auth*	Account password
HULY_TOKEN	Auth*	API token (alternative to email/password)
HULY_WORKSPACE	Yes	Workspace identifier
HULY_CONNECTION_TIMEOUT	No	Connection timeout in ms (default: 30000)
MCP_TRANSPORT	No	Transport type: stdio (default) or http
MCP_HTTP_PORT	No	HTTP server port (default: 3000)
MCP_HTTP_HOST	No	HTTP server host (default: 127.0.0.1)
TOOLSETS	No	Comma-separated tool categories to expose. If unset, all tools are exposed. Example: issues,projects,search

*Auth: Provide either HULY_EMAIL + HULY_PASSWORD or HULY_TOKEN.

Differences from @firfi/huly-mcp

This package is a downstream of @firfi/huly-mcp with two additions:

• taskType parameter on create_issue and update_issue so issues can be created with custom task types (e.g. Ticket, Bug, Feature) and project-scoped status workflows (Created, Awaiting approval, etc.). Without this, issues created via MCP fall back to the default task type even when the project defines its own.
• Read-side Process plugin tools: list_processes, get_process, list_executions. Requires a Huly server with the Process plugin enabled (v0.7.382+).

Original upstream copyright is preserved in LICENSE.

Available Tools

TOOLSETS categories: projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendar, time tracking, search, activity, notifications, workspace, associations, cards, custom-fields, labels, leads, processes, tag-categories, task-management, test-management, user-statuses

Projects

Tool	Description
list_projects	List all Huly projects. Returns projects sorted by name. Supports filtering by archived status.
get_project	Get full details of a Huly project including its statuses. Returns project name, description, archived flag, default status, and all available statuses.
list_statuses	List all issue statuses for a Huly project with category info. Returns status name, isDone, isCanceled, and isDefault flags. Use this to discover valid statuses before creating or updating issues.
create_project	Create a new Huly tracker project. Idempotent: returns existing project if one with the same identifier already exists (created=false). Identifier must be 1-5 uppercase alphanumeric chars starting with a letter.
update_project	Update a Huly project. Only provided fields are modified. Set description to null to clear it.
delete_project	Permanently delete a Huly project. All issues, milestones, and components in this project will be orphaned. This action cannot be undone.

Issues

Tool	Description
preview_deletion	Preview the impact of deleting a Huly entity before actually deleting it. Shows affected sub-entities, relations, and warnings. Supports issues, projects, components, and milestones. Use this to understand cascade effects before calling a delete operation.
list_issues	Query Huly issues with optional filters. Returns issues sorted by modification date (newest first). Supports filtering by project, status, assignee, component, and parentIssue (to list children of a specific issue). Supports searching by title substring (titleSearch) and description content (descriptionSearch).
get_issue	Retrieve full details for a Huly issue including markdown description. Use this to view issue content, comments, or full metadata.
create_issue	Create a new issue in a Huly project. Optionally create as a sub-issue by specifying parentIssue. Description supports markdown formatting. Returns the created issue identifier.
update_issue	Update fields on an existing Huly issue. Only provided fields are modified. Description updates support markdown.
add_issue_label	Add a tag/label to a Huly issue. Creates the tag if it doesn't exist in the project.
remove_issue_label	Remove a tag/label from a Huly issue. Detaches the label reference; does not delete the label definition.
delete_issue	Permanently delete a Huly issue. This action cannot be undone.
move_issue	Move an issue to a new parent (making it a sub-issue) or to top-level (null). Updates parent/child relationships and sub-issue counts.
list_components	List components in a Huly project. Components organize issues by area/feature. Returns components sorted by modification date (newest first).
get_component	Retrieve full details for a Huly component. Use this to view component content and metadata.
create_component	Create a new component in a Huly project. Components help organize issues by area/feature. Returns the created component ID and label.
update_component	Update fields on an existing Huly component. Only provided fields are modified.
set_issue_component	Set or clear the component on a Huly issue. Pass null for component to clear it.
delete_component	Permanently delete a Huly component. This action cannot be undone.
list_issue_templates	List issue templates in a Huly project. Templates define reusable issue configurations. Returns templates sorted by modification date (newest first).
get_issue_template	Retrieve full details for a Huly issue template including children (sub-task templates). Use this to view template content, default values, and child template IDs.
create_issue_template	Create a new issue template in a Huly project. Templates define default values for new issues. Optionally include children (sub-task templates) that will become sub-issues when creating issues from this template. Returns the created template ID and title.
create_issue_from_template	Create a new issue from a template. Applies template defaults, allowing overrides for specific fields. If the template has children (sub-task templates), sub-issues are created automatically unless includeChildren is set to false. Returns the created issue identifier and count of children created.
update_issue_template	Update fields on an existing Huly issue template. Only provided fields are modified.
delete_issue_template	Permanently delete a Huly issue template. This action cannot be undone.
add_template_child	Add a child (sub-task) template to an issue template. The child defines default values for sub-issues created when using create_issue_from_template. Returns the child template ID.
remove_template_child	Remove a child (sub-task) template from an issue template by its child ID. Get child IDs from get_issue_template response.
add_issue_relation	Add a relation between two issues. Relation types: 'blocks' (source blocks target — pushes into target's blockedBy), 'is-blocked-by' (source is blocked by target — pushes into source's blockedBy), 'relates-to' (bidirectional link — updates both sides). targetIssue accepts cross-project identifiers like 'OTHER-42'. No-op if the relation already exists.
remove_issue_relation	Remove a relation between two issues. Mirrors add_issue_relation: 'blocks' pulls from target's blockedBy, 'is-blocked-by' pulls from source's blockedBy, 'relates-to' pulls from both sides. No-op if the relation doesn't exist.
list_issue_relations	List all relations of an issue. Returns blockedBy (issues blocking this one), relations (bidirectional issue links), and documents (linked documents with title/teamspace). Does NOT return issues that this issue blocks — use list_issue_relations on the target issue to see that.
link_document_to_issue	Link a Huly document to an issue. The link appears in the issue's Relations panel in the UI. Idempotent: no-op if the document is already linked. Use list_issue_relations to see linked documents.
unlink_document_from_issue	Remove a document link from an issue. Idempotent: no-op if the document is not linked.

Comments

Tool	Description
list_comments	List comments on a Huly issue. Returns comments sorted by creation date (oldest first).
add_comment	Add a comment to a Huly issue. Comment body supports markdown formatting.
update_comment	Update an existing comment on a Huly issue. Comment body supports markdown formatting.
delete_comment	Delete a comment from a Huly issue. This action cannot be undone.

Milestones

Tool	Description
list_milestones	List milestones in a Huly project. Returns milestones sorted by modification date (newest first).
get_milestone	Retrieve full details for a Huly milestone. Use this to view milestone content and metadata.
create_milestone	Create a new milestone in a Huly project. Returns the created milestone ID and label.
update_milestone	Update fields on an existing Huly milestone. Only provided fields are modified.
set_issue_milestone	Set or clear the milestone on a Huly issue. Pass null for milestone to clear it.
delete_milestone	Permanently delete a Huly milestone. This action cannot be undone.

Documents

Tool	Description
list_teamspaces	List all Huly document teamspaces. Returns teamspaces sorted by name. Supports filtering by archived status.
get_teamspace	Get details for a Huly document teamspace including document count. Finds by name or ID, including archived teamspaces.
create_teamspace	Create a new Huly document teamspace. Idempotent: returns existing teamspace if one with the same name exists.
update_teamspace	Update fields on an existing Huly document teamspace. Only provided fields are modified. Set description to null to clear it.
delete_teamspace	Permanently delete a Huly document teamspace. This action cannot be undone.
list_documents	List documents in a Huly teamspace. Returns documents sorted by modification date (newest first). Each result includes a 'url' field pointing to the document in the Huly web app. Supports searching by title substring (titleSearch) and content (contentSearch).
get_document	Retrieve full details for a Huly document including markdown content and a 'url' field pointing to the document in the Huly web app. Use this to view document content and metadata.
create_document	Create a new document in a Huly teamspace. Content supports full markdown including native Mermaid diagrams (```mermaid blocks render interactively in Huly UI). Optionally pass parent as a document title or ID to create a nested child document; invalid parents fail instead of silently creating a top-level document. Returns the created document id and a 'url' field pointing to the document in the Huly web app. Use link_document_to_issue to associate the document with a tracker issue.
edit_document	Edit an existing Huly document. Two content modes (mutually exclusive): (1) 'content' for full replace, (2) 'old_text' + 'new_text' for targeted search-and-replace. Multiple matches error unless replace_all is true. Empty new_text deletes matched text. Also supports renaming via 'title'. Content supports full markdown including native Mermaid diagrams. Returns a 'url' field pointing to the document in the Huly web app.
list_inline_comments	List inline comment threads from a Huly document. Extracts comments embedded in document content as ProseMirror marks. Each comment includes the highlighted text and thread ID. Set includeReplies=true to also fetch thread reply messages with sender names.
delete_document	Permanently delete a Huly document. This action cannot be undone.

Storage

Tool	Description
upload_file	Upload a file to Huly storage. Provide ONE of: filePath (local file - preferred), fileUrl (fetch from URL), or data (base64 - for small files only). Returns blob ID and URL for referencing the file.

Attachments

Tool	Description
list_attachments	List attachments on a Huly object (issue, document, etc.). Returns attachments sorted by modification date (newest first).
get_attachment	Retrieve full details for a Huly attachment including download URL.
add_attachment	Add an attachment to a Huly object. Provide ONE of: filePath (local file - preferred), fileUrl (fetch from URL), or data (base64). Returns the attachment ID and download URL.
update_attachment	Update attachment metadata (description, pinned status).
delete_attachment	Permanently delete an attachment. This action cannot be undone.
pin_attachment	Pin or unpin an attachment.
download_attachment	Get download URL for an attachment along with file metadata (name, type, size).
add_issue_attachment	Add an attachment to a Huly issue. Convenience method that finds the issue by project and identifier. Provide ONE of: filePath, fileUrl, or data.
add_document_attachment	Add an attachment to a Huly document. Convenience method that finds the document by teamspace and title/ID. Provide ONE of: filePath, fileUrl, or data.

Contacts

Tool	Description
list_persons	List all persons in the Huly workspace. Returns persons sorted by modification date (newest first). Supports searching by name substring (nameSearch) and email substring (emailSearch).
get_person	Retrieve full details for a person including contact channels. Use personId or email to identify the person.
create_person	Create a new person in Huly. Returns the created person ID.
update_person	Update fields on an existing person. Only provided fields are modified.
delete_person	Permanently delete a person from Huly. This action cannot be undone.
list_employees	List employees (persons who are team members). Returns employees sorted by modification date (newest first).
list_organizations	List all organizations in the Huly workspace. Returns organizations sorted by modification date (newest first).
create_organization	Create a new organization in Huly. Optionally add members by person ID or email. Fails if any requested member cannot be resolved. Returns the created organization ID.
get_organization	Retrieve full details for an organization by ID or exact name when that name is unique - including city, description, member count, and modification timestamp. If multiple organizations share the same name, use the organization ID.
update_organization	Update fields on an existing organization identified by ID or exact name when that name is unique. Only provided fields are modified. Description supports multi-line plain text and is the right place to store CRM notes / revenue summaries / context. Pass null to clear city or description. If multiple organizations share the same name, use the organization ID.
delete_organization	Permanently delete an organization identified by ID or exact name when that name is unique. Use with care - this cannot be undone. Useful for cleaning up duplicate organizations after merging their data elsewhere. If multiple organizations share the same name, use the organization ID.
make_organization_customer	Apply the Customer mixin to an organization so it appears in the Huly Leads > Customers view. Idempotent - safe to call on organizations that are already customers. Takes the organization ID or exact name when that name is unique.
add_organization_channel	Add a contact channel (phone, email, website/homepage, LinkedIn, Twitter, GitHub, Facebook, Telegram) to an organization identified by ID or exact unique name. Provider names: email, phone, linkedin, twitter, github, facebook, telegram, homepage.
add_organization_member	Link a person as a member of an organization. The person appears under the org's Members tab in Huly. Use person ID or email to identify the person. Idempotent: returns added=false if that person is already a member.
list_organization_members	List all persons who are members of an organization. Returns each member's person ID, name, and primary email (if any). When using a name instead of an ID, that name must identify exactly one organization.
list_person_organizations	List all organizations that a person is a member of. Provide personId or email. Returns each organization's ID and name.
remove_organization_member	Unlink a person from an organization's members. Reverses add_organization_member. Returns removed: false if the person was not a member. When using an organization name instead of an ID, that name must identify exactly one organization.

Channels

Tool	Description
list_channels	List all Huly channels. Returns channels sorted by name. Supports filtering by archived status. Supports searching by name substring (nameSearch) and topic substring (topicSearch).
get_channel	Retrieve full details for a Huly channel including topic and member list.
create_channel	Create a new channel in Huly. Returns the created channel ID and name.
update_channel	Update fields on an existing Huly channel. Only provided fields are modified.
delete_channel	Permanently delete a Huly channel. This action cannot be undone.
list_channel_messages	List messages in a Huly channel. Returns messages sorted by date (newest first).
send_channel_message	Send a message to a Huly channel. Message body supports markdown formatting.
update_channel_message	Update a channel message. Only the body can be modified.
delete_channel_message	Permanently delete a channel message. This action cannot be undone.
list_direct_messages	List direct message conversations in Huly. Returns conversations sorted by date (newest first).
create_direct_message	Open a one-to-one direct-message conversation with a workspace member. The person argument accepts an email or exact display name (e.g. Smith,Bill). Idempotent: if a DM with that participant already exists, returns it (created: false); otherwise creates a new DM (created: true). The returned id can be passed as dm to send_dm_message, list_dm_messages, etc.
list_dm_messages	List messages in a direct-message conversation, newest first. The dm argument accepts either the DM _id or a participant display name (e.g. Kerr,Shannon); a name resolves only to a one-to-one DM with the authenticated account.
send_dm_message	Send a message to a direct-message conversation. The dm argument accepts either the DM _id or a participant display name; a name resolves only to a one-to-one DM with the authenticated account. Message body supports markdown formatting.
update_dm_message	Update a direct-message message. The dm argument accepts either the DM _id or a participant display name; a name resolves only to a one-to-one DM with the authenticated account. Only the body can be modified.
delete_dm_message	Permanently delete a direct-message message. The dm argument accepts either the DM _id or a participant display name; a name resolves only to a one-to-one DM with the authenticated account. This action cannot be undone.
list_thread_replies	List replies in a message thread. Returns replies sorted by date (oldest first).
add_thread_reply	Add a reply to a message thread. Reply body supports markdown formatting.
update_thread_reply	Update a thread reply. Only the body can be modified.
delete_thread_reply	Permanently delete a thread reply. This action cannot be undone.

Calendar

Tool	Description
list_events	List calendar events. Returns events sorted by date. Supports filtering by date range.
list_calendars	List writable, non-hidden calendars that can be used as create_event or create_recurring_event targets. Use this before creating events when you need to choose a target calendarId explicitly.
get_event	Retrieve full details for a calendar event including description. Use this to view event content and metadata.
create_event	Create a new calendar event. Description supports markdown formatting. Optional calendarId targets a specific calendar; when omitted, the event uses the authenticated user's primary personal calendar. Returns the created event ID.
update_event	Update fields on an existing calendar event. Only provided fields are modified. Description updates support markdown.
delete_event	Permanently delete a calendar event. This action cannot be undone.
list_recurring_events	List recurring event definitions. Returns recurring events sorted by modification date (newest first).
create_recurring_event	Create a new recurring calendar event with RFC5545 RRULE rules. Description supports markdown. Optional calendarId targets a specific calendar; when omitted, the event uses the authenticated user's primary personal calendar. Returns the created event ID.
list_event_instances	List instances of a recurring event. Returns instances sorted by date. Supports filtering by date range. Use includeParticipants=true to fetch full participant info (extra lookups).

Time Tracking

Tool	Description
log_time	Log time spent on a Huly issue. Records a time entry with optional description. Time value is in minutes.
get_time_report	Get time tracking report for a specific Huly issue. Shows total time, estimation, remaining time, and all time entries.
list_time_spend_reports	List all time entries across issues. Supports filtering by project and date range. Returns entries sorted by date (newest first).
get_detailed_time_report	Get detailed time breakdown for a project. Shows total time grouped by issue and by employee. Supports date range filtering.
list_work_slots	List scheduled work slots. Shows planned time blocks attached to ToDos. Supports filtering by employee and date range.
create_work_slot	Create a scheduled work slot. Attaches a time block to a ToDo for planning purposes.
start_timer	Start a client-side timer on a Huly issue. Validates the issue exists and returns a start timestamp. Use log_time to record the elapsed time when done.
stop_timer	Stop a client-side timer on a Huly issue. Returns the stop timestamp. Calculate elapsed time from start/stop timestamps and use log_time to record it.
dedup_planner_todos	Remove duplicate Planner ToDo items that the Huly server sometimes creates more than once per issue

Search

Tool	Description
fulltext_search	Perform a global fulltext search across all Huly content. Searches issues, documents, messages, and other indexed content. Returns matching items sorted by relevance (newest first).

Activity

Tool	Description
list_activity	List activity messages for a Huly object. Returns activity sorted by date (newest first).
add_reaction	Add an emoji reaction to an activity message.
remove_reaction	Remove an emoji reaction from an activity message.
list_reactions	List reactions on an activity message.
save_message	Save/bookmark an activity message for later reference.
unsave_message	Remove an activity message from saved/bookmarks.
list_saved_messages	List saved/bookmarked activity messages.
list_mentions	List @mentions of the current user in activity messages.

Notifications

Tool	Description
list_notifications	List inbox notifications. Returns notifications sorted by modification date (newest first). Supports filtering by read/archived status.
get_notification	Retrieve full details for a notification. Use this to view notification content and metadata.
mark_notification_read	Mark a notification as read.
mark_all_notifications_read	Mark all unread notifications as read. Returns the count of notifications marked.
archive_notification	Archive a notification. Archived notifications are hidden from the main inbox view.
archive_all_notifications	Archive all notifications. Returns the count of notifications archived.
delete_notification	Permanently delete a notification. This action cannot be undone.
get_notification_context	Get notification context for an entity. Returns tracking information for a specific object.
list_notification_contexts	List notification contexts. Returns contexts sorted by last update timestamp (newest first). Supports filtering by pinned status.
pin_notification_context	Pin or unpin a notification context. Pinned contexts are highlighted in the inbox.
list_notification_settings	List notification provider settings. Returns current notification preferences.
update_notification_provider_setting	Update notification provider setting. Enable or disable notifications for a specific provider.
get_unread_notification_count	Get the count of unread notifications.

Workspace

Tool	Description
list_workspace_members	List members in the current Huly workspace with their roles. Returns members with account IDs and roles.
update_member_role	Update a workspace member's role. Requires appropriate permissions. Valid roles: READONLYGUEST, DocGuest, GUEST, USER, MAINTAINER, OWNER, ADMIN.
get_workspace_info	Get information about the current workspace including name, URL, region, and settings.
list_workspaces	List all workspaces accessible to the current user. Returns workspace summaries sorted by last visit.
create_workspace	Create a new Huly workspace. Returns the workspace UUID and URL. Optionally specify a region.
delete_workspace	Permanently delete the current workspace. This action cannot be undone. Use with extreme caution.
get_user_profile	Get the current user's profile information including bio, location, and social links.
update_user_profile	Update the current user's profile. Supports bio, city, country, website, social links, and public visibility.
update_guest_settings	Update workspace guest settings. Control read-only guest access and guest sign-up permissions.
create_access_link	Create a Huly workspace access link. Defaults to role GUEST. Supports anonymous reusable guest links by setting personalized=false with notBefore and expiration, and can restrict access to specific Huly space IDs via spaces.
get_regions	Get available regions for workspace creation. Returns region codes and display names.

Associations

Tool	Description
list_associations	List Huly Association definitions in the workspace. Each Association is a typed link between two document classes (e.g. Person ↔ Organization with cardinality 1:1 / 1:N / N:N). Filter by classA or classB.
create_association	Create a new Huly Association between two document classes. Idempotent: returns existing association if one already exists with the same (classA, classB, nameA, nameB) tuple.
list_relations	List Huly Relations — concrete links between documents. Filter by association (ID), docA (source document ID), or docB (target document ID).
create_relation	Link two documents through an existing Association. Idempotent: returns existing relation if one already connects (docA, docB) via the same association.
delete_relation	Remove a Relation between two documents. Idempotent: returns deleted=false if the relation no longer exists.

Cards

Tool	Description
list_card_spaces	List all Huly card spaces. Returns card spaces sorted by name. Card spaces are containers for cards.
list_master_tags	List master tags (card types) available in a Huly card space. Master tags define the type/schema of cards that can be created in a space.
list_cards	List cards in a Huly card space. Returns cards sorted by modification date (newest first). Supports filtering by type (master tag), title substring, and content search.
get_card	Retrieve full details for a Huly card including markdown content. Use this to view card content and metadata.
create_card	Create a new card in a Huly card space. Requires a master tag (card type). Content supports markdown formatting. Returns the created card id.
update_card	Update fields on an existing Huly card. Only provided fields are modified. Content updates support markdown.
delete_card	Permanently delete a Huly card. This action cannot be undone.

Custom-Fields

Tool	Description
list_custom_fields	List custom field definitions in the workspace. Returns fields with their labels, types, and owner class info. Custom fields are created in the Huly UI on Card types, Issue types, or other classes. Use targetClass to filter fields for a specific class.
get_custom_field_values	Read custom field values from a document. Pass the document's ID and class (from list_cards, list_issues, etc.). Returns all custom field values found on the document with their labels and types.
set_custom_field	Set a custom field value on a document. Requires the document ID, class, field ID (from list_custom_fields), and value. Values are auto-parsed: numbers from numeric strings, booleans from 'true'/'false', strings as-is.

Labels

Tool	Description
list_labels	List label/tag definitions in the workspace. Labels are global (not project-scoped). Returns labels for tracker issues sorted by modification date (newest first).
create_label	Create a new label/tag definition in the workspace. Labels are global and can be attached to any issue. Returns existing label if one with the same title already exists (created=false). Use add_issue_label to attach a label to a specific issue.
update_label	Update a label/tag definition. Accepts label ID or title. Only provided fields are modified.
delete_label	Permanently delete a label/tag definition. Accepts label ID or title. This action cannot be undone.

Leads

Tool	Description
list_funnels	List all Huly sales funnels (lead pipelines). Returns each funnel's stable ID and display name, sorted by name. Supports filtering by archived status.
list_leads	Query Huly leads in a funnel with optional filters. Pass the funnel ID returned by list_funnels, or a funnel name for convenience lookup. Returns leads sorted by modification date (newest first). Supports filtering by status, assignee, and title search.
get_lead	Retrieve full details for a Huly lead including markdown description, customer name, funnel ID and funnel name, and status. Lead identifiers follow the upstream Huly format like 'LEAD-1'.

Processes

Tool	Description
list_processes	List Huly Process definitions in the workspace. Each Process is a workflow attached to a card class (master tag). Optionally filter by masterTag to find processes for a specific card type. Read-only.
get_process	Fetch a single Huly Process definition by ID or display name. Returns name, description, master tag, and start/automation flags. Read-only.
list_executions	List Process Executions — live or completed workflow runs against specific cards. Filter by process (ID or name), card (card ID), or status (active/done/cancelled). Each execution row includes the current workflow state and an error flag. Read-only.
start_process	Start a new Process execution against a card. Resolves the process by ID or display name and creates an active Execution at the first workflow state (lowest rank). The Huly server's process engine then auto-fires OnExecutionStart triggers to advance the execution.
cancel_execution	Cancel an in-flight Process execution by setting its status to 'cancelled'. Idempotent — already-cancelled executions return cancelled=false.

Tag-Categories

Tool	Description
list_tag_categories	List tag/label categories in the workspace. Categories group labels (e.g., 'Priority Labels', 'Type Labels'). Optional targetClass filter (defaults to all).
create_tag_category	Create a new tag/label category. Idempotent: returns existing category if one with the same label and targetClass already exists (created=false). Defaults targetClass to tracker issues.
update_tag_category	Update a tag/label category. Accepts category ID or label name. Only provided fields are modified.
delete_tag_category	Permanently delete a tag/label category. Accepts category ID or label name. Labels in this category will be orphaned (not deleted). This action cannot be undone.

Task-Management

Tool	Description
list_project_types	List Huly tracker project types/workflow templates. Returns ID, display name, descriptor, task type count, status count, and whether the type appears to be the default Classic tracker type.
get_project_type	Inspect one Huly tracker project type in a single call. Accepts projectType as ID or display name; when omitted, uses the unambiguous Classic tracker type. Returns task types, statuses, categories, and task-type-to-status mappings.
list_task_types	List Huly issue/task types. Optionally filter by projectType ID or display name. Returns task type identity, parent project type, kind, issue class, and available status count.
create_task_type	Add a Huly issue/task type to a project type idempotently by normalized name. Copies required workflow configuration from an existing template task type unless templateTaskType is supplied. Returns created, IDs, affected task type IDs, and a workspace-level workflow warning.
create_issue_status	Add a Huly issue workflow status idempotently by normalized name within a project type and task type scope. Accepts category as backlog, todo, active, done, or canceled; taskType may be ID or display name, and omission applies the status to every task type in the project type.

Test-Management

Tool	Description
list_test_projects	List test management projects. Returns test projects sorted by name. These are separate from tracker projects.
list_test_suites	List test suites in a test project. Accepts project ID or name. Optional parent filter for nested suites.
get_test_suite	Get a single test suite by ID or name within a test project. Returns suite details and test case count.
create_test_suite	Create a test suite in a test project. Idempotent: returns existing suite if one with the same name exists (created=false). Optional parent for nesting.
update_test_suite	Update a test suite. Accepts suite ID or name. Only provided fields are modified.
delete_test_suite	Permanently delete a test suite. Accepts suite ID or name. This action cannot be undone.
list_test_cases	List test cases in a test project. Optional filters: suite (ID or name), assignee (name or email).
get_test_case	Get a single test case by ID or name within a test project.
create_test_case	Create a test case attached to a suite. Requires project and suite. Defaults: type=functional, priority=medium, status=draft.
update_test_case	Update a test case. Accepts test case ID or name. Only provided fields are modified. Set assignee to null to unassign.
delete_test_case	Permanently delete a test case. Accepts test case ID or name. This action cannot be undone.
list_test_plans	List test plans in a test management project. Returns plan names and IDs. Requires project ID or name.
get_test_plan	Get test plan details including its items (test cases). Accepts plan ID or name within a project.
create_test_plan	Create a test plan in a project. Idempotent: returns existing plan if one with the same name exists (created=false).
update_test_plan	Update a test plan's name or description. Only provided fields are modified. Pass description=null to clear.
delete_test_plan	Permanently delete a test plan. This does not delete associated test runs. Cannot be undone.
add_test_plan_item	Add a test case to a test plan. Resolves test case by ID or name. Optionally assign a person by email or name.
remove_test_plan_item	Remove a test case from a test plan by item ID. Get item IDs from get_test_plan.
list_test_runs	List test runs in a test management project. Returns run names, IDs, and due dates.
get_test_run	Get test run details including all results. Accepts run ID or name within a project.
create_test_run	Create a test run in a project. For bulk creation from a plan, use run_test_plan instead.
update_test_run	Update a test run's name, description, or due date. Only provided fields are modified. Pass null to clear optional fields.
delete_test_run	Permanently delete a test run. This does not delete associated test results. Cannot be undone.
list_test_results	List test results in a test run. Returns result names, statuses, and assignees.
get_test_result	Get test result details. Accepts result ID or name.
create_test_result	Create a test result in a run. Resolves test case by ID or name. Status defaults to 'untested'.
update_test_result	Update a test result's status, assignee, or description. Status values: untested, blocked, passed, failed.
delete_test_result	Permanently delete a test result. Cannot be undone.
run_test_plan	Execute a test plan: creates a test run and one test result per plan item. Returns the run ID and count of results created. Optionally name the run and set a due date.

User-Statuses

Tool	Description
list_user_statuses	List Huly user presence records — who is currently online, with their account UUID and last status change timestamp. Filter by online (true/false) or user (account UUID). Read-only; presence is maintained server-side based on websocket connection state.

Troubleshooting

Passwords with special characters

If your Huly password contains characters like *, %, !, or #, passing it via the CLI -e flag may fail because the shell interprets these characters before they reach the process.

Solution: Edit your MCP config file directly instead of using claude mcp add -e. In ~/.claude.json (user scope) or .mcp.json (project scope), JSON handles all special characters natively:

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "node",
      "args": ["path/to/dist/index.cjs"],
      "env": {
        "HULY_URL": "https://your-huly-instance.com",
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "p@ss*w0rd!#%",
        "HULY_WORKSPACE": "your-workspace"
      }
    }
  }
}

Alternatively, use HULY_TOKEN instead of email/password to bypass password auth entirely (see Environment Variables).

MCP client shows "Failed to reconnect"

After changing MCP configuration, some clients (including Claude Code) require a full restart — not just a reconnect. Exit the application completely and reopen it.

You can verify the connection works independently with:

claude mcp list  # Should show "Connected"

Self-hosted Huly: account locked after failed login attempts

Huly locks password login after 5 failed API authentication attempts. This commonly happens during initial setup when the password is misconfigured. The lock persists in the database across service restarts.

Symptoms: PasswordLoginLocked error from the MCP server, and the Huly web UI shows "Password login is locked due to too many failed attempts. Please use an OTP login method to unlock your account." (OTP won't work without SMTP configured.)

Fix — reset the lock counter in CockroachDB:

# Find your account UUID and check lock status
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "SELECT uuid, failed_login_attempts FROM global_account.account;"

# Reset the counter
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "UPDATE global_account.account SET failed_login_attempts = 0 WHERE uuid = '<your_account_uuid>';"

The CockroachDB credentials can be found in your Huly compose.yml or via docker exec <cockroach_container> env | grep COCKROACH.

Windows-specific notes

• Bash wrapper scripts (sourcing .env files) may not work reliably when launched by MCP clients on Windows. Prefer setting env vars directly in the MCP config JSON.
• Docker pulls over SSH may fail on Windows due to credential manager issues. Pull images from the server desktop if needed.