huly-mcp-sdk

Huly를 위한 가장 완벽한 MCP 서버 — 오픈소스 프로젝트 관리 플랫폼.

Claude Desktop(및 모든 MCP 호환 클라이언트)을 Huly 워크스페이스에 직접 연결합니다. 프로젝트, 이슈, 마일스톤, 컴포넌트, 문서, 라벨 등을 자연어로 관리하세요.

도구 (총 36개)

Related MCP server: Huly MCP Server

요구 사항

• Node.js >= 20

• Huly 계정 — huly.app (클라우드) 또는 자체 호스팅

빠른 시작

npx huly-mcp-sdk setup

이 명령은 대화형 설정 마법사를 실행합니다. 이메일로 일회용 코드를 보내고(Google/GitHub SSO 계정도 지원) .env 파일을 자동으로 작성합니다.

워크스페이스 slug는 Huly URL에서 도메인 뒤에 오는 부분입니다: huly.app/myteam → slug는 myteam입니다.

호환 클라이언트

동일한 MCP 서버가 모든 주요 AI 코딩 도구에서 작동합니다. 원하는 클라이언트를 선택하세요.

인증 참고: 아래 모든 구성 예시는 HULY_TOKEN을 사용합니다. 토큰 만료 문제가 있으면 대신 이메일 + 비밀번호를 사용하세요. env 블록을 다음으로 교체하면 됩니다:

"HULY_EMAIL": "your@email.com",
"HULY_PASSWORD": "yourpassword",
"HULY_WORKSPACE": "your-workspace-slug"

두 옵션에 대한 자세한 내용은 수동 인증을 참조하세요.

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

저장 후 Claude Desktop을 다시 시작하세요.

Claude Code (CLI)

claude mcp add huly -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk

또는 단일 프로젝트로만 범위를 제한하려면:

claude mcp add huly --scope project -e HULY_TOKEN=your-token -e HULY_WORKSPACE=your-slug -- npx huly-mcp-sdk

연결되었는지 확인: claude mcp list

Cursor

~/.cursor/mcp.json 파일을 생성하거나 편집하세요:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Cursor를 다시 시작하세요. 도구가 Agent 패널의 MCP 아래에 표시됩니다.

Windsurf (Codeium)

~/.codeium/windsurf/mcp_config.json 파일을 생성하거나 편집하세요:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Windsurf를 다시 시작하세요. MCP 도구를 Cascade AI 패널에서 사용할 수 있습니다.

VS Code — Cline 확장

1. Cline 확장을 설치하세요

2. Cline 설정 → MCP 서버 → MCP 설정 편집을 여세요

3. 추가하세요:

{
  "huly": {
    "command": "npx",
    "args": ["huly-mcp-sdk"],
    "env": {
      "HULY_TOKEN": "your-token",
      "HULY_WORKSPACE": "your-workspace-slug"
    }
  }
}

VS Code — Continue 확장

1. Continue 확장을 설치하세요

2. ~/.continue/config.json을 편집하고 mcpServers 배열에 추가하세요:

{
  "mcpServers": [
    {
      "name": "huly",
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  ]
}

Zed

~/.config/zed/settings.json을 편집하고 context_servers 항목을 추가하세요:

{
  "context_servers": {
    "huly": {
      "command": {
        "path": "npx",
        "args": ["huly-mcp-sdk"],
        "env": {
          "HULY_TOKEN": "your-token",
          "HULY_WORKSPACE": "your-workspace-slug"
        }
      }
    }
  }
}

OpenAI Codex CLI

~/.codex/config.json을 편집하고 mcpServers에 추가하세요:

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "npx",
      "args": ["huly-mcp-sdk"],
      "env": {
        "HULY_TOKEN": "your-token",
        "HULY_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

기타 MCP 호환 클라이언트

서버는 표준 stdio 전송을 사용합니다. 도구가 MCP를 지원한다면 구성 패턴은 항상 동일합니다:

• command: npx

• args: ["huly-mcp-sdk"]

• env: HULY_TOKEN + HULY_WORKSPACE

정확한 구성 파일 위치는 도구의 MCP 문서를 참조하세요.

대안 (npx 콜드 스타트 방지): 한 번 클론하고 빌드한 다음 컴파일된 바이너리를 직접 가리키세요:

git clone https://github.com/varaprasadreddy9676/huly-mcp.git
cd huly-mcp && npm install && npm run build

위의 모든 구성에서 "command": "npx", "args": ["huly-mcp-sdk"]를 "command": "node", "args": ["/absolute/path/to/huly-mcp/dist/index.js"]로 교체하세요.

예시 프롬프트

프로젝트 및 이슈:

• "'Mobile App'이라는 새 프로젝트를 식별자 MOBILE로 생성해 줘"

• "PROJ 프로젝트의 진행 중인 모든 이슈를 나열해 줘"

• "PROJ에 'Fix login timeout'이라는 제목의 높은 우선순위 이슈를 생성해 줘"

• "PROJ-42의 상태를 Done으로 업데이트하고, Sarah에게 할당한 다음 Auth 컴포넌트로 이동해 줘"

• "인증과 관련된 이슈를 검색해 줘"

• "PROJ-15에 수정 사항이 배포되었다는 댓글을 추가해 줘"

• "논의 내용을 보기 위해 PROJ-42의 모든 댓글을 나열해 줘"

마일스톤 및 컴포넌트:

• "PROJ에 목표 날짜 2026-06-01로 'v2.0 Launch' 마일스톤을 생성해 줘"

• "PROJ 프로젝트의 마일스톤을 나열해 줘"

• "PROJ에 'Auth'라는 컴포넌트를 생성해 줘"

• "PROJ의 모든 컴포넌트를 나열해 줘"

라벨 및 관계:

• "PROJ-42에 'bug' 라벨을 추가해 줘"

• "'backend'라는 라벨을 색상 #3b82f6으로 생성해 줘"

• "PROJ-55를 PROJ-12에 의해 차단된 것으로 표시해 줘"

• "PROJ-42를 PROJ-5의 하위 작업으로 설정해 줘"

시간 추적:

• "데이터베이스 리팩터링에 대해 PROJ-42에 2.5시간을 기록해 줘"

문서:

• "Engineering 팀스페이스의 모든 문서를 나열해 줘"

• "Engineering 팀스페이스에 'API Design'이라는 문서를 생성해 줘"

• "API Design 문서를 이 Markdown으로 업데이트해 줘: ..."

• "EP1 문서에 Mermaid 아키텍처 다이어그램을 추가해 줘"

• "문서 abc123을 이슈 PROJ-42에 연결해 줘"

• "PROJ-15의 두 번째 댓글을 삭제해 줘"

문서 콘텐츠

읽기: get_document

get_document는 항상 전체 메타데이터(제목, 팀스페이스, 댓글, 스냅샷)를 반환합니다. 텍스트 콘텐츠도 가져와 표시하려면 선택적 HULY_FRONT_URL 환경 변수를 설정하세요:

"env": {
  "HULY_TOKEN": "...",
  "HULY_WORKSPACE": "myteam",
  "HULY_FRONT_URL": "https://front.huly.app"
}

자체 호스팅 Huly의 경우 HULY_FRONT_URL을 자체 프론트 서비스 URL(예: http://localhost:8083)로 설정하세요.

쓰기: update_document

update_document는 documentId와 markdown 문자열을 받아 문서에 풍부한 구조화 콘텐츠를 직접 작성합니다. 수동 편집이 필요 없습니다.

지원되는 Markdown:

예시:

update_document({
  documentId: "abc123",
  markdown: `# Service Flow\n\n` +
    `## Architecture\n\n` +
    "```mermaid\n" +
    "flowchart TD\n" +
    "  A([User]) --> B[Browse Catalogue]\n" +
    "  B --> C[Pay via Razorpay]\n" +
    "  C --> D[Order Confirmed]\n" +
    "```\n\n" +
    "## Business Rules\n\n" +
    "- Payment required before confirmation\n" +
    "- All orders synced to HIS\n"
})

Mermaid 블록은 Huly의 문서 편집기에서 코드 블록이 아닌 라이브 대화형 다이어그램으로 렌더링됩니다.

대량 CSV 가져오기

CSV 파일에서 여러 이슈를 한 번에 가져옵니다. 다른 도구에서 마이그레이션할 때 유용합니다:

node scripts/import-csv.js tasks.csv PROJ

CSV 형식:

title,priority,status,dueDate
Fix login bug,High,In Progress,2025-04-01
Add dark mode,Medium,,
Improve performance,Urgent,,2025-05-01

필수 열: title. 선택: priority (Urgent/High/Medium/Low), status (프로젝트의 상태 이름과 일치해야 함), dueDate (YYYY-MM-DD).

수동 인증

프로젝트 루트에 .env 파일을 생성하세요(또는 클라이언트 구성의 env로 전달).

옵션 A — 이메일 + 비밀번호 (권장):

Huly 계정에 비밀번호가 설정되어 있으면 작동합니다 (프로필 → 보안 → 비밀번호 변경).

HULY_EMAIL=your@email.com
HULY_PASSWORD=yourpassword
HULY_WORKSPACE=your-workspace-slug

옵션 B — 토큰:

HULY_WORKSPACE=your-workspace-slug
HULY_TOKEN=your-token-here

토큰을 얻으려면: huly.app → 브라우저 DevTools 열기 → Application → Local Storage → https://huly.app → token 값을 복사하세요.

토큰은 일정 시간이 지나면 만료됩니다. 인증 오류가 발생하면 이메일 + 비밀번호 인증으로 전환하거나 DevTools에서 토큰을 새로 고치세요.

자체 호스팅 Huly:

HULY_ACCOUNTS_URL=https://your-huly-instance.com/account
HULY_FRONT_URL=https://your-huly-instance.com

아키텍처

• 단일 장기 WebSocket 연결 — @hcengineering/server-client를 통해 프로세스당 한 번 연결되며, 도구 호출마다 연결되지 않습니다 (모델 로드에 1~3초가 걸리므로 도구가 빠르게 유지됩니다)

• 지연 초기화 — 첫 번째 도구 호출 시 연결되어 인증 오류가 Claude에서 명확하게 표시됩니다

• 이중 인증 — OTP 토큰 (Google/GitHub SSO 지원) 또는 이메일 + 비밀번호

• Stdio 전송 — Claude Desktop 및 모든 MCP 클라이언트와 호환되는 표준 MCP 전송

변경 로그

v0.5.6 — delete_document

• 새 기능: delete_document — ID로 문서를 영구 삭제합니다

v0.5.5 — create_teamspace

• 새 기능: create_teamspace — 새 문서 teamspace를 생성합니다 (문서를 프로젝트나 팀별로 정리하기 위한 최상위 폴더)

v0.5.2 — delete_comment + link_document

• 새 기능: delete_comment — 이슈에서 특정 댓글을 ID로 삭제합니다. list_comments의 출력에 이제 댓글 ID가 포함됩니다

• 새 기능: link_document — Huly 문서를 이슈에 연결합니다. 연결된 문서는 이슈의 Relations 패널에 표시됩니다

v0.5.0 — 문서 작성 + 버그 수정

• 새 기능: update_document — 모든 Huly 문서에 프로그래밍 방식으로 Markdown을 작성합니다. \``mermaid` 블록은 Huly의 네이티브 노드 유형을 사용하여 대화형 다이어그램으로 렌더링됩니다

• 수정: IssueStatus 쿼리 — 상태는 프로젝트별이 아니라 Huly에 전역적으로 저장됩니다 (core:space:Model). create_issue, update_issue, list_issues에서 "no statuses found" 오류를 유발하던 잘못된 space 필터를 제거했습니다

• 수정: create_project — members: [currentUser]를 설정하여 새로 생성된 프로젝트가 Huly UI에 즉시 표시되도록 합니다

v0.4.0

• log_time, list_comments, update_issue의 컴포넌트/마일스톤 할당

v0.3.1

• get_document, create_document

v0.3.0

• create_project, create_milestone, 이슈 담당자 지정 지원

링크

• npm: https://www.npmjs.com/package/huly-mcp-sdk

• GitHub: https://github.com/varaprasadreddy9676/huly-mcp

• MCP Registry: https://registry.modelcontextprotocol.io ("huly-mcp" 검색)

라이선스

Eclipse Public License 2.0

Wait — in the v0.5.2 bullet, I wrote "list_comments의 출력에" and later "오류" etc. Good.

But there's a small issue: In the bullet for list_comments, I have "이슈에서 특정 댓글을" — the original says "delete a specific comment from an issue by ID; list_comments now includes comment IDs in its output". Good.

One more: The line "new- in v0.5.0" has the wrapped inline: I removed the semicolon and added "". Good.

Wait: Did I put an extra space before "(core:space:Model)" because the original "Huly (core:space:Model)" has a space before parenthesis. Yes, I wrote "Huly (core:space:Model)" with a space. That matches.

Also "new-issue" vs "no" — fine.

Now, if the user wants the translated text only, this is it. No code fences.

However, I need to verify the escaped code token one more time. In my final, I typed:

\``mermaid`

Let me check count: The sequence in my final line: "\``mermaid`". In plain text, I need to make sure it matches original. The original: "\``mermaid`". I think mine matches.

Let me visualize: After "작성합니다.", I need to type "\``mermaid` 블록은". My draft: "\``mermaid` 블록은". Hmm, that has "``" at start? Actually let's copy from my draft:

"\``mermaid`"

breakdown:

1. ` (backtick)

2. \ (backslash)

3. ` (backtick)

4. \ (backslash)

5. `

6. \

7. `

8. mermaid

9. \

10. So it's backtick, escaped backtick, escaped backtick, escaped backtick, mermaid, escaped backtick. That aligns with original: a backtick starts inline code with content "\``mermaid`". Yes.

Now, the Korean text "`로" blends with backtick; it's fine.

Now I'm satisfied.

But wait, final issue: I should decide the exact heading for "v0.5.0": I wrote "### v0.5.0 — 문서 작성 + 버그 수정". Good.

Now, the "License" line: I wrote "## 라이선스". Good.

Now final response.### v0.5.6 — delete_document

• 새 기능: delete_document — ID로 문서를 영구 삭제합니다

v0.5.5 — create_teamspace

• 새 기능: create_teamspace — 새 문서 teamspace를 생성합니다 (문서를 프로젝트나 팀별로 정리하기 위한 최상위 폴더)

v0.5.2 — delete_comment + link_document

• 새 기능: delete_comment — 이슈에서 특정 댓글을 ID로 삭제합니다. list_comments의 출력에 이제 댓글 ID가 포함됩니다

• 새 기능: link_document — Huly 문서를 이슈에 연결합니다. 연결된 문서는 이슈의 Relations 패널에 표시됩니다

v0.5.0 — 문서 작성 + 버그 수정

• 새 기능: update_document — 모든 Huly 문서에 프로그래밍 방식으로 Markdown을 작성합니다. \``mermaid` 블록은 Huly의 네이티브 노드 유형을 사용하여 대화형 다이어그램으로 렌더링됩니다

• 수정: IssueStatus 쿼리 — 상태는 프로젝트별이 아니라 Huly에 전역적으로 저장됩니다 (core:space:Model). create_issue, update_issue, list_issues에서 발생하는 "no statuses found" 오류를 유발하던 잘못된 space 필터를 제거했습니다

• 수정: create_project — members: [currentUser]를 설정하여 새로 생성된 프로젝트가 Huly UI에 즉시 표시되도록 합니다

v0.4.0

• log_time, list_comments, update_issue의 컴포넌트/마일스톤 할당

v0.3.1

• get_document, create_document

v0.3.0

• create_project, create_milestone, 이슈 담당자 지정 지원

링크

• npm: https://www.npmjs.com/package/huly-mcp-sdk

• GitHub: https://github.com/varaprasadreddy9676/huly-mcp

• MCP Registry: https://registry.modelcontextprotocol.io ("huly-mcp" 검색)

라이선스

Eclipse Public License 2.0