atlassian-mcp

자체 호스팅 Jira(Server / Data Center) 및 자체 호스팅 Bitbucket(Server / Data Center)용 Model Context Protocol(MCP) 서버입니다. 티켓, 풀 리퀘스트, 리뷰 스레드, git 컨텍스트에 대한 자연어 워크플로를 위한 도구를 제공합니다.

참고: 이 서버는 자체 호스팅 인스턴스만 지원합니다. Jira Cloud 및 Bitbucket Cloud는 다른 API를 사용하므로 지원되지 않습니다.

도구

워크플로

Git

Jira

Bitbucket

자연어 예시

• "지금 뭐 하고 있지?" → get_dev_context

• "FOO-123용 브랜치 만들기" → start_work

• "이거 배포 / 병합하고 티켓 닫기" → complete_work

• "리뷰 대기 중인 내 PR 보기" → bitbucket_search with mine=true

• "feature/ABC-123에서 이 저장소의 열린 PR 나열" → bitbucket_search with fromBranch

• "PR 42 전체 개요 보기" → bitbucket_get_pr

• "현재 브랜치에서 master로 PR 열기" → bitbucket_mutate with create

• "PR 42 승인 / 병합 / 거부" → bitbucket_mutate with action

• "PR 42의 댓글 123에 답글" → bitbucket_comment with commentId=123

• "PR 42의 이 차단자 해결" → bitbucket_comment with action=update, severity=BLOCKER, state=RESOLVED

• "PR 체크리스트 작업 나열" → bitbucket_pr_tasks with action=list

• "PAY 프로젝트에서 나에게 할당된 버그 찾기" → jira_search with mine=true, issueType=Bug

• "현재 스프린트에 뭐가 있지?" → jira_search with resource=board_overview

• "FOO-123을 In Progress로 이동" → jira_mutate with transitionName="In Progress"

• "FOO-123에 2시간 기록" → jira_mutate with worklog

• "PAY에 버전 9.1.0 생성" → jira_version with action=create, projectKey=PAY, name=9.1.0

• "PAY의 릴리스 나열" → jira_search with resource=versions, project=PAY

• "버전 12345 릴리스" → jira_version with action=release, id=12345

• "FOO-123에 수정 버전 9.1.0 설정" → jira_mutate with update.fixVersion=9.1.0

• "에픽 FOO-100 아래 작업 생성" → jira_mutate with create.issueType=Task, create.parent=FOO-100 (Epic을 자동 감지하고 Epic Link 설정)

• "FOO-123을 에픽 FOO-100 아래로 이동" → jira_mutate with update.epicLink=FOO-100

• "에픽 생성" → jira_mutate with create.issueType=Epic (Epic Name은 요약으로 기본 설정됨)

• "스토리 포인트를 5로 설정" → jira_mutate with update.customFields={"Story Points": 5} — 값은 일반 값(옵션 레이블, 사용자 이름, 날짜, 레이블 배열)입니다. 서버는 필드 스키마에 따라 이를 래핑합니다.

• "이 티켓 / 에픽에 무엇을 설정할 수 있나요?" → jira_search resource=fields with issueKey=FOO-123 (편집 화면) 또는 project=FOO+issueType=Epic (생성 화면): 필수 및 선택 필드, 값 형태, 허용 값

Related MCP server: Bitbucket Server MCP

설정

1. 구성 파일 생성

~/.atlassian-mcp.json 생성:

{
  "$schema": "https://raw.githubusercontent.com/stubbedev/atlassian-mcp/master/atlassian-mcp.schema.json",
  "jira": {
    "url": "https://jira.example.com",
    "token": "your-jira-personal-access-token"
  },
  "bitbucket": {
    "url": "https://bitbucket.example.com",
    "token": "your-bitbucket-personal-access-token"
  }
}

$schema 필드는 선택 사항이지만 편집기 자동 완성 및 검증을 활성화합니다.

• projectKey는 프로젝트 코드를 의미합니다:

  • Jira 예: 티켓 PAY-123의 PAY

  • Bitbucket 예: 저장소 경로 ENG/payments-service의 프로젝트 ENG

• 인체공학적 별칭도 사용할 수 있습니다:

  • Jira: project (projectKey의 별칭)

  • Bitbucket: project 및 repo (projectKey 및 repoSlug의 별칭)

• Bitbucket 도구의 경우 projectKey 및 repoSlug는 일반적으로 로컬 origin 원격에서 자동 감지됩니다.

• bitbucket_create_pull_request는 현재 브랜치에서 fromBranch도 자동 감지하며 해당 브랜치에 이미 열린 PR이 있으면 기존 열린 PR을 반환합니다.

• Jira 프로젝트 범위 호출은 projectKey를 허용하며 제공될 때 가장 잘 작동합니다.

• Jira 이슈 생성/유형 조회에서 projectKey가 생략되면 서버는 현재 브랜치 티켓 키에서 이를 추론하려고 시도하고, 프로젝트가 하나만 보이면 자동 선택으로 대체하며, 그렇지 않으면 선택할 번호가 매겨진 프로젝트 목록을 반환합니다.

또는 환경 변수(또는 이 디렉토리의 .env 파일)를 사용하세요:

JIRA_URL=https://jira.example.com
JIRA_ACCESS_TOKEN=your-jira-personal-access-token
BITBUCKET_URL=https://bitbucket.example.com
BITBUCKET_ACCESS_TOKEN=your-bitbucket-personal-access-token

구성은 다음 순서로 해석됩니다: --config <path> CLI 인수 → ATLASSIAN_MCP_CONFIG 환경 변수 → ~/.atlassian-mcp.json → $XDG_CONFIG_HOME/atlassian-mcp/config.json (기본값 ~/.config/atlassian-mcp/config.json) → cwd의 .atlassian-mcp.json → 환경 변수.

2. AI 도구에 연결

클론이나 빌드가 필요 없습니다. 도구를 npx @stubbedev/atlassian-mcp@latest로 지정하기만 하면 자동으로 설치되고 실행됩니다.

참고: --prefer-online은 일부 클라이언트에서 MCP 시작을 깨뜨릴 수 있습니다. 명령을 단순하게 유지하고 업데이트하려면 아래 업데이트 단계를 사용하세요.

Claude Code

claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest --config ~/.atlassian-mcp.json

Cursor

~/.cursor/mcp.json(전역) 또는 .cursor/mcp.json(프로젝트 전용)에 추가:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json에 추가:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Zed

~/.config/zed/settings.json에 추가:

{
  "context_servers": {
    "atlassian": {
      "command": {
        "path": "npx",
        "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
      }
    }
  }
}

OpenCode

프로젝트 루트의 opencode.json(또는 전역의 경우 ~/.config/opencode/opencode.json)에 추가:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atlassian": {
      "type": "local",
      "command": ["npx", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
    }
  }
}

Codex CLI

~/.codex/config.yaml에 추가:

mcpServers:
  atlassian:
    command: npx
    args:
      - -y
      - @stubbedev/atlassian-mcp@latest
      - --config
      - /home/you/.atlassian-mcp.json

기타 MCP 호환 도구

MCP를 지원하는 대부분의 도구는 동일한 JSON 형식을 허용합니다. 명령으로 npx를 사용하고 인수로 ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/path/to/config.json"]를 사용하세요.

기존 설치 업데이트

MCP 클라이언트가 이미 구성되어 있고 최신 패키지 버전을 사용하려면:

npx clear-npx-cache

그런 다음 MCP 클라이언트를 다시 시작하세요.

npm 없이 설치하기

서버는 단일 Go 정적 바이너리입니다. 위의 npx 경로는 첫 실행 시 플랫폼에 맞는 사전 빌드된 바이너리를 다운로드합니다. 다음 대안들은 Node를 완전히 건너뜁니다:

# Go toolchain — installs to $GOBIN / $GOPATH/bin
go install github.com/stubbedev/atlassian-mcp@latest

# Nix flake
nix run github:stubbedev/atlassian-mcp -- --config ~/.atlassian-mcp.json

그런 다음 MCP 클라이언트의 command를 결과로 생성된 atlassian-mcp 바이너리로 지정하고 npx 대신 사용하세요. 이 경로들에서는 ffmpeg/ffprobe가 PATH에 있어야 합니다 (또는 ATLASSIAN_MCP_FFMPEG_PATH / ATLASSIAN_MCP_FFPROBE_PATH를 설정하세요). npm 래퍼는 이들을 자동으로 번들합니다.

HTTP 서버로 실행하기 (공유 / 프록시 뒤)

기본적으로 서버는 MCP를 stdio로 통신합니다 (클라이언트당 하나의 프로세스가 에디터에 의해 실행됨). 대신 오래 지속되는 Streamable HTTP 서버로 실행하여 여러 클라이언트가 공유할 수 있습니다 — 리버스 프록시 뒤에서 유용합니다:

atlassian-mcp --http                 # binds 127.0.0.1:7337
atlassian-mcp --http 127.0.0.1:9000  # custom address
ATLASSIAN_MCP_HTTP=1 atlassian-mcp   # same, via env

• 단일 엔드포인트 POST /mcp (JSON-RPC) 및 선택적 GET /mcp SSE 스트림으로 서버→클라이언트 요청을 전달합니다 (roots/list, elicitation). 서버는 상태 저장(stateful) 방식입니다: initialize가 세션을 생성하고 Mcp-Session-Id 헤더를 반환하며, 클라이언트는 이후 모든 요청과 SSE 스트림에서 이 헤더를 반드시 포함해야 합니다. 세션 ID가 없거나/알 수 없거나/만료된 요청은 HTTP 404를 받으므로 클라이언트가 재초기화합니다 (표준 MCP 클라이언트 동작). 각 연결된 클라이언트/워크트리는 격리된 세션을 갖습니다.

• 인증: 루프백 바인딩에서는 토큰이 필요 없습니다. 비루프백 주소에 바인딩할 때는 필수로 ATLASSIAN_MCP_HTTP_TOKEN이 필요합니다 (클라이언트는 Authorization: Bearer …로 전송). 그렇지 않으면 서버가 시작을 거부합니다. TLS는 프록시에서 종료하세요.

• **GET /healthz**는 인증 없는 liveness 프로브로 ok를 반환합니다 — 프록시/로드 밸런서용입니다. 유휴 세션은 1시간 후에 만료됩니다.

저장소 컨텍스트는 클라이언트에서 오며, 서버의 작업 디렉토리가 아닙니다. 저장소가 필요한 도구(git_* 도구, get_dev_context, start_work, complete_work, Bitbucket 프로젝트/저장소 자동 감지)는 다음 순서로 저장소를 결정합니다: 명시적 repoPath 인자 → 요청 헤더로 고정된 루트 (아래 참조) → 클라이언트의 MCP 워크스페이스 루트 (서버는 roots/list로 요청하고, notifications/roots/list_changed 시 새로고침) → 프로세스 cwd (stdio 전용). 따라서 하나의 공유 HTTP 서버가 여러 워크트리를 처리할 수 있습니다: 각 클라이언트의 자체 워크스페이스가 호출을 구동합니다. 세션이 여러 루트(여러 워크트리)를 노출할 때, repoPath가 없는 도구는 첫 번째 git 저장소 루트를 사용합니다. 특정 워크트리를 대상으로 하려면 repoPath(절대 경로 또는 루트 중 하나와 일치하는 워크트리 이름/기본 이름)를 전달하세요. Bitbucket의 경우 projectKey+repoSlug를 명시적으로 전달하면 저장소 감지를 완전히 건너뜁니다. 저장소는 서버 호스트에서 접근 가능해야 합니다 (git 도구는 git을 로컬에서 실행합니다).

요청 헤더로 루트 고정하기 (HTTP). 리버스 프록시나 하네스가 작업 트리를 이미 알고 있다면, roots/list 왕복을 건너뛰고 서버에 직접 전달할 수 있습니다 (클라이언트가 roots 기능을 광고하지 않아도 동작). file:// URI 또는 절대 경로를 보내세요 (여러 개는 쉼표로 구분, 첫 번째 git 저장소가 우선):

X-Mcp-Root: file:///srv/myrepo
X-Mcp-Roots: /srv/a, /srv/b

헤더 이름: X-Mcp-Roots, X-Mcp-Root, Mcp-Roots, Mcp-Root. 헤더 값은 우선합니다 — roots/list보다 우선하며 list_changed 이후에도 유지됩니다.

이미 실행 중인 HTTP 서버에 대한 클라이언트 구성 (Claude Code 예시):

claude mcp add --transport http atlassian http://127.0.0.1:7337/mcp

첨부 파일 디코딩 파이프라인

첨부 파일 도구(jira_get_attachment, bitbucket_get_attachment)는 모델이 읽을 수 있는 콘텐츠로 바이너리 첨부 파일을 디코딩한 후 반환합니다:

자동 저장된 파일은 TTL과 총 크기 할당량에 따라 주기적으로 정리됩니다 — 아래 환경 변수 참조.

외부 도구 (선택 사항)

이미지 및 PDF 텍스트 디코딩은 순수 Go로 구현되어 추가 도구가 필요 없습니다. 순수 Go 구현이 없는 두 파이프라인은 외부 바이너리에 셸 아웃소싱합니다:

• ffmpeg + ffprobe — 비디오 및 애니메이션 이미지 프레임 샘플링. npm 래퍼는 ffmpeg-static / ffprobe-static을 번들하여 경로를 자동 주입하므로 npx 설치 경로는 추가 설정이 필요 없습니다. go install / Nix 경로에서는 ffmpeg를 설치하거나 (그러면 ffprobe도 함께 제공됨) 아래 환경 변수를 설정하세요.

• pdftoppm (poppler) 또는 mutool (MuPDF) — 텍스트를 추출할 수 없는 스캔된 PDF를 래스터화하는 데만 필요합니다. 둘 다 PATH에 없으면 해당 PDF는 디스크에 저장됩니다.

환경 변수

릴리스 (유지보수자용)

이 패키지는 npm에 @stubbedev/atlassian-mcp로 게시됩니다.

릴리스에는 시맨틱 버저닝을 사용하세요. 도구 표면에 변경이 있는 경우 <1.0.0 동안 마이너 버전을 올리세요 (예: 0.0.x -> 0.1.0).

v* 태그가 푸시되면 .github/workflows/publish.yml이 Go 바이너리를 14개 OS/아키텍처 대상으로 크로스 컴파일하여 GitHub 릴리스에 첨부하고, npm 래퍼(설치 시 일치하는 바이너리를 다운로드)를 게시합니다.

릴리스 흐름:

# choose one: patch | minor | major (also: npm run release:patch / :minor / :major)
npm version patch          # bumps package.json, commits, tags vX.Y.Z
git push origin HEAD --follow-tags

flake.nix는 package.json에서 버전을 읽으므로 Nix 패키지도 동일한 버전 변경을 자동으로 추적합니다. GitHub Actions가 푸시된 태그에서 빌드 및 게시합니다.

• 워크플로는 npm Trusted Publisher (OIDC)로 구성되어 있으므로 NPM_TOKEN 시크릿이 필요하지 않습니다.

필요한 npm 설정 (1회):

• npm 패키지 설정에서 이 GitHub 저장소/워크플로를 Trusted Publisher로 추가하세요.

Personal Access Token 생성

Jira Server / Data Center

Personal Access Token은 Jira 8.14부터 지원됩니다.

1. Jira 인스턴스에 로그인하세요.

2. 오른쪽 상단의 프로필 아바타를 클릭하고 Profile을 선택하세요.

3. 왼쪽 사이드바에서 Personal Access Tokens을 클릭하세요.

4. Create token을 클릭하세요.

5. 토큰 이름(예: atlassian-mcp)을 지정하고 선택적으로 만료일을 설정하세요.

6. Create를 클릭하고 토큰을 복사하세요 — 토큰은 한 번만 표시됩니다.

구성 파일의 jira 아래 token 값으로 이 토큰을 붙여넣으세요.

Jira 버전이 8.14보다 오래된 경우 HTTP Basic Auth를 대신 사용할 수 있습니다 — 단, 이 서버는 Bearer token (PAT) 인증만 지원합니다.

Bitbucket Server / Data Center

Personal Access Token은 Bitbucket Server 5.5부터 지원됩니다.

1. Bitbucket 인스턴스에 로그인하세요.

2. 오른쪽 상단의 프로필 아바타를 클릭하고 Manage account를 선택하세요.

3. 왼쪽 사이드바의 Security 아래에서 Personal access tokens을 클릭하세요.

4. Create a token을 클릭하세요.

5. 토큰 이름(예: atlassian-mcp)을 지정하세요.

6. 권한을 설정하세요:

   • Projects: Read

   • Repositories: Read + Write (Write는 풀 리퀘스트 생성 및 코멘트 추가에 필요)

7. 선택적으로 만료일을 설정하세요.

8. Create를 클릭하고 토큰을 복사하세요 — 토큰은 한 번만 표시됩니다.

구성 파일의 bitbucket 아래 token 값으로 이 토큰을 붙여넣으세요.

개발

서버는 저장소 루트에 있는 단일 Go 모듈입니다 (src/ 트리 없음).

# Build the binary
go build -o atlassian-mcp .

# Run it
./atlassian-mcp --config /path/to/config.json

# Vet + unit tests
go vet ./...
go test ./...

# Test the tool list
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./atlassian-mcp

# Quick release smoke check (build + tools/list validation)
npm run smoke