@firfi/huly-mcp

MCP server for Huly integration.

Installation

The standard configuration works with most MCP clients:

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

Claude Code

claude mcp add huly \
  -e HULY_URL=https://huly.app \
  -e [email protected] \
  -e HULY_PASSWORD=yourpassword \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/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", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://huly.app",
        "HULY_EMAIL": "[email protected]",
        "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.

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 @firfi/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 \
[email protected] \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @firfi/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 @firfi/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.

Available Tools

TOOLSETS categories: projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendar, time tracking, search, activity, notifications, workspace, cards, labels, tag-categories, test-management

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.
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) and relations (bidirectional links) with resolved identifiers. Does NOT return issues that this issue blocks — use list_issue_relations on the target issue to see that.

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). 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 markdown formatting. Returns the created document id.
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'.
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. Returns the created organization ID.

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

Calendar

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

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.

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.
get_regions	Get available regions for workspace creation. Returns region codes and display names.

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.

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.

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.

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.