Jira MCP 서버

Jira와 상호작용하기 위한 도구를 제공하는 MCP(Model Context Protocol) 서버입니다. Cursor 및 기타 MCP 클라이언트가 티켓을 가져오고, 연결된 티켓을 관리하며, 티켓 상태를 업데이트할 수 있도록 지원합니다.

빠른 시작

1. 의존성 설치

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

2. Jira 자격 증명 구성

권장: 개인 액세스 토큰 (PAT)

1. Jira 로그인: https://jira.telekom.de

2. 프로필 > **개인 액세스 토큰(Personal Access Tokens)**으로 이동

3. "토큰 생성(Create token)" 클릭

4. 이름(예: "Cursor MCP")을 지정하고 만료일 설정

5. 중요: 토큰에 "읽기(Read)" 또는 "프로젝트 탐색(Browse Projects)" 권한이 있는지 확인

6. 토큰을 즉시 복사 (다시 볼 수 없음)

.env 파일 생성:

cp .env.example .env

자격 증명으로 .env 편집:

JIRA_URL=https://jira.telekom.de
JIRA_USERNAME=your.username@telekom.de
JIRA_API_TOKEN=your_personal_access_token_here
JIRA_AUTH_TYPE=bearer

참고: Kantega SSO API 토큰은 IP 제한이 있거나 관리자가 구성한 권한이 필요할 수 있습니다. 대부분의 사용자에게는 개인 액세스 토큰을 권장합니다.

3. Cursor에서 구성

1. Cursor 열기

2. **설정(Settings) > 도구 및 MCP(Tools and MCP)**로 이동

3. 다음 구성 추가:

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jira-mcp",
        "run",
        "-m",
        "src"
      ]
    }
  }
}

중요: 경로와 자격 증명을 실제 값으로 바꾸세요!

4. Cursor를 완전히 다시 시작

4. 사용해 보기

Cursor 채팅에서 다음을 시도해 보세요:

• "Get details for Jira ticket PROJ-123"

• "Show me all linked tickets for PROJ-456"

• "Update PROJ-789 status to In Progress"

기능

사용 가능한 도구

인증 지원

• Bearer 토큰: 개인 액세스 토큰 (PAT) - 권장

• 기본 인증(Basic Auth): 사용자 이름 + API 토큰 (Atlassian Cloud)

• 쿠키 인증(Cookie Auth): 세션 기반 인증 (대체 옵션)

도구 세부 정보

get_ticket

전체 티켓 정보를 가져옵니다.

매개변수:

• ticket_id (문자열, 필수): 티켓 ID 또는 키 (예: "PROJ-123")

반환값:

{
  "key": "PROJ-123",
  "summary": "Ticket summary",
  "description": "Detailed description",
  "status": "In Progress",
  "issue_type": "Story",
  "priority": "High",
  "assignee": "John Doe",
  "reporter": "Jane Smith",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-20T14:45:00.000+0000",
  "comments_count": 3,
  "comments": [...],
  "custom_fields": {...}
}

get_linked_tickets

모든 관련 티켓 및 하위 작업을 가져옵니다.

매개변수:

• ticket_id (문자열, 필수): 티켓 ID 또는 키

반환값:

{
  "ticket": "PROJ-123",
  "linked_tickets": [
    {
      "link_type": "Blocks",
      "direction": "blocks",
      "key": "PROJ-124",
      "summary": "Related ticket",
      "status": "To Do"
    }
  ],
  "linked_tickets_count": 1,
  "subtasks": [...],
  "subtasks_count": 2
}

update_ticket_status

워크플로우 유효성 검사를 통해 티켓 상태를 업데이트합니다.

매개변수:

• ticket_id (문자열, 필수): 티켓 ID 또는 키

• status (문자열, 필수): 대상 상태 (예: "In Progress", "Done")

반환값:

Successfully updated ticket PROJ-123 status from 'To Do' to 'In Progress'

참고: 이 도구는 전환을 검증합니다. 유효하지 않은 경우 사용 가능한 전환을 반환합니다.

테스트

테스트 실행

# Run all tests
.venv/bin/pytest tests/ -v

# Run with coverage
.venv/bin/pytest tests/ --cov=src -v

# Run specific test file
.venv/bin/pytest tests/test_integration/test_real_tickets.py -v

수동 테스트

서버를 직접 테스트:

uv run --env-file .env -m src

중지하려면 Ctrl+C를 누르세요.

문제 해결

인증 오류

증상: "401 Unauthorized" 또는 "403 Forbidden"

해결 방법:

• 가장 흔한 원인: 개인 액세스 토큰 만료 - 새로 생성하세요

• PAT에 "읽기" 또는 "프로젝트 탐색" 권한이 있는지 확인

• 사용자 이름이 Jira 계정 이메일과 일치하는지 확인

• JIRA_URL에 https://가 포함되어 있는지 확인

• 개인 액세스 토큰의 경우 JIRA_AUTH_TYPE=bearer인지 확인

티켓을 찾을 수 없음

증상: "404 Not Found"

해결 방법:

• 티켓 키가 올바른지 확인 (예: "PROJ-123")

• 티켓을 볼 수 있는 권한이 있는지 확인

• 올바른 Jira 인스턴스를 사용 중인지 확인

Cursor에 서버가 나타나지 않음

해결 방법:

• MCP 설정의 절대 경로 확인

• Python 3.12+ 설치 확인: python3 --version

• Cursor를 완전히 다시 시작 (종료 후 다시 열기)

• Cursor의 개발자 콘솔에서 오류 확인

티켓 상태를 변경할 수 없음

증상: "Invalid status transition"

해결 방법:

• 오류 메시지에 나열된 사용 가능한 전환 확인

• 상태 이름이 정확히 일치해야 함 (대소문자 구분 안 함)

• Jira 워크플로우 권한 확인

• 워크플로우에 대해 전환이 유효한지 확인

아키텍처

이 프로젝트는 SOLID 원칙과 클린 아키텍처를 따릅니다:

src/
├── __init__.py
├── __main__.py           # Entry point
├── server.py             # MCP server setup
├── config/               # Configuration management
├── client/               # Jira API client
├── tools/                # 3 MCP tools
├── models/               # Domain models
├── mappers/              # Data transformation
└── utils/                # Error handling, JSON utils

핵심 원칙:

• SOLID: 단일 책임, 의존성 역전

• DRY: 중복 없음, 재사용 가능한 구성 요소

• 타입 안전성: 전체 코드에 타입 힌트 적용

• 테스트 가능성: 관심사의 깔끔한 분리

자세한 기술 문서는 ARCHITECTURE.md를 참조하세요.

개발

프로젝트 구조

jira-mcp/
├── src/                  # Source code (22 Python files)
├── tests/                # Test suite
├── pyproject.toml        # Project config (includes pytest config)
├── .env.example          # Config template
├── .gitignore
├── README.md             # This file
└── ARCHITECTURE.md       # Technical docs

의존성 추가

uv add package-name

다른 구성으로 실행

uv run --env-file .env.production -m src

코드 품질

• 린팅 오류: 0

• 타입 커버리지: 100%

• 테스트 커버리지: 3개 도구 모두에 대한 통합 테스트

• 아키텍처: SOLID + DRY 준수

요구 사항

• Python 3.12+

• API 액세스가 가능한 Jira 계정

• Jira API 토큰 (Kantega SSO Enterprise 또는 Atlassian Cloud)

라이선스

이 프로젝트는 Cursor 및 Jira와 함께 사용하기 위해 있는 그대로 제공됩니다.

SOLID 및 DRY 원칙을 따르는 모범 사례로 구축됨 🚀