jira-mcp-server-kt

v2.0.1

Published

9 months ago

TypeScript MCP server for Jira integration with Streamable HTTP (MCP 2025-06-18)

0High
0Medium
0Low

emoket

mcp jira typescript ai agents model-context-protocol claude anthropic atlassian

Jira MCP Server

TypeScript로 구현된 Jira용 Model Context Protocol (MCP) 서버입니다. AI 에이전트가 Jira와 직접 상호작용할 수 있도록 표준화된 인터페이스를 제공합니다.

🚀 기능

Tools (도구)

search-jira-issues: JQL을 사용하여 이슈 검색
create-jira-issue: 새로운 이슈 생성
get-jira-issue: 특정 이슈 상세 조회

Resources (리소스)

jira://projects: 접근 가능한 프로젝트 목록

Prompts (프롬프트)

jira-issue-template: 이슈 생성 템플릿

📋 요구사항

Node.js 18+
Jira Cloud 인스턴스
Jira API 토큰

⚙️ 설정

1. 환경변수 설정

.env.example을 .env로 복사하고 값을 입력하세요:

cp .env.example .env

2. 환경변수 값 설정

# Jira 인스턴스 URL (필수)
JIRA_BASE_URL=https://your-domain.atlassian.net

# Jira 계정 이메일 (필수)
[email protected]

# Jira API 토큰 (필수)
JIRA_API_TOKEN=your_api_token_here

# 로그 레벨 (선택사항, 기본값: info)
LOG_LEVEL=info

3. Jira API 토큰 생성

Atlassian Account Settings에 접속
"Create API token" 클릭
토큰 이름 입력 (예: "MCP Server")
생성된 토큰을 .env 파일에 추가

🔧 설치 및 실행

의존성 설치

npm install

빌드

npm run build

개발 모드로 실행

npm run dev

서버가 http://localhost:3003에서 실행됩니다.

프로덕션 모드로 실행

npm run build
npm start

🐳 Docker로 실행

Docker 이미지 빌드 및 실행

# 1. 환경변수 파일 생성
cp .env.example .env
# .env 파일을 실제 Jira 정보로 수정

# 2. Docker 이미지 빌드
npm run docker:build

# 3. Docker 컨테이너 실행
npm run docker:run

Docker Compose로 실행

# 1. 환경변수 파일 생성
cp .env.example .env
# .env 파일을 실제 Jira 정보로 수정

# 2. 프로덕션 모드로 실행
npm run docker:compose:up

# 3. 개발 모드로 실행 (핫 리로드)
npm run docker:compose:dev

# 4. 컨테이너 중지
npm run docker:compose:down

환경변수 파일 (.env.example)

# Jira Configuration (Required)
JIRA_BASE_URL=https://your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token_here

# Logging (Optional)
LOG_LEVEL=info

Docker를 사용한 Claude Desktop 연동

Docker 컨테이너에서 실행되는 MCP 서버를 Claude Desktop과 연동하려면:

컨테이너에서 실행 파일 추출:

# 컨테이너 실행
docker run -d --name jira-mcp-temp jira-mcp-server

# 빌드된 파일 복사
docker cp jira-mcp-temp:/app/dist ./docker-dist

# 임시 컨테이너 제거
docker rm -f jira-mcp-temp

Claude Desktop 설정:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/project/docker-dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

참고: MCP는 stdio 기반 프로토콜이므로 Docker 컨테이너 내부에서 직접 Claude Desktop과 통신할 수 없습니다. Docker는 주로 개발, 테스트, 배포 환경에서 사용됩니다.

🔍 테스트 및 디버깅

MCP Inspector로 테스트

# 프로젝트 빌드
npm run build

# MCP Inspector 실행
npm run inspector

브라우저에서 Inspector UI가 열리면:

환경변수를 수동으로 설정
Tools 탭에서 각 도구 테스트
Resources 탭에서 프로젝트 목록 확인

🖥️ Claude Desktop 연동

🚀 빠른 시작

가장 간단한 npx 방식으로 바로 시작해보세요!

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["jira-mcp-server-kt"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

📖 자세한 설정 방법

상세한 설치 및 설정 방법은 사용자 가이드를 참조하세요.

✅ npx 방식 (권장): 설치 없이 바로 사용
✅ 글로벌 설치: npm install -g로 시스템에 설치
✅ 로컬 빌드: 개발자용 로컬 빌드 방법
✅ 문제 해결: 연결 오류 및 해결 방법
✅ 사용 예제: 실제 Jira 작업 예시들

🧪 사용 예시

JQL 검색 예시

project = PROJ AND status = "In Progress"
assignee = currentUser() AND created >= -1w
priority = High AND status != Done

이슈 생성 예시

{
  "projectKey": "PROJ",
  "summary": "새로운 기능 요청",
  "description": "사용자가 요청한 새로운 기능입니다.",
  "issueType": "Story",
  "priority": "Medium"
}

🔧 개발

프로젝트 구조

src/
├── config/          # 환경설정 및 로깅
├── lib/             # Jira API 클라이언트
├── tools/           # MCP 도구들
├── resources/       # MCP 리소스들
├── types/           # TypeScript 타입 정의
└── index.ts         # 메인 서버

새로운 도구 추가

src/tools/ 에 새 파일 생성
Zod 스키마 정의
도구 함수 구현
src/index.ts에 등록

코드 품질

# 린트 체크
npm run lint

# 포맷 체크
npm run format:check

# 타입 체크
npm run typecheck

# 빌드 테스트
npm run build

🐛 문제 해결

"Extension not found" 오류

설정 파일에서 mcpServers 키 사용 확인
절대 경로 사용 확인
Claude Desktop 완전 재시작

"Module not found" 오류

npm run build 실행 확인
dist/index.js 파일 존재 확인
프로젝트 경로가 정확한지 확인

JSON 파싱 오류

이 문제는 해결되었습니다 (모든 로그가 stderr로 출력됨)
만약 여전히 발생한다면 프로젝트를 다시 빌드하세요

인증 오류

JIRA_BASE_URL이 정확한지 확인 (https:// 포함)
JIRA_EMAIL이 Jira 계정과 일치하는지 확인
JIRA_API_TOKEN이 올바르게 생성되었는지 확인

📝 라이선스

MIT License

🤝 기여

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📞 지원

📚 문서

사용자용

사용자 가이드 (USER_GUIDE.md) - npx를 이용한 빠른 설치 및 사용법, Claude Desktop 설정 방법

개발자용

배포 가이드 (DEPLOYMENT.md) - npm 패키지 배포 및 릴리즈 프로세스
설정 예제 (claude-desktop-config-examples.json) - 다양한 Claude Desktop 설정 예제

MCP Hub 개발자용

⚠️ 업데이트: MCP 2025-06-18 Streamable HTTP 표준으로 업그레이드되었습니다.

🚀 MCP Hub 통합 가이드 (MCP_HUB_INTEGRATION_GUIDE.md) - mcp-hub 아키텍처에 통합하기 위한 완전한 가이드
📝 통합 예제 (examples/mcp-hub-integration-example.js) - Streamable HTTP 클라이언트 구현 예제
🧪 빠른 테스트 (examples/quick-test.sh) - Streamable HTTP 서버 테스트 스크립트
📋 마이그레이션 계획 (MIGRATION_PLAN.md) - stdio → HTTP/SSE 마이그레이션 상세 계획

🎯 로드맵

[ ] 이슈 업데이트 도구
[ ] 댓글 관리 기능
[ ] 첨부파일 지원
[ ] 워크플로우 관리
[ ] 대시보드 통계