MCP 아틀라시안

Atlassian 제품(Confluence 및 Jira)용 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 통합은 Confluence 및 Jira 클라우드와 서버/데이터 센터 배포를 모두 지원합니다.

사용 예

AI 비서에게 다음을 요청하세요.

• 📝 자동 Jira 업데이트 - "회의 메모에서 Jira 업데이트"

• 🔍 AI 기반 Confluence 검색 - "Confluence에서 OKR 가이드를 찾아 요약해 보세요"

• 🐛 스마트 Jira 이슈 필터링 - "지난주 PROJ 프로젝트의 긴급 버그를 보여주세요"

• 📄 콘텐츠 제작 및 관리 - "XYZ 기능에 대한 기술 설계 문서 작성"

기능 데모

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

호환성

Related MCP server: MCP Atlassian

빠른 시작 가이드

🔐 1. 인증 설정

MCP Atlassian은 세 가지 인증 방법을 지원합니다.

A. API 토큰 인증(클라우드)

1. https://id.atlassian.com/manage-profile/security/api-tokens 로 이동하세요

2. API 토큰 만들기를 클릭하고 이름을 지정하세요.

3. 토큰을 즉시 복사하세요

B. 개인 액세스 토큰(서버/데이터 센터)

1. 프로필(아바타) → 프로필 → 개인 액세스 토큰 으로 이동하세요.

2. 토큰 만들기를 클릭하고 이름을 지정하고 만료일을 설정합니다.

3. 토큰을 즉시 복사하세요

C. OAuth 2.0 인증(클라우드)

1. Atlassian 개발자 콘솔 로 이동

2. "OAuth 2.0(3LO) 통합" 앱을 만듭니다.

3. Jira/Confluence에 대한 권한 (범위) 구성

4. 콜백 URL 설정(예: http://localhost:8080/callback )

5. 설치 마법사 실행:

   지엑스피1

6. Client ID , Secret , URI 및 Scope 대한 프롬프트를 따르세요.

7. 브라우저 권한 완료

8. 획득한 자격 증명을 .env 또는 IDE 구성에 추가합니다.

   • ATLASSIAN_OAUTH_CLOUD_ID (마법사에서)

   • ATLASSIAN_OAUTH_CLIENT_ID

   • ATLASSIAN_OAUTH_CLIENT_SECRET

   • ATLASSIAN_OAUTH_REDIRECT_URI

   • ATLASSIAN_OAUTH_SCOPE

[!IMPORTANT] 지속적 인증에 대한 범위에 offline_access 포함합니다(예: read:jira-work write:jira-work offline_access )

📦 2. 설치

MCP Atlassian은 Docker 이미지로 배포됩니다. 특히 IDE 통합을 위해 서버를 실행하는 데 권장되는 방법입니다. Docker가 설치되어 있는지 확인하세요.

# Pull Pre-built Image
docker pull ghcr.io/sooperset/mcp-atlassian:latest

🛠️ IDE 통합

MCP Atlassian은 IDE 통합을 통해 AI 어시스턴트와 함께 사용하도록 설계되었습니다.

[!TIP] Claude Desktop의 경우 : 구성 파일을 직접 찾아 편집하세요.

• 윈도우 : %APPDATA%\Claude\claude_desktop_config.json

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

• 리눅스 : ~/.config/Claude/claude_desktop_config.json

커서의 경우 : 설정 → MCP → + 새 글로벌 MCP 서버 추가를 엽니다.

⚙️ 구성 방법

Docker 컨테이너를 구성하는 데는 두 가지 주요 접근 방식이 있습니다.

1. 변수 직접 전달 (아래 예시 참조)

2. --env-file 플래그를 사용하여 환경 파일 사용 (접을 수 있는 섹션에 표시됨)

[!NOTE] 일반적인 환경 변수는 다음과 같습니다.

• CONFLUENCE_SPACES_FILTER : 스페이스 키로 필터링(예: "DEV, TEAM, DOC")

• JIRA_PROJECTS_FILTER : 프로젝트 키(예: "PROJ, DEV, SUPPORT")로 필터링합니다.

• READ_ONLY_MODE : 쓰기 작업을 비활성화하려면 "true"로 설정합니다.

• MCP_VERBOSE : 더 자세한 로깅을 위해 "true"로 설정

• ENABLED_TOOLS : 활성화할 도구 이름의 쉼표로 구분된 목록(예: "confluence_search,jira_get_issue")

사용 가능한 모든 옵션은 .env.example 파일을 참조하세요.

📝 구성 예시

방법 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"
      }
    }
  }
}

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

서버/데이터 센터 배포의 경우 직접 변수 전달을 사용하세요.

{
  "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"
      }
    }
  }
}

[!NOTE] 자체 서명 인증서가 있는 경우에만 CONFLUENCE_SSL_VERIFY 및 JIRA_SSL_VERIFY "false"로 설정하세요.

이 예제는 Atlassian Cloud에서 OAuth 2.0을 사용할 때 IDE(예: Cursor 또는 Claude Desktop)에서 mcp-atlassian 구성하는 방법을 보여줍니다. 먼저 OAuth 설정 마법사를 완료했는지 확인하세요.

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "<path_to_your_home>/.mcp-atlassian:/home/app/.mcp-atlassian",
        "-e", "JIRA_URL",
        "-e", "CONFLUENCE_URL",
        "-e", "ATLASSIAN_OAUTH_CLIENT_ID",
        "-e", "ATLASSIAN_OAUTH_CLIENT_SECRET",
        "-e", "ATLASSIAN_OAUTH_REDIRECT_URI",
        "-e", "ATLASSIAN_OAUTH_SCOPE",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "ghcr.io/sooperset/mcp-atlassian:latest",
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "ATLASSIAN_OAUTH_CLIENT_ID": "YOUR_OAUTH_APP_CLIENT_ID",
        "ATLASSIAN_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_APP_CLIENT_SECRET",
        "ATLASSIAN_OAUTH_REDIRECT_URI": "http://localhost:8080/callback",
        "ATLASSIAN_OAUTH_SCOPE": "read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_CLOUD_ID_FROM_SETUP_WIZARD"
      }
    }
  }
}

[!메모]

• ATLASSIAN_OAUTH_CLOUD_ID``--oauth-setup 마법사 출력에서 가져옵니다.

• 다른 ATLASSIAN_OAUTH_* 변수는 Atlassian Developer Console에서 OAuth 앱에 대해 구성한 변수입니다(설정 마법사에 대한 입력으로 사용됨).

• 클라우드 인스턴스의 JIRA_URL 과 CONFLUENCE_URL 여전히 필요합니다.

MCP Atlassian은 표준 HTTP/HTTPS/SOCKS 프록시를 통한 API 요청 라우팅을 지원합니다. 환경 변수를 사용하여 구성하세요.

• 표준 HTTP_PROXY , HTTPS_PROXY , NO_PROXY , SOCKS_PROXY 지원합니다.

• 서비스별 재정의가 가능합니다(예: JIRA_HTTPS_PROXY , CONFLUENCE_NO_PROXY ).

• 서비스별 변수는 해당 서비스의 전역 변수보다 우선합니다.

MCP 구성의 args ( -e 사용) 및 env 섹션에 관련 프록시 변수를 추가합니다.

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "... existing Confluence/Jira vars",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "... existing Confluence/Jira vars": "...",
        "HTTP_PROXY": "http://proxy.internal:8080",
        "HTTPS_PROXY": "http://proxy.internal:8080",
        "NO_PROXY": "localhost,.your-company.com"
      }
    }
  }
}

프록시 URL의 사용자 인증 정보는 로그에 마스크됩니다. NO_PROXY 설정하면 일치하는 호스트에 대한 요청에 적용됩니다.

Confluence Cloud에만 해당:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME",
        "-e", "CONFLUENCE_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_api_token"
      }
    }
  }
}

Confluence Server/DC의 경우 다음을 사용하세요.

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

Jira Cloud에만 해당:

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

Jira Server/DC의 경우 다음을 사용하세요.

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

👥 HTTP 전송 구성

stdio 사용하는 대신 다음 중 하나를 사용하여 서버를 지속적인 HTTP 서비스로 실행할 수 있습니다.

• /sse 엔드포인트에서 sse (서버에서 보낸 이벤트) 전송

• /mcp 엔드포인트에서 streamable-http 전송

두 전송 유형 모두 단일 사용자 및 다중 사용자 인증을 지원합니다.

인증 옵션:

• 단일 사용자 : 환경 변수를 통해 구성된 서버 수준 인증 사용

• 다중 사용자 : 각 사용자가 자신의 인증을 제공합니다.

  • 클라우드: OAuth 2.0 Bearer 토큰

  • 서버/데이터 센터: 개인 액세스 토큰(PAT)

1. 선택한 전송 방식으로 서버를 시작합니다.

   # For SSE transport
   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport sse --port 9000 -vv
   
   # OR for streamable-http transport
   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000 -vv

2. IDE 구성(단일 사용자 예):

   SSE 운송 예:

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

   스트리밍 가능한 HTTP 전송 예:

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

스트리밍 가능한 HTTP 전송을 사용하여 다중 사용자 인증을 설정하는 전체 예는 다음과 같습니다.

1. 먼저 OAuth 설정 마법사를 실행하여 서버의 OAuth 자격 증명을 구성합니다.

   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

2. 스트리밍 가능한 HTTP 전송으로 서버를 시작합니다.

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

3. IDE의 MCP 설정을 구성하세요.

Atlassian 배포에 적합한 권한 부여 방법을 선택하세요.

• 클라우드(OAuth 2.0): 조직이 Atlassian Cloud를 사용하고 각 사용자에 대해 OAuth 액세스 토큰이 있는 경우 이 옵션을 사용합니다.

• 서버/데이터 센터(PAT): Atlassian 서버 또는 데이터 센터를 사용하고 각 사용자에게 개인 액세스 토큰(PAT)이 있는 경우 이 옵션을 사용하세요.

클라우드(OAuth 2.0) 예:

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

서버/데이터 센터(PAT) 예:

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

4. .env 에 필요한 환경 변수:

   JIRA_URL=https://your-company.atlassian.net
   CONFLUENCE_URL=https://your-company.atlassian.net/wiki
   ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_app_client_id
   ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_app_client_secret
   ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback
   ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access
   ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizard

[!메모]

• 서버에는 자체 대체 인증이 구성되어 있어야 합니다(예: API 토큰 환경 변수, PAT 또는 --oauth-setup을 사용한 자체 OAuth 설정). 이는 요청에 사용자별 인증이 포함되지 않은 경우에 사용됩니다.

• OAuth : 각 사용자는 Atlassian OAuth 앱에서 자체 OAuth 액세스 토큰이 필요합니다.

• PAT : 각 사용자는 자신만의 개인 액세스 토큰을 제공합니다.

• 서버는 API 호출에 사용자 토큰이 제공되면 이를 사용하고, 제공되지 않으면 서버 인증으로 대체합니다.

• 사용자 토큰은 필요한 작업에 적합한 범위를 가져야 합니다.

도구

주요 도구

지라 도구

• jira_get_issue : 특정 이슈에 대한 세부 정보를 가져옵니다.

• jira_search : JQL을 사용하여 문제 검색

• jira_create_issue : 새로운 이슈를 생성합니다

• jira_update_issue : 기존 이슈를 업데이트합니다.

• jira_transition_issue : 이슈를 새로운 상태로 전환합니다.

• jira_add_comment : 이슈에 댓글을 추가합니다.

Confluence 도구

• confluence_search : CQL을 사용하여 Confluence 콘텐츠 검색

• confluence_get_page : 특정 페이지의 콘텐츠를 가져옵니다

• confluence_create_page : 새 페이지를 만듭니다

• confluence_update_page : 기존 페이지 업데이트

*이 도구는 Jira Cloud에서만 사용 가능합니다.

도구 필터링 및 액세스 제어

서버는 도구 액세스를 제어하는 두 가지 방법을 제공합니다.

1. 도구 필터링 : --enabled-tools 플래그나 ENABLED_TOOLS 환경 변수를 사용하여 어떤 도구를 사용할 수 있는지 지정합니다.

   # Via environment variable
   ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"
   
   # Or via command line flag
   docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

2. 읽기/쓰기 제어 : 도구는 읽기 또는 쓰기 작업으로 분류됩니다. READ_ONLY_MODE 활성화되면 ENABLED_TOOLS 설정과 관계없이 읽기 작업만 사용할 수 있습니다.

문제 해결 및 디버깅

일반적인 문제

• 인증 실패 :

  • 클라우드의 경우: API 토큰을 확인하세요(계정 비밀번호가 아님)

  • 서버/데이터 센터의 경우: 개인 액세스 토큰이 유효하고 만료되지 않았는지 확인하세요.

  • 이전 Confluence 서버의 경우: 일부 이전 버전에서는 CONFLUENCE_USERNAME 및 CONFLUENCE_API_TOKEN (여기서 토큰은 비밀번호)을 사용한 기본 인증이 필요합니다.

• SSL 인증서 문제 : 서버/데이터 센터를 사용하고 SSL 오류가 발생하는 경우 CONFLUENCE_SSL_VERIFY=false 또는 JIRA_SSL_VERIFY=false 설정하세요.

• 권한 오류 : Atlassian 계정에 공간/프로젝트에 액세스할 수 있는 충분한 권한이 있는지 확인하세요.

디버깅 도구

# Using MCP Inspector for testing
npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

# For local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...

# View logs
# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Windows
type %APPDATA%\Claude\logs\mcp*.log | more

보안

• API 토큰을 공유하지 마세요

• .env 파일을 안전하고 비공개로 유지하세요

• 모범 사례는 SECURITY.md를 참조하세요.

기여하다

MCP Atlassian에 기여해 주세요! 기여하고 싶으신 분은 다음과 같습니다.

1. 자세한 개발 설정 지침은 CONTRIBUTING.md 가이드를 확인하세요.

2. 변경 사항을 적용하고 풀 리퀘스트를 제출합니다.

코드 품질을 위해 사전 커밋 후크를 사용하고 릴리스를 위해 의미적 버전을 따릅니다.

특허

MIT 라이선스에 따라 배포됩니다. 라이선스 파일을 참조하세요. 이 제품은 Atlassian의 공식 제품이 아닙니다.