@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": "your@email.com",
        "HULY_PASSWORD": "yourpassword",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

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

[mcp_servers.huly]
command = "npx"
args = ["-y", "@firfi/huly-mcp@latest"]

[mcp_servers.huly.env]
HULY_URL = "https://huly.app"
HULY_EMAIL = "your@email.com"
HULY_PASSWORD = "yourpassword"
HULY_WORKSPACE = "yourworkspace"

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 @firfi/huly-mcp@latest

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

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

Updating

The @latest tag asks the package runner for the newest version. Some MCP clients keep server processes or resolved installs alive, so restart or re-add the server when updating:

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

HTTP MCP Protocol Support

The HTTP server supports both the existing SDK initialize-compatible Streamable HTTP flow and the 2026 stateless HTTP flow at the same /mcp endpoint. Dispatch is per request:

• Requests with MCP-Protocol-Version: 2026-07-28, matching _meta.io.modelcontextprotocol/protocolVersion, or server/discover use the 2026 stateless dispatcher.
• Requests without 2026 protocol signals continue through the SDK transport for compatibility with existing clients.

The 2026 path requires one JSON-RPC message per POST, Accept: application/json, text/event-stream, Mcp-Method, method-specific Mcp-Name, and per-request _meta.io.modelcontextprotocol/* client metadata. Huly credentials are still configured separately through env vars or supported x-huly-* headers.

For hosted or tunneled HTTP deployments, you can require an MCP endpoint bearer token:

MCP_TRANSPORT=http \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
npx -y @firfi/huly-mcp@latest

HTTP clients must then send:

Authorization: Bearer <MCP_AUTH_TOKEN>

MCP_AUTH_TOKEN protects only the MCP HTTP /mcp endpoint. It is unrelated to HULY_TOKEN, does not authenticate to Huly, and does not replace HULY_EMAIL / HULY_PASSWORD / HULY_TOKEN. Huly credentials are still required through process env vars or, for hosted URL deployments, the supported x-huly-* headers. Stdio deployments do not use MCP_AUTH_TOKEN.

Hosted HTTP Header Configuration

For hosted URL deployments, keep the server process configured with MCP_TRANSPORT=http. A hosting layer can forward per-session Huly credentials as request headers, so one hosted server can serve different Huly workspaces without process-wide HULY_* env vars.

Supported v1 headers:

If any x-huly-* header is present, all required headers must be present. Missing values are not filled from environment variables. Email/password auth is not supported in hosted header configuration v1.

For a Smithery publish schema example, see docs/SMITHERY_URL_PUBLISH.md.

Environment Variables

*Auth: Provide either HULY_EMAIL + HULY_PASSWORD or HULY_TOKEN.

Built-in Diagnostic Tools

get_version returns the current server version and latest npm version.

get_huly_context returns sanitized runtime/configuration context for the current MCP session without connecting to Huly. It reports package version, transport, auth mode, sanitized Huly URL origin/host/protocol, workspace, timeout, config sources, and toolset filtering. Tokens, passwords, email values, credential headers, URL paths, URL query strings, and URL credentials are never returned.

MCP Resources

The server exposes read-only MCP Resources as JSON context for clients that support resources/read.

resources/list returns concrete active project resources. Issue resources are template-based: use resources/templates/list to discover supported issue URI templates, then read a known issue URI.

Roadmap

The roadmap is driven by SDK parity and the project principle that this server should expose LLM-first tools: clear names, self-contained parameters, automatic identifier resolution, and single-call correctness. The audited source of truth lives in plans/huly-sdk-gap-matrix.md, with machine-checkable classifications in plans/sdk-parity-ledger.json.

Highest-value additions for coding agents:

• Generic space follow-ups: role assignment mutations, role/permission definition writes, generic space creation, and module-specific wrappers above the shared space foundation.
• SDK discovery phase 2: space types, roles, permissions, plugin configuration, sequence metadata, and richer tool hints.
• Drive tools: drive spaces, folders, files, file versions, path traversal, moves, permissions, and comments/activity.
• Planner/ToDos: personal and project ToDo CRUD, scheduling, complete/reopen, priority, privacy/visibility, and document action items.
• Recruiting: vacancies, candidates, applications, application statuses, recruiter assignment, reviews, opinions, skills, and related comments/attachments/activity.
• Controlled documents and trainings: controlled document spaces/projects, review/approval workflows, templates, categories, snapshots/history, training assignments, attempts, scoring, and results.
• Module-specific tag wrappers for tag-backed concepts such as recruiting skills, board labels, controlled-document labels, and contact tags.

Planned feature surfaces:

• Implemented foundation: generic space discovery and safe existing-space administration are covered by spaces tools for listing/getting spaces, listing/getting space types, reading permissions, updating common metadata, adding/removing members, and replacing owners.
• Controlled Documents / TraceX documents: controlled spaces/projects, controlled document CRUD, quality/technical docs, co-authors/reviewers/approvers, e-signature workflows, release/effective-date metadata, change control, training linkage, controlled-document comments, and snapshots/history.
• Products and product versions: product spaces, members, descriptions, attachments, versions, version state transitions, and change-control links.
• Trainings, questions, and assessments: training revisions, releases, requests, due dates, max attempts, question banks, answer options, correct-answer data, submissions, scoring, and reporting.
• Drive: drives, folders, files, file versions, current-version selection, path traversal, moves, uploads, comments/activity, and permissions/members.
• HR: departments, nested departments, staff mixins, managers, subscribers, team leads, request types, PTO/sick/overtime/remote requests, public holidays, and schedule/table reports.
• Recruiting: vacancies, talents/candidates, applications, matches, reviews, verdicts/opinions, vacancy-company lists, skills, and recruiting-specific custom fields/relations.
• Surveys and polls: survey CRUD, poll creation/attachment, survey question data, completion status, and results.
• Generic approval requests: create/list/approve/reject/cancel approval requests, decision comments, required approval counts, request status, and requested/approved/rejected people.
• Boards: board CRUD, board cards, status workflows, members/assignees, location, cover/archive fields, board labels, and menu/archive views.
• Inventory: categories, products, variants/SKUs, product photos, attachments, activity/comments, and hierarchy tools.
• Leads write surface: create/update/delete funnels and leads, status changes, assignment, start dates, customer descriptions, person customer support, and lead comments/attachments/labels/relations.
• Contacts: person channels, social identities, provider discovery, contact statuses, notes/comments, person attachments, person merge, employee invite/create/kick/reinvite, and inactive employee management.
• Calendar: calendar CRUD/config, external calendar sync metadata, primary calendar management, schedule objects, participant mutations, and RSVP/status support when stable.
• Team planner and schedule reporting: team agendas, workload/capacity summaries, and visibility-aware free/busy views across members/projects.
• Virtual office and meetings: offices, floors, rooms, access/language/default recording/transcription settings, meeting schedules, active participants, room info, meeting minutes, transcripts, recordings, and device preferences.
• Chat and communication: direct-message send/update/delete, group DMs, channel member mutations, join/leave/request access, archive/unarchive, star/favorite channels, close/reopen conversations, pinned messages, message attachments, translation, applets, in-message polls, and guest communication settings.
• Notifications and activity: mark unread, unarchive, hide/unhide/mute contexts, unsubscribe per context/type, notification type settings, collaborators, pin/unpin activity messages, generic activity replies, filters, references, mentions, and update-message introspection.
• Attachments and media: saved attachments, photos, drawings, embeddings, previews/preview metadata, and friendly wrappers for additional object types.
• Core schema and workspace administration: attribute/property create/update/delete/hide, enum CRUD/options, sequence management, role assignment mutations, role/permission definition writes, generic space creation, global space admins, integrations registry, invite settings, role capability settings, and workspace setting metadata.
• Integrations: GitHub repository/project mappings and sync metadata, Google Calendar connect/configure/sync controls, Bitrix entity/field mappings and sync status, Gmail/email channel messages, Telegram messages, Huly Mail/Mail plugin behavior, AI assistant integration state, and AI bot configuration if server-side APIs expose stable behavior.
• Templates, rating, support, billing, analytics, views, workbench, and preferences: message templates/categories/fields, document/person rating data, support conversations, billing tier/status discovery, onboarding channels, saved filtered views, user view preferences, tabs/widgets/apps, and module preference discovery/update.
• Document-specific gaps: document snapshots/history, backlinks, notes, structured action items/tables, PDF/export, advanced document relationships, and document printing/export once SDK support is safe.

MCP resource roadmap:

• Return resource links from list/search tool results for direct resources/read follow-up.
• Add document resources when document reads have a stable URI shape and context-friendly payload.
• Consider scoped/paginated issue listing only when filters prevent very large resources/list responses.
• Consider resource subscribe and listChanged support after stateful sessions and a Huly change source are available.

SDK upgrade revisit:

• Revisit @hcengineering/* upgrades when a newer release is available after 0.7.423.
• Verify published tarballs, not only npm metadata, before accepting SDK upgrades.
• Require valid published declaration files for direct Huly dependencies.
• Upgrade direct Huly package declarations coherently in package.json; do not accept lockfile-only transitive rewrites.
• Run pnpm check-all and local Huly integration tests before treating an SDK upgrade as viable.

Available Tools

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

Projects

Issues

Comments

Milestones

Documents

Storage

Attachments

Contacts

Channels

Calendar

Time Tracking

Search

Associations

Activity

Notifications

Workspace

Cards

Custom-Fields

Labels

Leads

Processes

Sdk-Discovery

Spaces

Tag-Categories

Tags

Task-Management

Test-Management

User-Statuses

Troubleshooting

Passwords with special characters

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

Solution: Edit your MCP config file directly instead of passing the password through the shell:

• Codex: ~/.codex/config.toml
• Claude Code: ~/.claude.json (user scope) or .mcp.json (project scope)
• Claude Desktop: claude_desktop_config.json in the location listed in the installation section
• VS Code and Cursor: use the client config location from the installation section; avoid committing workspace files that contain real credentials
• Windsurf: edit your Windsurf MCP configuration file directly
• OpenCode: ~/.config/opencode/opencode.json

For Claude JSON config, the shell-sensitive characters above can be written directly. JSON-reserved characters such as " and \ still need normal JSON escaping:

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "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.