sooperset/mcp-atlassianPlease refer to the latest official releases for information GitHub Homepage

Atlassian 도구(Confluence 및 Jira)를 위한 MCP 서버로, AI 어시스턴트가 작업 공간 데이터에 직접 액세스하고 조작할 수 있도록 지원합니다.

MITPython 2.2ksoopersetmcp-atlassian Last Updated: 2025-06-27

MCP-Atlassian 프로젝트 상세 소개

프로젝트 개요

MCP-Atlassian은 Model Context Protocol (MCP) 기반 서버로, Atlassian 제품(Confluence 및 Jira)을 위해 설계되었습니다. 이 프로젝트는 AI 어시스턴트(예: Claude)가 Atlassian 작업 공간 데이터에 직접 액세스하고 조작하여 지능적인 워크플로 관리를 구현할 수 있도록 합니다.

프로젝트 기본 정보

프로젝트 이름: mcp-atlassian
개발자: sooperset
GitHub 주소: https://github.com/sooperset/mcp-atlassian
배포 방식: Docker 컨테이너

핵심 기능 특성

AI 기반의 스마트 작업

프로젝트는 다양한 AI 어시스턴트 기반의 스마트 작업을 지원합니다.

📝 자동 Jira 업데이트 - "회의록에서 Jira 업데이트"
🔍 AI 기반의 Confluence 검색 - "Confluence에서 OKR 가이드를 찾아 요약"
🐛 스마트 Jira 이슈 필터링 - "지난주 PROJ 프로젝트의 긴급 버그 표시"
📄 콘텐츠 생성 및 관리 - "XYZ 기능에 대한 기술 설계 문서 생성"

제품 호환성 지원

제품	배포 유형	지원 상태
Confluence	Cloud	✅ 완전 지원
Confluence	Server/Data Center	✅ 지원 (버전 6.0+)
Jira	Cloud	✅ 완전 지원
Jira	Server/Data Center	✅ 지원 (버전 8.14+)

설치 및 구성

사전 요구 사항

Docker 환경
Atlassian API 토큰 (클라우드 버전) 또는 개인 액세스 토큰 (서버 버전)

인증 토큰 획득

Atlassian Cloud:

https://id.atlassian.com/manage-profile/security/api-tokens 방문
"Create API token" 클릭, 이름 지정 및 토큰 복사

Server/Data Center:

개인 프로필 → 개인 액세스 토큰으로 이동
"Create token" 클릭, 만료 시간 설정 및 토큰 복사

Docker 이미지 획득

# 미리 빌드된 이미지 가져오기
docker pull ghcr.io/sooperset/mcp-atlassian:latest

IDE 통합 구성

Claude Desktop 구성

구성 파일 위치:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

방법 1: 직접 변수 전달

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME", 
        "-e", "CONFLUENCE_API_TOKEN",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com", 
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

방법 2: 환경 파일 사용

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm", 
        "-i",
        "--env-file",
        "/path/to/your/mcp-atlassian.env",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Server/Data Center 구성

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i", 
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "-e", "CONFLUENCE_SSL_VERIFY",
        "-e", "JIRA_URL", 
        "-e", "JIRA_PERSONAL_TOKEN",
        "-e", "JIRA_SSL_VERIFY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_confluence_pat",
        "CONFLUENCE_SSL_VERIFY": "false",
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_jira_pat", 
        "JIRA_SSL_VERIFY": "false"
      }
    }
  }
}

환경 변수 설명

자주 사용되는 환경 변수:

CONFLUENCE_SPACES_FILTER: 스페이스 키로 필터링 (예: "DEV,TEAM,DOC")
JIRA_PROJECTS_FILTER: 프로젝트 키로 필터링 (예: "PROJ,DEV,SUPPORT")
READ_ONLY_MODE: "true"로 설정하여 쓰기 작업 비활성화
MCP_VERBOSE: "true"로 설정하여 상세 로그 활성화
ENABLED_TOOLS: 쉼표로 구분된 도구 이름 목록

사용 가능한 도구 기능

Confluence 도구

도구 이름	기능 설명
`confluence_search`	CQL을 사용하여 Confluence 콘텐츠 검색
`confluence_get_page`	특정 페이지 콘텐츠 가져오기
`confluence_get_page_children`	페이지 하위 페이지 가져오기
`confluence_get_page_ancestors`	페이지 상위 페이지 가져오기
`confluence_get_comments`	페이지 댓글 가져오기
`confluence_create_page`	새 페이지 생성
`confluence_update_page`	기존 페이지 업데이트
`confluence_delete_page`	페이지 삭제
`confluence_get_labels`	레이블 가져오기
`confluence_add_label`	레이블 추가

Jira 도구

도구 이름	기능 설명
`jira_get_issue`	특정 이슈 상세 정보 가져오기
`jira_search`	JQL을 사용하여 이슈 검색
`jira_get_project_issues`	프로젝트 이슈 가져오기
`jira_get_epic_issues`	에픽 이슈 가져오기
`jira_create_issue`	새 이슈 생성
`jira_batch_create_issues`	이슈 일괄 생성
`jira_update_issue`	기존 이슈 업데이트
`jira_delete_issue`	이슈 삭제
`jira_get_transitions`	이슈 상태 전환 가져오기
`jira_transition_issue`	이슈 상태 전환
`jira_add_comment`	댓글 추가
`jira_add_worklog`	작업 로그 추가
`jira_get_worklog`	작업 로그 가져오기
`jira_download_attachments`	첨부 파일 다운로드
`jira_link_to_epic`	에픽에 연결
`jira_get_agile_boards`	칸반 보드 가져오기
`jira_get_board_issues`	칸반 보드 이슈 가져오기
`jira_get_sprints_from_board`	칸반 보드 스프린트 가져오기
`jira_get_sprint_issues`	스프린트 이슈 가져오기
`jira_create_sprint`	스프린트 생성
`jira_update_sprint`	스프린트 업데이트
`jira_get_issue_link_types`	이슈 링크 유형 가져오기
`jira_create_issue_link`	이슈 링크 생성
`jira_remove_issue_link`	이슈 링크 제거

참고: * 표시된 도구는 Jira Cloud에서만 사용 가능

접근 제어

도구 필터링

--enabled-tools 플래그 또는 ENABLED_TOOLS 환경 변수를 사용하여 사용 가능한 도구를 지정합니다.

# 환경 변수를 통해
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

# 또는 명령줄 플래그를 통해
docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

읽기/쓰기 제어

도구는 읽기 및 쓰기 작업으로 나뉩니다. READ_ONLY_MODE를 활성화하면 ENABLED_TOOLS 설정에 관계없이 읽기 작업만 사용할 수 있습니다.

문제 해결

일반적인 문제 해결

인증 실패:

클라우드 버전: API 토큰 확인 (계정 비밀번호 아님)
서버/데이터 센터 버전: 개인 액세스 토큰이 유효하고 만료되지 않았는지 확인
이전 버전의 Confluence 서버: CONFLUENCE_USERNAME 및 CONFLUENCE_API_TOKEN (토큰은 비밀번호)을 사용해야 할 수 있습니다.

SSL 인증서 문제: 서버/데이터 센터 배포에서 SSL 오류가 발생하면 CONFLUENCE_SSL_VERIFY=false 또는 JIRA_SSL_VERIFY=false로 설정합니다.

권한 오류: Atlassian 계정에 관련 공간/프로젝트에 액세스할 수 있는 충분한 권한이 있는지 확인합니다.

디버깅 방법

MCP Inspector를 사용하여 테스트:

npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

로그 보기:

# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows  
type %APPDATA%\Claude\logs\mcp*.log | more

SSE 전송 사용

표준 stdio 전송 외에도 Server-Sent Events (SSE)를 지원합니다.

터미널에서 서버를 수동으로 시작합니다.

docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport sse --port 9000 -vv

실행 중인 서버에 연결하도록 IDE를 구성합니다.

{
  "mcpServers": {
    "mcp-atlassian-sse": {
      "url": "http://localhost:9000/sse"
    }
  }
}

보안 고려 사항

API 토큰을 절대 공유하지 마십시오.
.env 파일을 안전하고 비공개로 유지하십시오.
모범 사례는 SECURITY.md를 참조하십시오.

기술 아키텍처

이 프로젝트는 Docker 컨테이너화 배포를 채택하고 Model Context Protocol을 통해 AI 어시스턴트와 통신합니다. 다양한 전송 방식(stdio 및 SSE)을 지원하여 다양한 배포 환경 및 사용 시나리오에 유연하게 적응할 수 있습니다.

프로젝트 설계는 엔터프라이즈급 애플리케이션의 요구 사항을 고려하여 Atlassian의 클라우드 버전 및 사설 배포 버전을 지원하고 완전한 인증, 권한 제어 및 보안 메커니즘을 제공합니다.

주의: 이것은 Atlassian 공식 제품이 아니며 커뮤니티 개발자 sooperset이 유지 관리하는 오픈 소스 프로젝트입니다.