Skip to main content
Glama

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"
      ]
    }
  }
}

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

  1. 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"

Related MCP server: JIRA MCP Server

기능

사용 가능한 도구

도구

설명

예시

get_ticket

전체 티켓 세부 정보 가져오기

"Get PROJ-123"

get_linked_tickets

관련 티켓 및 하위 작업 가져오기

"Show linked tickets for PROJ-123"

update_ticket_status

티켓 상태 업데이트

"Move PROJ-123 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 원칙을 따르는 모범 사례로 구축됨 🚀

Available Tools

3 tools
get_linked_ticketsA

Fetch all linked tickets and subtasks for a given Jira ticket. Returns issue links (blocks, is blocked by, relates to, etc.) and subtasks with their summaries and statuses.

Inputs: ticket_id (required).

get_ticketA

Fetch full details of a Jira ticket by its ID or key. Returns comprehensive ticket information including summary, description, status, issue type, priority, assignee, reporter, comments, and custom fields.

Inputs: ticket_id (required).

update_ticket_statusA

Update the status of a Jira ticket by transitioning it to a new status. Validates that the transition is valid for the ticket's current workflow. Common statuses include: 'To Do', 'In Progress', 'In Review', 'Done'.

Inputs: ticket_id (required), status (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct operation: retrieving a ticket, fetching linked tickets, and updating status. No overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent 'verb_noun' pattern in snake_case (get_ticket, get_linked_tickets, update_ticket_status), making them predictable.

    Tool Count4/5

    Three tools is on the lower end of the ideal range but still reasonable for a focused Jira server. Each tool serves a clear purpose without feeling sparse.

    Completeness2/5

    Missing essential CRUD operations such as create_ticket, search_tickets, or add_comment. Agents cannot create new tickets or perform most lifecycle actions.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that integrates JIRA directly into Cursor IDE, allowing users to view assigned issues, get detailed information on specific tickets, and convert JIRA issues into local tasks without leaving their editor.
      14
      43 npm
      6
      TypeScript
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Simple Model Context Protocol server that enables AI assistants to interact with Jira, allowing operations like fetching tickets, adding comments, and updating ticket status.
      1
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Model Context Protocol server that allows AI assistants to interact with Jira, supporting operations like creating tickets and fetching project information directly from the cursor.
      1
      -