Atlassian Read-only MCP

AI 어시스턴트에게 Jira 및 Confluence Cloud에 대한 읽기 전용 액세스를 제공하는 소형 MCP 서버입니다. 읽기 전용 액세스는 두 계층에서 강제됩니다:

1. Atlassian 토큰에는 읽기 범위(read scope)만 포함됩니다.

2. 서버는 허용 목록(allowlist) 방식의 GET 요청만 구현합니다.

다음 네 가지 도구를 제공합니다:

• Jira 이슈 읽기

• JQL로 Jira 검색

• Confluence 페이지 읽기

• CQL로 Confluence 검색

일반적인 HTTP 도구는 없으며 POST, PUT, PATCH, DELETE 구현도 존재하지 않습니다. 더 넓은 범위의 자격 증명이 실수로 제공되더라도 MCP 클라이언트에는 Jira 또는 Confluence 콘텐츠를 변경할 수 있는 도구가 없습니다. 응답 크기는 제한되고, 비밀 정보로 보이는 값은 삭제되며, Confluence storage HTML은 Markdown으로 변환되고, 선택적 JMESPath 프로젝션(projection)을 사용하여 반환 데이터를 줄일 수 있습니다.

요구 사항

• Node.js 20 이상

• 구성된 Atlassian Cloud 테넌트에 액세스할 수 있어야 함

• Jira와 Confluence에 대한 별도의 범위 지정 API 토큰

• VS Code의 GitHub Copilot과 같은 MCP 클라이언트

Related MCP server: MCP Atlassian Server

설치

git clone https://github.com/AlexSchaap-TMMC/atlassian-readonly-mcp.git C:\Tools\atlassian-readonly
Set-Location C:\Tools\atlassian-readonly
npm install
npm test

API 토큰 생성

Atlassian API tokens 페이지를 열고 토큰 두 개를 만듭니다.

Jira 토큰

read:jira-work

이 클래식(classic) 범위 하나만으로도 이슈 조회와 JQL 검색이 검증되었습니다. Atlassian은 동일한 기능의 세분화된(granular) 범위만 포함한 Jira 토큰을 401 Unauthorized; scope does not match 오류로 거부했습니다.

Confluence 토큰

read:page:confluence
read:content-details:confluence
search:confluence

이 세분화된 범위들은 CQL 검색 및 전체 페이지 조회에 대해 검증되었습니다.

범위(scope)는 토큰 생성 시 고정됩니다. Jira와 Confluence에는 각각 별도의 토큰이 필요합니다. 각 토큰은 최초 생성 대화상자에서 복사하되, 소스 파일, MCP 구성, 셸 히스토리, 이슈, 채팅 등에 넣지 마세요.

쓰기 또는 관리 범위(admin scope)를 추가하지 마십시오. 제한된 토큰을 사용하면 MCP 구현과 무관하게 Atlassian이 쓰기 작업을 거부합니다.

자격 증명 저장

저장소 디렉터리에서 실행하세요:

npm run configure -- jira
npm run configure -- confluence

숨겨진 프롬프트는 각 토큰을 Windows Credential Manager, macOS Keychain, 또는 Linux Secret Service에 개별적으로 저장합니다. Atlassian 계정 이메일은 자격 증명 저장소가 아니라 MCP 환경에 있어야 합니다.

VS Code에서 GitHub Copilot 구성

명령 팔레트에서 MCP: Open User Configuration을 실행하세요:

{
  "servers": {
    "atlassian-readonly": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\Tools\\atlassian-readonly\\src\\server.mjs"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "your.atlassian.email@example.com",
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

VS Code를 다시 로드하고, Copilot Chat을 연 다음 Configure Tools를 선택하고 네 가지 Atlassian 도구를 활성화하세요.

예시 프롬프트:

Read HEC-123 and summarize its acceptance criteria.
Search Jira for open bugs assigned to me.
Search Confluence for pages about Kafka retry handling.

GitHub Copilot CLI 구성

copilot mcp add atlassian-readonly `
  --env ATLASSIAN_USER_EMAIL="your.atlassian.email@example.com" `
  --env NODE_OPTIONS="--use-system-ca" `
  -- node C:\Tools\atlassian-readonly\src\server.mjs

서버를 추가하거나 변경한 후에는 Copilot CLI를 다시 시작하세요.

문제 해결

인증

다음을 확인하세요:

• 이메일이 토큰을 생성한 Atlassian 계정과 일치하는지.

• 올바른 제품 토큰이 저장되었는지.

• 토큰이 유효하고 해당 계정이 요청한 콘텐츠에 액세스할 수 있는지.

• Jira에 세분화된 범위만이 아니라 read:jira-work가 포함되었는지.

• Confluence에 위에 나열된 세 가지 범위가 모두 포함되었는지.

• 토큰을 교체한 후 MCP 호스트를 다시 시작했는지.

범위가 지정된 토큰은 Atlassian의 제품 게이트웨이를 사용해야 합니다:

https://api.atlassian.com/ex/jira/{cloudId}
https://api.atlassian.com/ex/confluence/{cloudId}

이 서버는 src/atlassian.mjs에 있는 고정된 테넌트 Cloud ID를 사용합니다.

기업 인증서

Zscaler와 같은 TLS 검사 제품은 기업 인증 기관(CA)으로 HTTPS 트래픽을 다시 서명합니다. Windows는 해당 인증 기관을 신뢰할 수 있지만 Node.js는 자체 번들 CA 목록을 사용합니다. 지원되는 Node.js 버전에서는 이 설정을 MCP 환경에 유지하세요:

NODE_OPTIONS=--use-system-ca

필요한 경우 만료되지 않은 기업 CA를 Base-64 PEM으로 내보내고 NODE_EXTRA_CA_CERTS에 절대 경로를 설정하십시오. TLS 검증을 절대 비활성화하지 마십시오.

WSL은 별도의 Linux 신뢰 저장소를 사용합니다. 관련 기업 루트 및 중간 인증서를 Windows에서 내보내고 .crt 확장자로 저장한 후 /usr/local/share/ca-certificates/에 복사한 다음 실행하세요:

sudo update-ca-certificates

curl, Docker, Node.js 또는 기타 HTTPS 클라이언트를 다시 시도하기 전에 WSL을 다시 시작하세요.

WSL 및

데스크톱 키링(keyring)이 없는 환경에서는 제한된 토큰 파일을 사용하세요:

mkdir -p ~/.config
install -m 600 /dev/null ~/.config/atlassian-jira-token
install -m 600 /dev/null ~/.config/atlassian-confluence-token
read -rsp "Jira API token: " token; echo
printf '%s' "$token" > ~/.config/atlassian-jira-token
read -rsp "Confluence API token: " token; echo
printf '%s' "$token" > ~/.config/atlassian-confluence-token
unset token

MCP 환경에 다음 변수를 구성하세요:

ATLASSIAN_USER_EMAIL
ATLASSIAN_JIRA_TOKEN_FILE
ATLASSIAN_CONFLUENCE_TOKEN_FILE

ATLASSIAN_JIRA_API_TOKEN 및 ATLASSIAN_CONFLUENCE_API_TOKEN은 프로세스 범위의 CI 사용에는 지원되지만, 데스크톱 구성에 유지해서는 안 됩니다.

자격 증명 교체 또는 삭제

저장된 토큰 교체:

npm run configure -- jira
npm run configure -- confluence

저장된 토큰 삭제:

npm run configure -- jira delete
npm run configure -- confluence delete

로컬 삭제는 토큰을 해지하지 않습니다. Atlassian의 토큰 관리 페이지에서 별도로 해지하세요.

보안 경계

이 프로젝트는 방어를 위한 심층 방어(defense in depth)를 사용합니다:

• 토큰 구속: 문서화된 토큰에는 Atlassian 읽기 범위만 포함되어 있기 때문에 Atlassian이 쓰기를 승인하지 않습니다.

• 구현 구속: 읽기 전용 도구 네 개만 노출되며, 각 도구의 URL이나 HTTP 메서드는 고정되어 있어 호출자가 다른 호스트, 엔드포인트 또는 메서드를 선택할 수 없습니다.

• 응답 구속: 응답 크기에 제한이 있고 비밀 정보로 보이는 값이 삭제되며 프로젝션을 통해 반환 데이터를 최소화할 수 있습니다.

토큰은 여전히 생성자의 가시 범위를 상속받습니다. 즉, MCP는 해당 계정이 이미 액세스할 수 있는 콘텐츠만 읽습니다. 더 넓은 범위의 토큰을 제공하면 토큰 계층이 약화되지만 이 서버에 쓰기 작업이 추가되지는 않습니다.

라이선스

MIT