| name | jira-setup |
| description | Interactive setup wizard for Jira MCP server registration and connection validation. Triggers: jira setup, setup jira; Jira 설정, MCP 등록. |
| user-invocable | false |
| argument-hint | |
| allowed-tools | ["Read","Bash","mcp__atlassian__jira_get_user_profile","mcp__atlassian__jira_search"] |
jira-setup: Interactive Jira Setup Wizard
Language Rule: 프로젝트 CLAUDE.md의 Conventions 섹션 참고 (한국어 출력).
Overview
Jira MCP 서버(atlassian)를 Claude Code에 등록하는 대화형 설정 위자드.
Step 1: Prerequisites Check
1-1. uv 설치 확인
uv --version
실패 시:
❌ uv가 설치되어 있지 않습니다.
설치 방법:
Windows (PowerShell): irm https://astral.sh/uv/install.ps1 | iex
macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
설치 후 터미널을 재시작하고 /jira setup을 다시 실행하세요.
→ 중단
1-2. Python 3.10+ 확인
python --version 2>/dev/null || python3 --version 2>/dev/null
Windows Store stub 회피: python --version이 "Python 3.x.x"를 반환하지 않고 아무것도 출력하지 않거나 Microsoft Store를 열려고 하면 stub으로 간주. uv python list로 대체 확인.
Python 3.10 미만이거나 없으면:
❌ Python 3.10 이상이 필요합니다.
현재 버전: <버전 또는 "없음">
uv로 Python 설치:
uv python install 3.11
또는 python.org에서 직접 설치하세요.
→ 중단
사전 요건 통과 시: ✅ 사전 요건 확인 완료 (uv <버전>, Python <버전>)
Step 2: Check Existing Registration
.claude/settings.local.json과 ~/.claude/settings.json 검사:
cat .claude/settings.local.json 2>/dev/null
cat ~/.claude/settings.json 2>/dev/null
mcpServers 키 아래 atlassian 항목이 존재하면 이미 등록된 것으로 판단.
이미 등록된 경우, 선택지를 안내:
ℹ️ Jira MCP 서버(atlassian)가 이미 등록되어 있습니다.
어떻게 하시겠습니까?
1. 연결 테스트만 실행
2. 자격증명 재설정 (기존 설정 덮어쓰기)
3. 취소
AskUserQuestion 도구로 사용자에게 선택 요청:
- "연결 테스트" 선택 → Step 5로 바로 이동
- "재설정" 선택 → Step 3부터 진행
- "취소" 선택 → 종료
Step 3: Collect Credentials
AskUserQuestion 도구로 아래 정보를 수집한다.
필수 항목:
-
JIRA_URL — Jira Cloud URL
- 예시:
https://your-domain.atlassian.net
- 확인:
https://로 시작하고 atlassian.net을 포함해야 함
-
JIRA_USERNAME — Atlassian 계정 이메일
- 예시:
your-email@company.com
-
JIRA_API_TOKEN — API 토큰
선택 항목 (별도 질문):
-
JIRA_PROJECTS_FILTER — 접근 허용 프로젝트 키 (쉼표 구분)
- 예시:
PROJ 또는 PROJ,DEV
- 비워두면 모든 프로젝트 접근 가능
-
JIRA_DEFAULT_PROJECT — 기본 프로젝트 키 (JQL 쿼리에 자동 포함)
- 예시:
PROJ
- 비워두면 프로젝트 필터링 없음
Step 4: Register MCP Server
수집한 자격증명으로 MCP 서버를 등록:
claude mcp add atlassian \
-e JIRA_URL="<JIRA_URL>" \
-e JIRA_USERNAME="<JIRA_USERNAME>" \
-e JIRA_API_TOKEN="<JIRA_API_TOKEN>" \
-- uvx mcp-atlassian
JIRA_PROJECTS_FILTER가 입력되었으면 -e JIRA_PROJECTS_FILTER="<값>" 추가.
참고: JIRA_DEFAULT_PROJECT는 MCP 서버가 아닌 플러그인 자체에서 사용하는 변수이므로, .claude/settings.local.json 또는 CLAUDE.md에 별도로 기록 안내.
등록 후: ✅ MCP 서버 등록 완료
Step 5: Validate Connection
mcp__atlassian__jira_get_user_profile 호출로 연결 검증.
성공 시:
✅ 연결 성공!
사용자: <displayName> (<emailAddress>)
계정 ID: <accountId>
Jira MCP 서버가 정상적으로 연결되었습니다.
이제 /jira-task 워크플로를 사용할 수 있습니다.
실패 시 오류 진단:
| 오류 패턴 | 원인 | 해결책 |
|---|
401 Unauthorized | API 토큰 또는 이메일 오류 | JIRA_USERNAME과 JIRA_API_TOKEN 재확인 |
404 Not Found | JIRA_URL 오류 | URL 형식 확인 (https://domain.atlassian.net) |
connection refused | 네트워크 문제 | 인터넷 연결 및 방화벽 확인 |
uvx not found | uv 미설치 또는 PATH 오류 | uv --version 재확인 |
❌ 연결 실패
오류: <오류 메시지>
원인: <진단 결과>
해결책: <구체적인 조치>
자격증명을 수정하려면 /jira setup을 다시 실행하세요.
Step 6: Post-Setup Summary
─────────────────────────────────────────
🎉 Jira 설정 완료
─────────────────────────────────────────
MCP 서버: atlassian (uvx mcp-atlassian)
연결 계정: <이메일>
Jira URL: <JIRA_URL>
다음 단계:
/jira — 연결 상태 및 사용 가능한 명령 확인
/jira-task init — 할당된 작업 목록 가져오기
─────────────────────────────────────────
