JIRA MCP 도구

Claude Desktop을 통해 JIRA API와 상호 작용하기 위한 모델 컨텍스트 프로토콜(MCP)입니다.

특징

• JQL(JIRA 쿼리 언어)을 사용하여 JIRA 문제 검색
• 인증된 사용자에 대한 JIRA 프로젝트 나열
• JIRA 이슈 생성, 업데이트 및 삭제
• 상태 간에 주석 및 전환 문제 추가
• 사용자 검색(GDPR 준수 지원)

설치

1. 이 저장소를 복제하세요:지엑스피1
2. 가상 환경을 만들고 활성화하세요.
   # On macOS/Linux python -m venv venv source venv/bin/activate # On Windows python -m venv venv .\venv\Scripts\activate
3. 종속성 설치:
   pip install -r requirements.txt
4. 프로젝트 루트에 .env 파일을 만듭니다.
   touch .env
5. JIRA 자격 증명을 .env 파일에 추가합니다.
   JIRA_SERVER=https://your-domain.atlassian.net JIRA_EMAIL=your.email@example.com JIRA_API_TOKEN=your_api_token_here
6. 설치를 테스트하세요:
   # Run all tests python -m pytest # Run a specific test file python -m pytest tests/test_search_issues.py
7. MCP 서버를 시작합니다.
   python run.py

환경 설정

JIRA API 토큰

JIRA 인스턴스를 인증하려면 JIRA API 토큰이 필요합니다.

1. Atlassian 계정에 로그인하세요
2. 계정 설정 > 보안 > API 토큰 생성 및 관리로 이동하세요.
3. "API 토큰 만들기"를 클릭하세요
4. 이름을 지정하세요(예: "Claude Desktop Integration")
5. "생성"을 클릭하고 생성된 토큰을 안전하게 저장하세요.

GDPR 준수

JIRA Cloud 인스턴스를 사용하는 경우(GDPR 엄격 모드일 가능성이 높음):

1. 사용자 검색은 표시 이름 및 이메일 주소와만 일치합니다.
2. 사용자 이름 기반 검색은 지원되지 않습니다.
3. 결과는 사용자 권한에 따라 제한될 수 있습니다.
4. 이 도구는 GDPR 요구 사항을 자동으로 처리하지만 검색 패턴을 조정해야 할 수도 있습니다.

문제 해결

일반적인 문제 및 해결 방법:

1. ModuleNotFoundError: 'src'라는 이름의 모듈이 없습니다.
   # Run with PYTHONPATH set PYTHONPATH=/path/to/mcp-jira python run.py
2. JIRA API 인증 오류
   • API 토큰이 올바른지 확인하세요
   • 귀하의 이메일이 Atlassian 계정과 일치하는지 확인하세요
   • JIRA 인스턴스 URL이 올바르고 'https://'를 포함하는지 확인하세요.
3. GDPR 관련 오류
   • "사용자 이름 매개변수가 지원되지 않음" 오류가 표시되면 인스턴스가 GDPR 모드에 있는 것입니다.
   • 사용자 이름 대신 표시 이름이나 이메일 주소를 사용하여 검색하세요.
   • 이 도구는 GDPR 준수를 위해 API 호출을 자동으로 조정합니다.

JIRA API 토큰 받기

1. Atlassian 계정에 로그인하세요
2. 계정 설정 > 보안 > API 토큰 생성 및 관리로 이동하세요.
3. "API 토큰 만들기"를 클릭하세요
4. 이름을 지정하세요(예: "Claude Desktop Integration")
5. "생성"을 클릭하고 생성된 토큰을 안전하게 저장하세요.

도구

검색 문제

JQL(JIRA 쿼리 언어)을 사용하여 JIRA 문제를 검색합니다.

매개변수:

• jql: JIRA 쿼리 언어 문자열(예: "project=DEMO AND status=Open")
• max_results: 반환할 최대 결과 수(기본값: 10)
• 필드: 결과에 포함할 필드의 쉼표로 구분된 목록(기본값: "summary, status, assignee, priority, issuetype")

문제 생성

지정된 프로젝트에서 새로운 JIRA 이슈를 만듭니다.

매개변수:

• project_key: 문제를 생성할 프로젝트의 키(예: "DEMO")
• 요약: 이슈 요약
• 설명: 문제 설명(선택 사항)
• issue_type: 문제 유형(기본값: "작업", "버그", "스토리" 등)
• 우선순위: 문제의 우선순위(선택 사항, 예: "높음", "보통", "낮음")
• 담당자: 문제를 할당할 사용자 이름(선택 사항)

업데이트 문제

기존 JIRA 이슈를 새로운 값으로 업데이트합니다.

매개변수:

• issue_key: JIRA 이슈 키(예: "PROJ-123")
• 요약: 해당 이슈에 대한 새로운 요약 (선택 사항)
• 설명: 문제에 대한 새로운 설명(선택 사항)
• 상태: 해당 이슈의 새로운 상태(선택 사항, 예: "진행 중", "완료")
• 우선순위: 문제에 대한 새로운 우선순위(선택 사항, 예: "높음", "보통", "낮음")
• 담당자: 해당 이슈에 대한 새로운 담당자(선택 사항)
• comment: 이슈에 추가할 코멘트 (선택 사항)

문제 삭제

JIRA 이슈를 삭제합니다(명시적인 확인이 필요합니다).

매개변수:

• issue_key: JIRA 이슈 키(예: "PROJ-123")
• 확인: 실수로 삭제되는 것을 방지하기 위한 확인 플래그입니다. True로 설정해야 합니다.

프로젝트 목록

인증된 사용자의 JIRA 프로젝트를 나열합니다.

매개변수:

• 제한: 반환할 프로젝트의 최대 개수(기본값: 10)

댓글 추가

기존 JIRA 이슈에 댓글을 추가합니다.

매개변수:

• issue_key: JIRA 이슈 키(예: "PROJ-123")
• comment: 문제에 추가할 코멘트 텍스트

전환 문제

JIRA 이슈를 새로운 상태로 전환합니다.

매개변수:

• issue_key: JIRA 이슈 키(예: "PROJ-123")
• 상태: 문제를 전환할 대상 상태(예: "진행 중", "완료")
• comment: 전환과 함께 추가할 선택적 주석

문제 세부 정보 가져오기

JIRA 문제에 대한 자세한 정보를 얻으세요.

매개변수:

• issue_key: JIRA 이슈 키(예: "PROJ-123")
• include_comments: 응답에 이슈 코멘트를 포함할지 여부(기본값: False)

사용자 검색

이름, 이메일 또는 사용자 이름으로 JIRA 사용자를 검색하세요. 이 도구를 사용하면 이슈를 할당하거나 감시자를 추가할 때 사용자를 쉽게 찾을 수 있습니다.

중요 참고 사항 : GDPR 엄격 모드가 활성화된 JIRA Cloud 인스턴스(최신 인스턴스의 기본값)의 경우, 사용자 검색은 username 대신 query 매개변수를 사용해야 합니다. 도구에서 자동으로 처리하지만, 검색 패턴을 적절히 조정해야 할 수도 있습니다.

매개변수:

• query (str): 사용자 표시 이름 및 이메일 주소와 일치시킬 검색 문자열
  • GDPR을 준수하는 인스턴스의 경우 표시 이름과 이메일 주소가 검색됩니다.
  • 검색은 대소문자를 구분하지 않으며 부분 문자열과 일치합니다.
  • 예: "john"은 "John Doe" 및 " johnny@example.com "과 일치합니다.
• max_results (int, 선택 사항): 반환할 최대 사용자 수(기본값: 10)
• include_active_users (bool, 선택 사항): 검색 결과에 활성 사용자 포함(기본값: True)
• include_inactive_users (bool, 선택 사항): 검색 결과에 비활성 사용자 포함(기본값: False)

사용 예:

GDPR 준수 참고 사항:

• GDPR 엄격 모드에서는 사용자 개인 정보를 보호하기 위해 사용자 검색이 더욱 제한적입니다.
• 검색은 사용자 표시 이름 및 이메일 주소에 대해서만 일치합니다.
• 정확한 사용자 이름 일치는 지원되지 않습니다.
• 검색은 항상 대소문자를 구분하지 않습니다.
• 부분 일치가 지원됩니다(예: "jo"는 "John"과 일치함)
• 결과는 사용자의 권한 및 개인정보 보호 설정에 따라 제한될 수 있습니다.

사용 예

개발

이 MCP를 수정하거나 확장하려는 개발자의 경우:

1. 저장소를 복제합니다
2. 가상 환경 설정: python -m venv venv && source venv/bin/activate
3. 종속성 설치: pip install -r requirements.txt
4. 테스트 실행: python -m pytest
5. 변경 사항을 만드세요
6. Claude Desktop으로 테스트