Confluence MCP 서버

Claude Code와 Atlassian Confluence를 통합하기 위한 Model Context Protocol (MCP) 서버입니다.

주요 기능

• 🔍 검색: CQL(Confluence Query Language)을 사용하여 Confluence 페이지 검색

• 📄 읽기: ID 또는 제목으로 페이지 읽기

• ✏️ 생성 및 업데이트: 페이지 생성 및 업데이트

• 🏷️ 라벨 관리: 라벨 및 메타데이터 관리

• 📁 스페이스 목록: 스페이스 및 첨부 파일 목록 조회

• 🔐 보안: API 토큰을 사용한 Basic Auth 지원

Related MCP server: mcp-confluence

설치

사전 요구 사항

• Node.js 18+ 및 npm

• Atlassian Confluence Cloud 계정

• API 토큰 (아래 구성 참조)

설정

git clone https://github.com/gkrauchunas-arlo/confluence-mcp.git
cd confluence-mcp
npm install

구성

1. .env.example 파일을 .env로 복사합니다:

   cp .env.example .env

2. .env 파일에 Atlassian 자격 증명을 입력합니다:

   ATLASSIAN_SITE=your-domain.atlassian.net
   ATLASSIAN_EMAIL=your-email@example.com
   ATLASSIAN_API_TOKEN=your-token

API 토큰 발급 방법:

1. https://id.atlassian.com/manage-profile/security/api-tokens 로 이동합니다.

2. "Create API token"을 클릭합니다.

3. 이름을 지정하고(예: "Claude Code MCP") 토큰을 복사하여 .env에 저장합니다.

테스트

# Test Confluence API connectivity
node test-confluence.js

# Test MCP protocol (via stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

Claude Code에 연결

옵션 1: CLI (권장)

claude mcp add --transport stdio confluence \
  --env ATLASSIAN_SITE="your-domain.atlassian.net" \
  --env ATLASSIAN_EMAIL="your-email@example.com" \
  --env ATLASSIAN_API_TOKEN="your-token" \
  -- node /absolute/path/to/confluence-mcp/index.js

/absolute/path/to/를 실제 설치 경로(예: /home/username/confluence-mcp)로 바꿉니다.

옵션 2: 구성 파일

Claude Code MCP 구성 파일에 다음을 추가합니다:

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/absolute/path/to/confluence-mcp/index.js"],
      "env": {
        "ATLASSIAN_SITE": "your-domain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-token"
      }
    }
  }
}

구성 파일 위치:

• Linux: ~/.config/claude-code/mcp_servers.json 또는 ~/.claude/config/mcp_servers.json

• macOS: ~/Library/Application Support/claude-code/mcp_servers.json

• Windows: %APPDATA%\claude-code\mcp_servers.json

구성 후 Claude Code를 재시작하여 MCP 서버를 활성화합니다.

사용 가능한 도구

검색 및 탐색

• confluence_search - 모든 콘텐츠에 대한 CQL 검색

  • 매개변수: query (문자열), limit (숫자, 선택 사항), spaceKey (문자열, 선택 사항)

  • 예시: 특정 스페이스 내에서 제목에 "API"가 포함된 페이지 검색

• confluence_list_spaces - 모든 스페이스 목록 조회

  • 매개변수: limit (숫자, 선택 사항, 기본값: 25)

  • 반환값: 계정에서 액세스 가능한 모든 Confluence 스페이스 목록

콘텐츠 읽기

• confluence_get_page - ID로 페이지 가져오기

  • 매개변수: pageId (문자열)

  • 반환값: 콘텐츠, 버전, 메타데이터를 포함한 전체 페이지 데이터

• confluence_get_page_by_title - 제목과 스페이스로 페이지 찾기

  • 매개변수: title (문자열), spaceKey (문자열)

  • 반환값: 지정된 스페이스에서 정확히 일치하는 제목의 페이지

• confluence_get_space - 스페이스 정보 가져오기

  • 매개변수: spaceKey (문자열)

  • 반환값: 스페이스 메타데이터 및 구성

• confluence_get_attachments - 페이지 첨부 파일 목록 조회

  • 매개변수: pageId (문자열)

  • 반환값: 페이지의 모든 첨부 파일 목록

생성 및 편집

• confluence_create_page - 새 페이지 생성

  • 매개변수: title (문자열), spaceKey (문자열), content (HTML 문자열), parentId (문자열, 선택 사항)

  • 지정된 스페이스에 새 페이지를 생성하며, 선택적으로 다른 페이지의 하위 페이지로 생성 가능

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

  • 매개변수: pageId (문자열), title (문자열), content (HTML 문자열), version (숫자)

  • 새 콘텐츠로 페이지를 업데이트합니다. 버전 번호는 현재 페이지 버전과 일치해야 합니다.

메타데이터

• confluence_add_labels - 페이지에 라벨 추가

  • 매개변수: pageId (문자열), labels (문자열 배열)

  • 분류를 위해 페이지에 하나 이상의 라벨/태그를 추가합니다.

사용 예시

Claude Code에 연결되면 자연어를 사용하여 Confluence와 상호 작용할 수 있습니다:

페이지 검색

Find all pages about "API documentation" in Confluence

페이지 읽기

Read the contents of Confluence page with ID 12345

새 페이지 생성

Create a new page in the DEV space titled "API Guidelines" with this content:
<h1>API Guidelines</h1>
<p>This document describes our API design principles.</p>

페이지 업데이트

Update Confluence page 12345 to add a new section about authentication

라벨 추가

Add labels "documentation" and "api" to Confluence page 12345

CQL 쿼리 예시

confluence_search 도구는 Confluence Query Language (CQL)을 지원합니다:

type=page AND title~"API"
type=page AND space=DEV
type=page ORDER BY lastmodified DESC
type=page AND label=documentation
type=page AND creator=currentUser()

API 참조

이 MCP 서버는 Confluence REST API를 사용합니다:

• 기본 URL: https://{site}.atlassian.net/wiki/rest/api

• 인증: 이메일 + API 토큰을 사용한 Basic Auth

• API 버전: Cloud REST API (안정 버전)

• 전체 API 문서

문제 해결

"Authentication failed" (인증 실패)

• .env 파일의 이메일과 API 토큰을 확인하세요.

• 토큰이 만료되지 않았는지 확인하세요 (API 토큰은 만료되지 않지만 취소될 수 있습니다).

• Atlassian 계정 비밀번호가 아닌 API 토큰을 사용하고 있는지 확인하세요.

"MCP tools not showing up" (MCP 도구가 표시되지 않음)

• Claude Code를 완전히 재시작하세요 (종료 후 다시 열기).

• node index.js를 직접 실행하여 서버 로그에서 오류를 확인하세요.

• claude mcp list로 구성을 확인하세요.

• 구성에 전체 절대 경로가 사용되었는지 확인하세요.

"Permission denied" (권한 거부) 오류

• Atlassian 계정에 요청한 스페이스/페이지에 대한 액세스 권한이 있는지 확인하세요.

• 일부 작업은 특정 권한이 필요합니다 (예: 페이지 생성을 위한 스페이스 관리자 권한).

• Confluence 웹 UI에서 스페이스 권한을 확인하세요.

"Page version conflict" (페이지 버전 충돌)

• 페이지를 업데이트할 때 현재 버전 번호를 제공해야 합니다.

• 먼저 confluence_get_page를 사용하여 현재 버전을 가져오세요.

• 서버는 자동으로 버전을 1 증가시킵니다.

콘텐츠 형식

Confluence 페이지는 Storage Format(Confluence 매크로가 포함된 HTML)을 사용합니다. 간단한 페이지의 경우 표준 HTML이 작동합니다:

<h1>Heading</h1>
<p>Paragraph with <strong>bold</strong> and <em>italic</em> text.</p>
<ul>
  <li>Bullet point 1</li>
  <li>Bullet point 2</li>
</ul>
<pre><code>Code block</code></pre>

고급 기능은 Confluence Storage Format 문서를 참조하세요.

아키텍처

다음 기술을 기반으로 구축되었습니다:

• @modelcontextprotocol/sdk - MCP 프로토콜 구현

• axios - Confluence REST API용 HTTP 클라이언트

• dotenv - 구성 관리

이 서버는 stdio 기반 MCP 서버로 실행되며, 표준 입출력을 통해 JSON-RPC 2.0으로 Claude Code와 통신합니다.

개발

프로젝트 구조

confluence-mcp/
├── index.js              # Main MCP server implementation
├── package.json          # Dependencies and scripts
├── test-confluence.js    # Confluence API connectivity tests
├── test-mcp.js           # MCP protocol tests (WIP)
├── .env.example          # Example configuration
├── .env                  # Your configuration (gitignored)
└── README.md             # This file

테스트 실행

# Test Confluence API directly
node test-confluence.js

# Test MCP server via stdio
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

기여

기여를 환영합니다! 다음 절차를 따라주세요:

1. 저장소를 포크(Fork)합니다.

2. 기능 브랜치를 생성합니다 (git checkout -b feature/amazing-feature).

3. 테스트와 함께 변경 사항을 적용합니다.

4. 변경 사항을 커밋합니다 (git commit -m 'feat: add amazing feature').

5. 브랜치에 푸시합니다 (git push origin feature/amazing-feature).

6. Pull Request를 엽니다.

알려진 제한 사항

1. 첨부 파일 업로드 - 아직 구현되지 않음 (multipart/form-data 인코딩 필요)

2. 서식 지정 - 기본 HTML만 지원되며, Confluence 매크로는 복잡할 수 있음

3. 페이지네이션 - 대규모 결과 집합은 limit 매개변수에 의해 제한됨

4. 권한 - API는 인증된 사용자가 액세스할 수 있는 콘텐츠만 반환함

라이선스

ISC

감사의 말

• rovo-mcp에서 영감을 받은 아키텍처

• Claude Code를 위해 제작됨

• Model Context Protocol 사용

지원

• 이슈: https://github.com/gkrauchunas-arlo/confluence-mcp/issues

• Atlassian API 문서: https://developer.atlassian.com/cloud/confluence/rest/

• MCP 사양: https://modelcontextprotocol.io/specification

제작자: gkrauchunas-arlo 상태: 안정 버전 v1.0.0 - 모든 핵심 기능 구현 및 테스트 완료