@choing.dev/jira-mcp

Jira Cloud & Confluence를 AI 에이전트에서 바로 사용할 수 있게 해주는 MCP (Model Context Protocol) 서버입니다.

Claude, Cursor 등 MCP를 지원하는 AI 도구에서 JQL 검색, 이슈 생성/수정/전환, 댓글 작성, Confluence 페이지 생성까지 자연어로 수행할 수 있습니다.

주요 기능

도구	설명
jql_search	JQL로 이슈 검색 (v3 페이지네이션 지원)
get_issue	이슈 상세 조회
create_issue	이슈 생성 (Task, Bug, Story, Epic 등)
update_issue	이슈 필드 수정 (제목, 설명, 담당자, 라벨 등)
get_transitions	가능한 상태 전환 목록 조회
transition_issue	이슈 상태 전환 (예: To Do → In Progress)
add_comment	이슈에 댓글 추가
list_projects	프로젝트 목록 조회
get_myself	현재 사용자 정보 조회
confluence_create_page	Confluence 페이지 생성

빠른 시작

1. 환경변수 설정

export JIRA_INSTANCE_URL="https://your-domain.atlassian.net"
export JIRA_USER_EMAIL="your-email@example.com"
export JIRA_API_KEY="your-api-token"

API 토큰 발급: Atlassian API 토큰 관리에서 발급받을 수 있습니다.

2. 설치 및 실행

npx @choing.dev/jira-mcp

또는 글로벌 설치:

npm install -g @choing.dev/jira-mcp
jira-mcp

AI 도구 설정

Cursor

.cursor/mcp.json 파일에 추가:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@choing.dev/jira-mcp"],
      "env": {
        "JIRA_INSTANCE_URL": "https://your-domain.atlassian.net",
        "JIRA_USER_EMAIL": "your-email@example.com",
        "JIRA_API_KEY": "your-api-token"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@choing.dev/jira-mcp"],
      "env": {
        "JIRA_INSTANCE_URL": "https://your-domain.atlassian.net",
        "JIRA_USER_EMAIL": "your-email@example.com",
        "JIRA_API_KEY": "your-api-token"
      }
    }
  }
}

도구 상세

jql_search

JQL 쿼리로 이슈를 검색합니다. Jira REST API v3의 POST /search/jql을 사용합니다.

"내 프로젝트의 진행 중인 버그를 검색해줘"
→ jql_search { jql: "project = PROJ AND status = 'In Progress' AND issuetype = Bug" }

파라미터	필수	설명
jql	O	JQL 쿼리 문자열
maxResults		최대 결과 수 (기본: 50)
fields		반환할 필드 목록
nextPageToken		다음 페이지 토큰
expand		추가 정보 (changelog, renderedFields 등)

get_issue

이슈 키 또는 ID로 상세 정보를 조회합니다.

"PROJ-123 이슈 내용 보여줘"
→ get_issue { issueIdOrKey: "PROJ-123" }

create_issue

새 이슈를 생성합니다.

"PROJ 프로젝트에 로그인 버그 이슈 만들어줘"
→ create_issue { projectKey: "PROJ", issueType: "Bug", summary: "로그인 실패 버그" }

파라미터	필수	설명
projectKey	O	프로젝트 키
issueType	O	이슈 유형 (Task, Bug, Story, Epic)
summary	O	이슈 제목
description		이슈 설명 (텍스트 → ADF 자동 변환)
assignee		담당자 계정 ID
labels		라벨 목록
priority		우선순위 (Highest, High, Medium, Low, Lowest)
parentKey		상위 이슈 키 (하위 작업 생성 시)
customFields		커스텀 필드 객체

update_issue

이슈 필드를 수정합니다. description은 ADF(Atlassian Document Format) 객체입니다.

"PROJ-123 제목을 '수정된 제목'으로 바꿔줘"
→ update_issue { issueIdOrKey: "PROJ-123", summary: "수정된 제목" }

get_transitions / transition_issue

이슈 상태를 전환합니다. 먼저 get_transitions로 가능한 전환을 확인한 후 transition_issue를 호출합니다.

"PROJ-123을 In Progress로 변경해줘"
→ get_transitions { issueIdOrKey: "PROJ-123" }
→ transition_issue { issueIdOrKey: "PROJ-123", transitionId: "21" }

add_comment

이슈에 댓글을 추가합니다. 텍스트를 입력하면 ADF 형식으로 자동 변환됩니다.

"PROJ-123에 '확인 완료' 댓글 달아줘"
→ add_comment { issueIdOrKey: "PROJ-123", body: "확인 완료" }

list_projects

접근 가능한 Jira 프로젝트 목록을 조회합니다.

"내 프로젝트 목록 보여줘"
→ list_projects {}

get_myself

현재 인증된 사용자 정보를 조회합니다. 담당자 배정 시 accountId 확인에 유용합니다.

confluence_create_page

Confluence에 새 페이지를 생성합니다. Confluence REST API v2를 사용합니다.

"TEAM 스페이스에 회의록 페이지 만들어줘"
→ confluence_create_page { spaceKey: "TEAM", title: "2026-03-10 회의록", bodyHtml: "<h2>안건</h2><p>...</p>" }

개발

# 의존성 설치
npm install

# 개발 모드 (tsx)
npm run dev

# 빌드
npm run build

# 빌드 후 실행
npm start

환경변수

변수	필수	설명
JIRA_INSTANCE_URL	O	Jira 인스턴스 URL (예: https://your-domain.atlassian.net)
JIRA_USER_EMAIL	O	Atlassian 계정 이메일
JIRA_API_KEY	O	Atlassian API 토큰

기술 스택

• TypeScript – 타입 안전한 코드
• MCP SDK (@modelcontextprotocol/sdk) – Model Context Protocol 구현
• Jira REST API v3 – 이슈, 프로젝트, 전환 관리
• Confluence REST API v2 – 페이지 생성
• stdio 전송 – MCP 클라이언트와 표준 입출력 통신

라이선스

MIT © choing.dev