# MCP Atlassian Server

Atlassian 제품(Confluence, Jira)과 통합하기 위한 Model Context Protocol (MCP) 서버입니다. AI 어시스턴트가 Atlassian Cloud API와 상호작용하여 문서 관리, 검색, 내보내기 기능을 사용할 수 있게 합니다.

## 📋 목차

- [주요 기능](#주요-기능)
- [빠른 시작](#빠른-시작)
- [사용 가능한 도구](#사용-가능한-도구)
- [사용 예시](#사용-예시)
- [문제 해결](#문제-해결)

## 주요 기능

### 🔵 Confluence 통합

- **읽기 & 검색**: 페이지, 스페이스, 콘텐츠 접근
- **콘텐츠 관리**: 페이지 생성, 수정, 댓글 작성
- **페이지 계층**: 부모/자식 페이지 관계 탐색
- **내보내기**: 이미지가 포함된 HTML 또는 Markdown으로 내보내기
- **첨부파일**: 첨부파일 목록, 다운로드, 업로드
- **레이블**: 페이지 레이블 관리
- **사용자**: 사용자 검색 및 개인 활동 추적
- **개인 대시보드**: 최근 페이지 및 멘션 확인

### 🟢 Jira 통합

- **이슈**: 이슈 읽기, 검색, 개인 작업 조회
- **프로젝트**: 프로젝트 목록 및 탐색
- **보드 & 스프린트**: 보드 목록, 스프린트 보기, 활성 작업 추적
- **댓글**: 이슈에 댓글 추가
- **이슈 생성**: 커스텀 필드를 포함한 새 이슈 생성
- **사용자 관리**: 현재 사용자 정보 조회
- **개인 대시보드**: 열린 이슈 및 스프린트 작업 확인

## 빠른 시작

### 1. Atlassian API 토큰 발급

1. [Atlassian 보안 설정](https://id.atlassian.com/manage-profile/security/api-tokens)으로 이동
2. "API 토큰 만들기" 클릭
3. 토큰 라벨 입력 (예: "MCP Integration")
4. 생성된 토큰을 복사 (한 번만 표시됩니다!)

> ⚠️ **중요**: API 토큰은 비밀번호처럼 안전하게 보관하세요.

### 2. MCP 설정 파일 찾기

**Claude Desktop**

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

**Cursor**

- 모든 OS: `~/.cursor/mcp.json`

### 3. 설정 파일 수정

설정 파일을 열고 다음 내용을 추가하세요:

```json
{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "mcp-atlassian"],
      "env": {
        "ATLASSIAN_BASE_URL": "https://your-company.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@company.com",
        "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}
```

**설정값 설명:**

- `ATLASSIAN_BASE_URL`: 회사의 Atlassian URL (끝에 `/` 제거)
- `ATLASSIAN_EMAIL`: Atlassian 계정 이메일
- `ATLASSIAN_API_TOKEN`: 1단계에서 생성한 API 토큰

### 4. 앱 재시작

- **Claude Desktop**: 앱을 완전히 종료하고 다시 시작
- **Cursor**: `⌘+Q` (또는 `Ctrl+Q`) 후 다시 실행

### 5. 연결 확인

AI 어시스턴트에게 다음과 같이 물어보세요:

```
"Atlassian MCP 서버가 연결되었는지 확인해줘"
```

## 사용 가능한 도구

### Confluence 도구 (23개)

| 도구                                 | 설명                               |
| ------------------------------------ | ---------------------------------- |
| `get_confluence_current_user`        | 인증된 사용자 정보 조회            |
| `get_confluence_user`                | 특정 사용자 정보 조회              |
| `search_pages_by_user_involvement`   | 사용자 활동으로 페이지 검색        |
| `list_pages_created_by_user`         | 사용자가 작성한 페이지 목록        |
| `list_attachments_uploaded_by_user`  | 사용자가 업로드한 첨부파일 목록    |
| `read_confluence_page`               | ID 또는 제목으로 페이지 읽기       |
| `search_confluence_pages`            | CQL로 페이지 검색                  |
| `list_confluence_spaces`             | 접근 가능한 스페이스 목록          |
| `get_confluence_space`               | 특정 스페이스 정보 조회            |
| `create_confluence_page`             | 새 페이지 생성                     |
| `update_confluence_page`             | 기존 페이지 수정                   |
| `list_confluence_page_children`      | 하위 페이지 목록                   |
| `list_confluence_page_ancestors`     | 상위 페이지 계층 조회              |
| `export_confluence_page`             | 이미지 포함 HTML/Markdown 내보내기 |
| `list_attachments_on_page`           | 페이지 첨부파일 목록               |
| `download_confluence_attachment`     | 특정 첨부파일 다운로드             |
| `upload_confluence_attachment`       | 페이지에 파일 업로드               |
| `get_page_with_attachments`          | 모든 콘텐츠와 함께 페이지 다운로드 |
| `add_confluence_comment`             | 페이지에 댓글 추가                 |
| `list_confluence_page_labels`        | 페이지 레이블 조회                 |
| `add_confluence_page_label`          | 페이지에 레이블 추가               |
| `find_confluence_users`              | 사용자 검색                        |
| `get_my_recent_confluence_pages`     | 내 최근 페이지 목록                |
| `get_confluence_pages_mentioning_me` | 나를 멘션한 페이지 찾기            |

### Jira 도구 (16개)

| 도구                                | 설명                                    |
| ----------------------------------- | --------------------------------------- |
| `get_jira_current_user`             | 인증된 사용자 정보 조회                 |
| `get_jira_user`                     | 특정 사용자 정보 조회                   |
| `search_issues_by_user_involvement` | 사용자 관련 이슈 검색                   |
| `list_issues_by_user_role`          | 역할별 사용자 이슈 목록 (날짜 필터링)   |
| `get_user_activity_history`         | 댓글 및 상태 변경 포함 사용자 활동 추적 |
| `get_user_time_tracking`            | 시간 추적 항목 및 합계 조회             |
| `read_jira_issue`                   | 키로 이슈 상세 정보 읽기                |
| `search_jira_issues`                | JQL로 이슈 검색                         |
| `list_jira_projects`                | 접근 가능한 프로젝트 목록               |
| `create_jira_issue`                 | 새 이슈 생성                            |
| `add_jira_comment`                  | 이슈에 댓글 추가                        |
| `list_agile_boards`                 | 스크럼/칸반 보드 목록                   |
| `list_sprints_for_board`            | 보드의 스프린트 목록                    |
| `get_sprint_details`                | 스프린트 상세 정보 조회                 |
| `get_my_current_sprint_issues`      | 활성 스프린트의 내 작업 조회            |
| `get_my_unresolved_issues`          | 모든 미해결 이슈 조회                   |

## 사용 예시

### Confluence 페이지 검색

```
"내가 작성한 Confluence 페이지 중 최근 5개를 보여줘"
```

```
"'API 문서'라는 제목이 포함된 페이지를 검색해줘"
```

### Confluence 페이지 읽기

```
"페이지 ID 882573681의 내용을 마크다운으로 보여줘"
```

### Jira 이슈 조회

```
"나한테 할당된 미해결 이슈를 모두 보여줘"
```

```
"현재 스프린트에서 내 작업 목록을 보여줘"
```

### 프로젝트 및 보드 탐색

```
"접근 가능한 Jira 프로젝트 목록을 보여줘"
```

```
"스크럼 보드 목록을 보여줘"
```

### CQL을 사용한 고급 검색

```
"type = page AND creator = currentUser() 조건으로 Confluence 페이지를 검색해줘"
```

## 문제 해결

### 연결이 안 될 때

1. **API 토큰 재확인**

   - Base URL 형식: `https://your-company.atlassian.net` (끝에 `/` 제거)
   - 이메일과 토큰이 정확한지 확인
   - 토큰에 필요한 권한이 있는지 확인

2. **앱 완전 재시작**

   - Claude Desktop: 앱을 완전히 종료하고 다시 시작
   - Cursor: `⌘+Q` 후 재실행

3. **설정 파일 확인**
   - JSON 형식이 올바른지 확인 (쉼표, 중괄호 등)
   - 환경 변수 이름이 정확한지 확인

### 성능이 느릴 때

검색 범위를 좁히면 속도가 향상됩니다:

```
"최대 10개의 결과만 보여줘"
"DEV 스페이스에서만 검색해줘"
"최근 1주일 이내의 이슈만 보여줘"
```

### 기타 문제

- GitHub 저장소에 이슈를 생성해주세요: [Issues](https://github.com/dunz/mcp-atlassian/issues)
- Atlassian API 문서: [Developer Docs](https://developer.atlassian.com/cloud/)

## 제한사항

- Atlassian Cloud만 지원 (Server/Data Center 미지원)
- 안전을 위해 삭제 작업은 지원하지 않음
- 일부 Confluence 매크로는 Markdown 변환 시 제한적
- Atlassian Cloud API 속도 제한이 적용됨

## 라이선스

MIT License

---

**Made with ❤️ for better Atlassian integration**