Huly

You set up and run an MCP server that bridges your Huly workspace with MCP clients, enabling streamlined project, issue, document, and channel management through a single, configurable endpoint.

How to use

You connect MCP clients to the Huly MCP Server by configuring either the local stdio server or the HTTP transport so clients can issue commands and receive responses. The server exposes a wide set of tools to manage projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, and more. Start the server with the appropriate transport, then point your MCP client to the local HTTP endpoint or to the standard in/out stream, depending on your workflow.

How to install

Prerequisites: you need Node.js and npm or npx available on your system. The MCP server is run using the npx-based command shown in the examples.

# Standard local MCP server (stdio transport)

npx -y @firfi/huly-mcp@latest

# HTTP transport (enable local HTTP endpoint on port 3000 by default)
MCP_TRANSPORT=http HULY_URL=https://huly.app \
HULY_EMAIL=your@email.com \
HULY_PASSWORD=yourpassword \
HULY_WORKSPACE=yourworkspace \
MCP_HTTP_PORT=3000 MCP_HTTP_HOST=127.0.0.1 npx -y @firfi/huly-mcp@latest

Additional configuration and usage notes

HTTP transport defaults set up a local HTTP server at http://127.0.0.1:3000/mcp. You can override the port and host with MCP_HTTP_PORT and MCP_HTTP_HOST. When using HTTP, include the Huly connection details through environment variables, and specify the workspace you will operate in. The server can expose a wide range of tool categories depending on your configuration and permissions.

Security considerations

Securely configure credentials for Huly access. Use API tokens or email/password combinations as described, and avoid exposing sensitive values in logs or plaintext configuration files. When using HTTP transport, restrict access to trusted networks or employ additional security controls as needed.

Troubleshooting tips

If you encounter connection issues, verify that MCP_TRANSPORT is set correctly for your chosen transport, the Huly URL, and workspace values are correct, and that the local HTTP endpoint is reachable. Check that the server process started without errors and that the environment variables are in place before launching.

Available tools

list_projects

List all Huly projects, sorted by name, with optional archived filter.

list_issues

Query issues with filters, sort by modification date, and search by title or description.

get_issue

Retrieve full details for a specific issue, including markdown content and metadata.

create_issue

Create a new issue in a Huly project with markdown-enabled description.

update_issue

Update fields on an existing issue, with markdown-capable descriptions.

add_issue_label

Add or create a label on an issue.

delete_issue

Permanently delete an issue.

list_components

List components within a project, sorted by modification date.

get_component

Retrieve full details for a component.

create_component

Create a new component within a project.

update_component

Update fields on an existing component.

set_issue_component

Set or clear the component for an issue.

delete_component

Permanently delete a component.

list_issue_templates

List issue templates within a project.

get_issue_template

Retrieve details for a specific issue template.

create_issue_template

Create a new issue template.

create_issue_from_template

Create an issue from a template with overrides.

update_issue_template

Update fields on an existing issue template.

delete_issue_template

Permanently delete an issue template.

list_comments

List comments on an issue, oldest to newest.

add_comment

Add a markdown-enabled comment to an issue.

update_comment

Update an existing comment with markdown content.

delete_comment

Permanently delete a comment.

list_milestones

List milestones in a project, newest to oldest.

get_milestone

Retrieve full details for a milestone.

create_milestone

Create a new milestone in a project.

update_milestone

Update fields on an existing milestone.

set_issue_milestone

Set or clear the milestone on an issue.

delete_milestone

Permanently delete a milestone.

list_documents

List documents in a teamspace, with markdown content support.

get_document

Retrieve full details for a document, including markdown content.

create_document

Create a new document with markdown content.

update_document

Update document fields with markdown support.

delete_document

Permanently delete a document.

upload_file

Upload a file to storage and obtain a blob reference.

list_attachments

List attachments on an object, newest first.

get_attachment

Retrieve attachment details including download URL.

add_attachment

Add an attachment from a local path, URL, or base64 data.

update_attachment

Update attachment metadata.

delete_attachment

Permanently delete an attachment.

pin_attachment

Pin or unpin an attachment.

download_attachment

Receive download URL and metadata for an attachment.

add_issue_attachment

Add an attachment to an issue by locating the issue via project and identifier.

add_document_attachment

Add an attachment to a document by locating the document.

list_channels

List all channels with filters by name or topic.

get_channel

Retrieve channel details including topic and members.

create_channel

Create a new channel in Huly.

update_channel

Update channel fields.

delete_channel

Permanently delete a channel.

list_events

List calendar events with date range filtering.

get_event

Retrieve full details for a calendar event.

create_event

Create a new calendar event with markdown-enabled description.

update_event

Update calendar event fields with markdown support.

delete_event

Permanently delete a calendar event.

list_time_spend_reports

List time entries across issues, filterable by project and date range.

log_time

Log time spent on an issue with optional description.

start_timer

Start a client-side timer for an issue; use later with log_time.

stop_timer

Stop the client-side timer and record the elapsed time.

fulltext_search

Perform a global search across content for relevant items.