JIRA MCP 서버

이것은 JIRA와 상호작용하기 위한 도구를 제공하는 Model Context Protocol(MCP) 서버입니다. MCP 인터페이스를 통해 활성 스프린트의 티켓을 가져오고 상세 티켓 정보를 얻을 수 있습니다.

기능

서버는 다음 도구를 제공합니다:

1. list-sprint-tickets: 주어진 프로젝트의 활성 스프린트에 있는 모든 티켓을 가져옵니다

   • 필수 매개변수: projectKey (문자열)

2. get-ticket-details: 특정 티켓에 대한 상세 정보를 가져옵니다

   • 필수 매개변수: issueKey (문자열)

3. add-comment: 특정 티켓에 댓글을 추가합니다

   • 필수 매개변수: issueKey (문자열)

   • comment (문자열) 또는 filePath (문자열) 중 하나 — 파일에서 콘텐츠 편집 참조

   • 선택 매개변수: commentFormat — plain (기본값), wiki, markdown 또는 adf

4. link-tickets: 두 티켓을 '관련됨' 관계로 연결합니다

   • 필수 매개변수: sourceIssueKey (문자열)

   • 필수 매개변수: targetIssueKey (문자열)

5. update-description: 특정 티켓의 설명을 업데이트합니다

   • 필수 매개변수: issueKey (문자열)

   • description (문자열) 또는 filePath (문자열) 중 하나 — 파일에서 콘텐츠 편집 참조

   • 선택 매개변수: descriptionFormat — plain (기본값), wiki, markdown 또는 adf

6. list-child-issues: 상위 티켓의 모든 하위 이슈를 가져옵니다

   • 필수 매개변수: parentKey (문자열)

7. create-sub-ticket: 상위 티켓에 대한 하위 티켓(자식 이슈)을 생성합니다

   • 필수 매개변수: parentKey (문자열)

   • 필수 매개변수: summary (문자열)

   • 선택 매개변수: description (문자열) 또는 filePath (문자열) — 파일에서 콘텐츠 편집 참조

   • 선택 매개변수: issueType (문자열) - 하위 작업 이슈 유형의 이름 (예: 'Sub-task')

Related MCP server: mcp-jira

설정

1. 의존성 설치:

npm install

2. TypeScript 코드 빌드:

이 단계는 현재 npx 실행에 문제가 있는 Windows의 Cline에만 필요합니다.

npm run build

3. Claude 앱 설정 파일에 MCP 설정을 구성합니다 (macOS에서는 보통 ~/Library/Application Support/Claude/claude_desktop_config.json, Windows에서는 %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json에 위치):

Claude용 설정:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["path/to/this/repo/jira.ts"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cline용 설정:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["path/to/this/repo/dist/jira.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

구성

MCP 설정에서 다음 환경 변수를 설정해야 합니다:

1. JIRA_HOST: Atlassian 도메인 URL (예: https://your-company.atlassian.net)

2. JIRA_EMAIL: JIRA 계정 이메일

3. JIRA_API_TOKEN: JIRA API 토큰

   • Atlassian 계정 설정에서 API 토큰을 생성할 수 있습니다

사용법

구성이 완료되면 Claude의 MCP 인터페이스를 통해 도구를 사용할 수 있습니다:

스프린트 티켓 목록

프로젝트의 활성 스프린트에 있는 모든 티켓을 가져오려면:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>list-sprint-tickets</tool_name>
<arguments>
{
  "projectKey": "YOUR_PROJECT_KEY"
}
</arguments>
</use_mcp_tool>

티켓 상세 정보

특정 티켓에 대한 상세 정보를 가져오려면:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>get-ticket-details</tool_name>
<arguments>
{
  "issueKey": "PROJECT-123"
}
</arguments>
</use_mcp_tool>

파일에서 콘텐츠 편집

update-description, update-comment, add-comment, create-ticket 및 create-sub-ticket은 인라인 텍스트 대신 filePath를 허용합니다. 긴 콘텐츠를 위한 것입니다: 소스를 파일에 유지하고, 해당 파일을 편집한 후 다시 전송하세요 — 매번 도구 호출을 통해 전체 본문을 다시 게시할 필요가 없습니다. 두 생성 도구에서는 설명이 선택 사항으로 유지되므로 둘 다 생략해도 괜찮습니다.

형식은 확장자에서 추론되므로 descriptionFormat / commentFormat은 생략할 수 있습니다:

형식을 명시적으로 전달하면 확장자를 덮어씁니다. 이것이 다른 확장자를 가진 파일을 사용하는 방법이기도 합니다. 경로는 절대 경로이거나 서버의 작업 디렉터리를 기준으로 한 상대 경로입니다.

{
  "issueKey": "PROJECT-123",
  "filePath": "/abs/path/to/description.md"
}

빈 파일은 기존 설명이나 댓글을 지우는 대신 거부되며, 인라인 텍스트와 filePath를 모두 전달하면 오류입니다.

기존 콘텐츠 패치

이미 존재하는 설명이나 댓글의 일부를 변경하려면 먼저 export-content로 내보내고, 파일을 편집한 후 다시 업로드하세요 — 전체를 다시 작성할 필요가 없습니다:

{ "issueKey": "PROJECT-123", "commentId": "54660", "filePath": "/tmp/pir-timeline.md" }

내보내기는 해당 콘텐츠를 markdown으로 다시 업로드해도 안전한지 보고합니다. Jira는 콘텐츠를 ADF로 저장하며, 패널, 멘션, 상태 로젠지, 미디어, 테이블, 작업 목록 및 확장과 같은 구조는 markdown에 해당하는 것이 없습니다 — markdown으로 다시 업로드하면 조용히 누락됩니다. 이러한 항목이 있으면 도구가 경고하고 목록을 표시합니다. 대신 "format": "adf"로 내보내고 JSON을 패치하세요. JSON은 항상 정확히 왕복됩니다 (.json 파일은 업로드 시 ADF로 인식됩니다).

filePath를 생략하면 파일을 쓰는 대신 콘텐츠를 인라인으로 다시 받습니다. 댓글 ID는 get-ticket-details에 표시됩니다.

콘텐츠 버전 (낙관적 동시성)

update-description 및 update-comment는 교체되는 콘텐츠가 비어 있지 않을 때마다 expectedVersion을 요구합니다: 편집의 기반이 된 버전입니다. 그 사이에 Jira에서 콘텐츠가 변경된 경우, 해당 변경 사항을 조용히 버리는 대신 업데이트가 거부됩니다 — Confluence가 페이지 버전 번호로 얻는 것과 동일한 잠금입니다.

Jira에는 자체 버전 번호가 없으며, 이슈의 updated 타임스탬프는 대체물이 아닙니다: 이슈에 대한 모든 변경으로 이동하므로 전환, 라벨 및 새 댓글은 충돌하지 않은 설명 패치를 모두 거부할 수 있습니다. 따라서 버전은 콘텐츠 자체의 해시입니다 (v1-…). 패치 대상이 변경될 때 정확히 변경됩니다.

버전은 export-content와 get-ticket-details에서 제공되며, get-ticket-details는 Description version:과 모든 댓글에 대한 version:을 보고합니다 — 따라서 작은 인라인 편집은 내보내기 왕복이 필요 없습니다.

설명을 처음 작성할 때는 버전이 필요 없습니다. expectedVersion을 생략하는 것 자체가 "아직 여기에 아무것도 없다"는 주장이며, 서버가 이를 확인합니다: 설명이 여전히 비어 있으면 쓰기가 통과되고, 그 사이에 누군가 작성한 경우 — 현재 Jira에 있는 버전을 명명하며 — 거부됩니다. 따라서 잠금은 호출자가 빈 콘텐츠의 버전을 가져올 필요 없이 첫 번째 쓰기도 보호합니다.

"force": true를 전달하면 검사를 건너뛰고 무조건 덮어씁니다.

개발

서버는 TypeScript로 작성되었으며 다음을 사용합니다:

• MCP 서버 구현을 위한 @modelcontextprotocol/sdk

• JIRA API 통합을 위한 jira.js

권장 스크립트:

• 1회 빌드: npm run build

• 빌드 및 감시: npm run build:watch

• 타입 검사만: npm run typecheck

• 감시 모드 개발 실행: npm run start:dev

• 컴파일된 서버 실행: npm start

• 형식 검사: npm run fmt:check

• 형식 쓰기: npm run fmt

일반적인 워크플로:

1. jira.ts를 변경합니다

2. 개발 중에는 npm run start:dev를 실행하거나, 컴파일 실행을 위해 npm run build 후 npm start를 실행합니다

3. 변경 사항을 반영하려면 필요 시 MCP 클라이언트를 다시 시작합니다

오류 처리

서버에는 다음에 대한 오류 처리가 포함되어 있습니다:

• 잘못된 JIRA 자격 증명

• 활성 스프린트 없음

• 잘못된 프로젝트 키 또는 이슈 키

• 네트워크 오류

오류 메시지는 도구 응답으로 반환됩니다.