Claude Code용 MCP Jira 서버

Claude Code와 Jira를 통합하기 위한 포괄적인 MCP(Model Context Protocol) 서버입니다. 이 서버는 이슈 관리, 스프린트 작업, 댓글, 첨부 파일 및 일괄 처리를 포함한 완전한 Jira 기능을 제공합니다.

License: MIT TypeScript Node.js

⚠️ 보안 주의: API 토큰을 절대 커밋하지 마십시오! 환경 변수(예: ~/.zshrc)나 보안 관리 도구를 사용하십시오.

🚀 기능

📋 이슈 관리 (12개 도구)

create-issue - 사용자 정의 필드 및 날짜를 포함한 전체 필드 지원으로 이슈 생성
update-issue - 스마트 필드 처리를 사용하여 기존 이슈 업데이트
get-issue - 상세 이슈 정보 검색
search-issues - JQL 또는 날짜 지원이 포함된 단순화된 필터를 사용한 고급 검색
transition-issue - 워크플로우 상태를 통해 이슈 이동
link-issues - 이슈 간 관계 생성 (스마트 유형 매칭 포함)
get-link-types - 사용 가능한 이슈 링크 유형 나열
get-fields - 프로젝트/이슈 유형에 사용 가능한 필드 표시
diagnose-fields - 필드 구성 문제 해결 및 사용자 정의 필드 ID 찾기
create-epic-with-subtasks - 한 번의 작업으로 여러 하위 작업이 포함된 에픽 생성
create-task-for-epic - 에픽에 연결된 작업 생성 (로컬라이즈된 Jira에 최적화)

💬 댓글 및 기록 (3개 도구)

get-comments - 작성자 및 타임스탬프 정보와 함께 이슈 댓글 읽기
get-history - 필드 수정 사항이 포함된 상세 변경 기록 보기
add-comment - Atlassian Document Format 지원으로 댓글 추가
batch-comment - 여러 이슈에 동시에 동일한 댓글 추가

📎 첨부 파일 (2개 도구)

get-attachments - 메타데이터(크기, 유형, 업로드 날짜)와 함께 첨부 파일 나열
upload-attachment - base64 인코딩을 사용하여 파일 업로드

🏃 스프린트 및 애자일 관리 (4개 도구)

get-boards - 애자일 프로젝트에 사용 가능한 Jira 보드 나열
get-sprints - 상태 표시기가 포함된 보드의 스프린트 보기
move-issue-to-sprint - 스프린트와 백로그 간 이슈 이동
create-sprint - 선택적 시작/종료 날짜로 새 스프린트 생성

리소스

jira://projects - 액세스 가능한 모든 프로젝트 나열
jira://project/{key} - 특정 프로젝트 세부 정보 가져오기
jira://issue/{key} - 특정 이슈 세부 정보 가져오기
jira://myself - 현재 사용자 정보
jira://search?jql={query} - 검색 결과

프롬프트

standup-report - 일일 스탠드업 보고서 생성
sprint-planning - 스프린트 계획 활동 지원
bug-triage - 버그 우선순위 지정 및 분류 지원
release-notes - 완료된 이슈에서 릴리스 노트 생성
epic-status - 포괄적인 에픽 진행 상황 보고서

설치

저장소 복제:

git clone https://github.com/tom28881/JIRA_MCP.git
cd JIRA_MCP

종속성 설치:

npm install

프로젝트 빌드:

npm run build

환경 변수에 Jira 자격 증명 구성 (예: ~/.zshrc):

Jira Cloud의 경우:

export JIRA_HOST=https://your-company.atlassian.net
export JIRA_EMAIL=your-email@company.com
export JIRA_API_TOKEN=your-api-token

Jira Server/DC 9.12+의 경우:

export JIRA_HOST=https://jira.your-company.com
export JIRA_PAT=your-personal-access-token

Jira Server/DC (레거시)의 경우:

export JIRA_HOST=https://jira.your-company.com
export JIRA_USERNAME=your-username
export JIRA_PASSWORD=your-password

전체 인증 가이드는 docs/AUTH_SETUP.md를 참조하십시오.

자격 증명 얻기

Jira Cloud (API 토큰)

Atlassian 계정 설정에 로그인
"Create API token" 클릭
이름 지정 (예: "MCP Server")
토큰을 복사하여 셸 구성(예: ~/.zshrc)에 JIRA_API_TOKEN으로 추가

Jira Server/DC 9.12+ (개인 액세스 토큰)

Jira Server/DC에 로그인
프로필 → 개인 액세스 토큰으로 이동
토큰 생성 클릭
이름 및 만료일 설정 (최대 365일)
즉시 토큰 복사 — 다시 볼 수 없습니다
셸 구성(예: ~/.zshrc)에 JIRA_PAT으로 추가

자세한 설정 지침은 docs/AUTH_SETUP.md를 참조하십시오.

Claude Code 구성

Claude Code와 이 MCP 서버를 사용하려면 MCP 설정에서 구성해야 합니다.

옵션 1: 환경 변수 사용 (권장)

셸 구성(예: ~/.zshrc)에서 환경 변수로 서버 설정:

# Add to ~/.zshrc
export JIRA_HOST="https://your-company.atlassian.net"
export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_DEFAULT_PROJECT="PROJ"

# Restart terminal or run: source ~/.zshrc
# Then run Claude Code with the MCP server
claude --mcp "node /absolute/path/to/mcp-jira-server/dist/index.js"

옵션 2: Claude Code 설정에 추가

Claude Code 설정 파일(~/.claude/settings.json)에 서버 추가:

{
  "mcpServers": [
    {
      "name": "jira",
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-server/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  ]
}

사용 예시

이슈 생성

Create a new bug in project PROJ with high priority about login issues

Create a story "Implement user authentication" with 5 story points and assign it to john@example.com

날짜 및 시간 추정치 설정

Create task "Database backup" with dueDate "next week" and originalEstimate "4h"

Update PROJ-123 with startDate "tomorrow" and dueDate "+14d"

Create issue "Quarterly review" with dueDate "31.3.2025" and originalEstimate "2 days"

하위 작업이 포함된 에픽 생성

Create an epic "Database Migration" in project PROJ with subtasks "Backup current data" and "Migrate schema"

하위 작업 생성

Create a subtask "Review code" for parent issue PROJ-123

체코어 Jira 지원

Create issue type "Úkol" in project PROJ

Create task for epic PPC-48 with summary "Database backup"

이슈 검색

Find all open bugs assigned to me

Search for issues in project PROJ with label "urgent" that are not done

날짜 기반 검색

Search issues due before "next week" in project PROJ

Find issues created after "2024-12-01" and updated after "yesterday"

Search for overdue issues: dueBefore "today" and status != "Done"

이슈 관리

Update PROJ-123 to add story points 8

Transition PROJ-456 to "In Progress"

Link PROJ-123 to PROJ-456 as "blocks"

참고: 에픽-스토리 관계는 일반 이슈 링크가 아닌 epicLink 필드를 사용합니다:

Update PROJ-456 with epicLink "PROJ-100"  # Links story to epic

프롬프트 사용

Generate a standup report for john@example.com

Help me plan the sprint for project PROJ

Create release notes for version 2.0 in project PROJ

고급 구성

사용자 정의 필드

이 서버는 모든 Jira 구성에서 작동할 수 있습니다:

옵션 1: 자동 감지 (권장)

환경 구성에서 사용자 정의 필드 ID를 설정하지 않은 상태로 두면 서버가 필드 이름을 기반으로 자동으로 감지합니다.

옵션 2: 수동 구성

자동 감지가 작동하지 않으면 환경(예: ~/.zshrc)에서 사용자 정의 필드 ID를 구성하십시오:

export JIRA_FIELD_STORY_POINTS=customfield_10001
export JIRA_FIELD_ACCEPTANCE_CRITERIA=customfield_10002
export JIRA_FIELD_EPIC_LINK=customfield_10003

필드 ID 찾기

diagnose-fields 도구를 사용하여 Jira 인스턴스에 맞는 올바른 필드 ID를 찾으십시오:

diagnose-fields project:"PROJ" issueType:"Story"

테스트 티켓 자동 생성

스토리에 대한 자동 테스트 티켓 생성 활성화:

AUTO_CREATE_TEST_TICKETS=true

개발

개발 모드에서 실행

npm run dev

유형 검사

npm run typecheck

린팅

npm run lint

기능

🌍 로컬라이제이션 지원

로컬라이즈된 Jira 인스턴스(체코어, 영어 등) 자동 지원
이슈 유형 이름은 모든 언어로 가능 (예: "Task", "Úkol", "Aufgabe")
우선순위 이름 로컬라이제이션 지원 (예: "High", "Vysoká", "Hoch")
체코어 Jira 구성을 위한 특별 지원
모든 Jira 언어 설정에서 작동

📅 날짜 및 시간 관리

유연한 날짜 입력 형식:
- ISO: "2024-12-31"
- 유럽식: "31.12.2024" 또는 "31/12/2024"
- 상대적: "today", "tomorrow", "next week", "+7d", "+2w", "+1m"
- 체코어: "dnes", "zítra", "příští týden"
시간 추적 지원:
- 추정치: "2h", "1d 4h", "3 days", "2 hodiny"
- 자동 형식 변환
날짜 기반 검색 및 필터링

🔄 자동 재시도

서버는 지수 백오프(최대 3회 시도)를 사용하여 실패한 요청을 자동으로 재시도합니다.

📦 강력한 오류 처리

Jira 전환에 대한 빈 응답 처리
컨텍스트가 포함된 상세 오류 메시지
누락된 기능에 대한 우아한 저하(Graceful degradation)

📝 포괄적인 로깅

디버그 로깅을 활성화하여 상세 정보 확인:

DEBUG=* claude --mcp "./run.sh"
# or specific to jira-mcp:
DEBUG=jira-mcp claude --mcp "./run.sh"

🔒 연결 테스트

서버는 시작 시 연결을 테스트하고 인증 실패 시 명확한 오류 메시지를 제공합니다.

📄 Atlassian Document Format

일반 텍스트와 마크다운을 리치 텍스트 필드를 위한 Jira의 ADF 형식으로 자동 변환합니다.

문제 해결

다양한 Jira 구성 작업

이 MCP 서버는 다음 사항에 관계없이 모든 Jira 인스턴스에서 작동하도록 설계되었습니다:

언어 설정 (영어, 체코어, 독일어 등)
사용자 정의 필드 구성
프로젝트별 설정

모범 사례:

get-fields를 사용하여 해당 언어로 사용 가능한 이슈 유형 확인
diagnose-fields를 사용하여 사용자 정의 필드 ID 찾기
Jira의 정확한 이슈 유형 이름을 사용하여 이슈 생성

일반적인 문제

인증 실패
- API 토큰이 올바른지 확인
- 이메일이 Atlassian 계정과 일치하는지 확인
- Jira 인스턴스 URL에 https://가 포함되어 있는지 확인
프로젝트를 찾을 수 없음
- 프로젝트에 대한 액세스 권한이 있는지 확인
- 프로젝트 키가 올바른지 확인 (대소문자 구분)
사용자 정의 필드가 작동하지 않음
- diagnose-fields 도구를 사용하여 프로젝트에 맞는 올바른 필드 ID 찾기
- get-fields 도구를 사용하여 사용 가능한 모든 필드 확인
- 사용자 정의 필드 ID는 일반적으로 customfield_로 시작
- 일부 필드는 특정 이슈 유형에 사용하지 못할 수 있음 (예: 에픽의 라벨)
- 에픽 링크 필드 ID는 Jira 인스턴스마다 다름
링크 유형을 찾을 수 없음
- get-link-types 도구를 사용하여 사용 가능한 링크 유형 확인
- 링크 유형은 Jira API에서 대소문자를 구분함
- 서버는 대소문자를 구분하지 않고 일치시키려고 시도함
- 에픽-스토리 관계는 일반 이슈 링크가 아닌 epicLink 필드를 사용함
에픽-스토리 연결 문제
- 프로젝트 및 "Story" 이슈 유형에 대해 diagnose-fields 실행
- 환경 구성에서 JIRA_FIELD_EPIC_LINK를 올바른 필드 ID로 업데이트
- 업데이트 후 터미널을 다시 시작하거나 source ~/.zshrc 실행

디버그 모드

상세 로깅을 위해 DEBUG 환경 변수 설정:

DEBUG=* claude --mcp "./run.sh"
# or
DEBUG=jira-mcp claude --mcp "./run.sh"

로그 보기

로그는 stderr로 출력되며 다음을 포함합니다:

연결 상태
API 요청 및 응답
컨텍스트가 포함된 오류 세부 정보
성능 지표

기여

개발 지침은 CONTRIBUTING.md를 참조하십시오.

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일 참조

지원

문제 및 기능 요청은 GitHub 이슈 트래커를 사용하십시오.