Jira MCP Server (읽기 전용)

Claude Code가 Jira 티켓 컨텍스트(이슈 상세, 댓글 스레드, 티켓 주변의 참조 그래프, JQL 검색 결과)를 간결한 Markdown으로 가져올 수 있게 해주는 로컬 MCP 서버입니다. 이미지 첨부 파일(예: UI 버그 티켓의 스크린샷)은 Claude가 시각적으로 분석할 수 있도록 가져올 수 있습니다.

의도적으로 할 수 없는 것

이 서버는 엄격히 읽기 전용입니다. 무엇이든 생성, 업데이트, 상태 전환, 삭제 또는 댓글을 다는 도구를 노출하지 않습니다. 강제는 계층적으로 이루어집니다:

1. 코드에서: 모든 HTTP 요청은 GET만 허용하는 단일 헬퍼를 통과하며, 허용 목록에 있는 예외가 하나 있습니다: POST /rest/api/3/search/jql — Atlassian이 POST로 보내도록 요구하는 읽기 작업입니다. 다른 모든 메서드는 ReadOnlyViolationError를 발생시키므로, 나중에 쓰기 호출을 추가하는 편집이 있으면 크게 실패합니다.

2. 자격 증명 수준에서: API 토큰을 읽기 범위만으로 생성하십시오(아래 참조). 그러면 버그가 있어도 쓸 수 없습니다.

Related MCP server: JIRA MCP Server

도구

설정

1. Atlassian API 토큰 생성

1. https://id.atlassian.com/manage-profile/security/api-tokens로 이동합니다.

2. 범위가 있는 API 토큰 생성을 선택합니다(Atlassian은 범위 없는 토큰을 폐지하고 있습니다).

3. Jira 앱을 선택하고 다음 범위만 선택합니다:

   • read:jira-work

   • read:jira-user

4. 토큰을 즉시 복사하십시오. 한 번만 표시됩니다.

이전의 범위 없는 토큰도 작동합니다. 서버는 두 가지를 모두 자동으로 처리합니다(아래 참조).

2. .env 구성

cp .env.example .env   # then edit

필수 키(이것이 전체 구성 표면입니다):

.env는 gitignore 처리되어 있습니다. 절대 커밋하지 마십시오. 실제 환경 변수가 파일보다 우선합니다. 파일은 프로젝트 디렉터리(작업 디렉터리가 아님)를 기준으로 위치하므로, 서버가 어디서 실행되든 찾을 수 있습니다.

3. 의존성 설치

uv 사용(이 저장소에는 uv.lock이 있으므로 권장):

uv sync

또는 venv에 일반 pip 사용:

python -m venv .venv
.venv/bin/pip install -r requirements.txt   # Windows: .venv\Scripts\pip

4. --check로 확인

.venv/bin/python -m jira_mcp --check            # connectivity + auth only
.venv/bin/python -m jira_mcp --check PROJ-123   # also fetch a ticket in full

이 명령은 .env가 발견되었는지, 어떤 기본 URL이 선택되었는지(그리고 cloud-ID 폴백이 필요했는지), 인증된 계정, 그리고 키가 주어지면 Claude가 보는 것과 정확히 동일한 티켓을 출력합니다.

범위 있는 토큰 vs. 범위 없는 토큰: 기본 URL 문제

• 범위 없는 토큰은 사이트 URL https://<site>.atlassian.net에서 작동합니다.

• 범위 있는 토큰은 동일한 URL에서 조용히 실패하여 익명처럼 보이는 응답을 반환합니다. 대신 https://api.atlassian.com/ex/jira/{cloudId}를 호출해야 합니다.

어떤 종류를 보유하고 있는지 알 필요는 없습니다. 시작 시 서버는 GET /rest/api/3/myself로 사이트 URL을 프로브합니다. 실제 계정이 반환되지 않으면 {site}/_edge/tenant_info에서 cloud ID를 가져와 api.atlassian.com에 재시도합니다. 승자는 프로세스 수명 동안 캐시되고 stderr에 기록됩니다.

감지가 실패하는 경우: _edge/tenant_info는 Atlassian의 공식 지원 REST API의 일부가 아닙니다(Atlassian 자체 지원 문서가 이를 가리키지만). 변경될 수 있습니다. 이 경우 .env에 ATLASSIAN_CLOUD_ID를 설정하여 감지를 건너뛰십시오. 오류 메시지가 이 경우가 적용되는 시점을 알려줍니다. 거의 필요하지 않습니다.

PyCharm 설정

1. 인터프리터: Settings → Project → Python Interpreter → Add Interpreter → Existing → 프로젝트 디렉터리에서 .venv/bin/python 선택. (uv sync를 실행했다면 venv에 모든 것이 이미 설치되어 있습니다.)

2. 디버깅용 실행 구성: Run → Edit Configurations → + → Python:

   • Run: 모듈 jira_mcp("script path" 대신 "module" 선택)

   • Parameters: --check PROJ-123

   • Working directory: 프로젝트 루트(아무거나 작동하지만 깔끔합니다)

   이제 어디서든 중단점을 설정하고(예: client.py에서) 실제 요청을 디버깅할 수 있습니다. 실행 중인 MCP 서버 내부의 오류는 그렇지 않으면 보이지 않습니다.

Claude Code에 연결

venv의 Python을 절대 경로로 사용하십시오. Claude Code가 서버를 실행할 때 단순한 python은 venv로 해석되지 않습니다.

macOS/Linux:

claude mcp add jira -- /path/to/PythonProject/.venv/bin/python -m jira_mcp

Windows:

claude mcp add jira -- C:\path\to\PythonProject\.venv\Scripts\python.exe -m jira_mcp

참고:

• -- 뒤의 모든 것은 Claude가 실행하는 명령입니다. -- 앞의 모든 것은 Claude 자신의 옵션입니다.

• 기본 범위는 local입니다(사용자 본인만, 이 프로젝트만, ~/.claude.json에 저장). 체크인된 .mcp.json을 통해 공유하려면 --scope project를 추가하고, 모든 프로젝트에서 사용하려면 --scope user를 추가하십시오.

연결 확인

Claude Code 세션 내에서:

• /mcp를 실행하면 jira 서버가 연결된 것으로 표시되고 여섯 개의 도구가 나열되어야 합니다.

• 또는 그냥 물어보십시오: "use whoami to check the jira connection".

문제 해결

Python을 처음 접하는 개발자를 위한 참고 사항

• venv(.venv/)는 Python과 이 프로젝트의 패키지가 포함된 프로젝트 로컬 복사본입니다: node_modules와 동일하지만 인터프리터 자체도 그 안에 있습니다. 그래서 Claude Code에 .venv/bin/python을 절대 경로로 제공해야 합니다. 대체할 전역 설치가 없습니다.

• asyncio.run(...) 이 필요한 이유는 Python의 async 함수는 호출만으로 실행되지 않기 때문입니다. 호출하면 코루틴 객체가 반환되며, 누군가가 이를 구동해야 합니다. Node처럼 주변 이벤트 루프가 없습니다. asyncio.run()은 루프를 만들고 하나의 코루틴을 완료까지 실행한 다음 루프를 정리합니다. MCP 서버는 mcp.run()을 통해 내부적으로 이 작업을 수행합니다. --check 모드는 명시적으로 수행합니다.

• 데코레이터(@mcp.tool)는 아래에 정의된 함수를 받아 등록/래핑하는 함수로, 정의 시점에 적용되는 미들웨어 팩토리와 같습니다. FastMCP의 데코레이터는 함수 이름, 타입 힌트, docstring을 읽어 Claude가 보는 MCP 도구 스키마를 생성합니다. docstring이 곧 도구의 API 문서입니다.

• python -m jira_mcp 는 패키지의 __main__.py를 실행합니다. Python에서 npm bin 항목에 가장 가까운 것입니다. uv sync가 프로젝트를 venv에 설치했기 때문에 어떤 디렉터리에서도 작동합니다.