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 @firfi/huly-mcp@latest — the -y flag skips the cache when @latest resolves to a new version

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

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.

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.

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.

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.

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). Supports searching by title substring (titleSearch) and content (contentSearch).

get_document

Retrieve full details for a Huly document including markdown content. 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). Returns the created document id. 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.

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.

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.

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.

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. Returns the created organization ID.

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.

list_direct_messages

List direct message conversations in Huly. Returns conversations sorted by date (newest first).

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.

Tool

Description

list_events

List calendar events. Returns events sorted by date. Supports filtering by date range.

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. 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. 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).

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.

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).

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.

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.

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.

get_regions

Get available regions for workspace creation. Returns region codes and display names.

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.

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.

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.

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.

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.