# Mattermost MCP Server

Mattermost와 연동되는 Model Context Protocol (MCP) 서버입니다. 이 서버를 통해 Claude가 Mattermost의 메시지 검색, 사용자 조회, 채널 관리, 팀 정보 조회 등을 수행할 수 있습니다.

## 주요 기능

- **사용자 관리**: 현재 사용자 정보 조회, 사용자 검색, 사용자 상세 정보 조회
- **메시지 검색**: 키워드, 사용자명, 날짜를 사용하여 전체 메시지 검색
- **사용자별 메시지 검색**: 특정 사용자의 메시지만 검색
- **팀 관리**: 소속된 팀 목록 조회
- **채널 관리**: 채널 목록 조회 및 채널 메시지 가져오기
- **스레드 조회**: 특정 게시물의 전체 대화 스레드 조회
- **자동 사용자 정보 포함**: 모든 메시지 결과에 작성자의 이름과 username 자동 포함
- **KST 시간 표시**: 모든 타임스탬프가 한국 시간(KST, UTC+9)으로 표시

## 사전 요구사항

- Node.js (v16 이상)
- npm 또는 yarn
- API 접근 권한이 있는 Mattermost 계정
- Mattermost 서버 URL 및 액세스 토큰
- Claude Desktop 앱

## 설치 방법

```bash
# 저장소 클론
git clone https://github.com/jhanglim/mattermost-mcp-server.git
cd mattermost-mcp-server

# 의존성 설치
npm install

# TypeScript 컴파일
npm run build
```

## 설정

### 1. Mattermost 액세스 토큰 발급

1. Mattermost에 로그인
2. **계정 설정** → **보안** → **개인 액세스 토큰**으로 이동
3. **토큰 생성** 클릭
4. 토큰 설명 입력 후 생성
5. 생성된 토큰을 복사 (한 번만 표시됩니다!)

### 2. Claude Desktop 설정

Claude Desktop 설정 파일을 편집하세요:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

다음 내용을 추가:

```json
{
  "mcpServers": {
    "mattermost": {
      "command": "node",
      "args": ["/절대경로/mattermost-mcp-server/build/index.js"],
      "env": {
        "MATTERMOST_URL": "https://your-mattermost-server.com",
        "MATTERMOST_TOKEN": "your-personal-access-token"
      }
    }
  }
}
```

**중요**: 
- `/절대경로/mattermost-mcp-server/`를 실제 프로젝트 경로로 변경하세요
- `build/index.js` 경로를 정확히 지정하세요
- `MATTERMOST_URL`과 `MATTERMOST_TOKEN`을 실제 값으로 변경하세요

### 3. Claude Desktop 재시작

설정을 저장한 후 Claude Desktop을 완전히 종료하고 다시 시작하세요.

## 사용 예시

Claude Desktop에서 다음과 같이 요청할 수 있습니다:

### 기본 검색
- "Mattermost에서 '프로젝트 업데이트' 관련 메시지를 검색해줘"
- "개발 채널의 최근 메시지를 보여줘"
- "내가 속한 모든 팀을 보여줘"

### 사용자 관련
- "내 Mattermost 정보를 알려줘"
- "'홍길동' 사용자를 찾아줘"
- "'nayoung' 사용자의 메시지를 검색해줘"
- "'이나영'이 작성한 '배포' 관련 메시지를 찾아줘"

### 고급 검색
- "from:jhanglim 형식으로 특정 사용자의 메시지 검색"
- "@username 형식으로 멘션된 메시지 검색"
- "마케팅 팀의 채널 목록을 알려줘"

## 문제 해결

### MCP 서버가 Claude Desktop에 표시되지 않음

1. `claude_desktop_config.json` 파일 경로가 올바른지 확인
2. JSON 문법이 올바른지 확인 (쉼표, 중괄호 등)
3. 프로젝트 경로가 절대 경로로 정확히 지정되었는지 확인
4. `build/index.js` 파일이 존재하는지 확인 (`npm run build` 실행)
5. Claude Desktop을 완전히 재시작

### 연결 오류

- Mattermost URL이 올바른지 확인 (https:// 포함)
- 액세스 토큰이 유효한지 확인
- Mattermost 서버에 접근 가능한지 확인
- 방화벽이나 프록시 설정 확인

### 권한 오류

- 토큰에 적절한 권한이 있는지 확인
- 팀/채널 멤버십을 확인
- 토큰이 만료되지 않았는지 확인

### 검색 결과가 없음

- 검색어를 확인하세요
- `from:username` 형식이 올바른지 확인
- 사용자가 실제로 메시지를 작성했는지 확인

### 빌드 오류

```bash
# node_modules 삭제 후 재설치
rm -rf node_modules package-lock.json
npm install
npm run build
```

## 보안 주의사항

- ⚠️ 액세스 토큰을 절대 Git에 커밋하지 마세요
- ⚠️ `claude_desktop_config.json`을 공유하지 마세요 (토큰 포함)
- 가능하면 읽기 전용 권한의 토큰을 사용하세요
- 토큰을 정기적으로 갱신하세요
- 더 이상 사용하지 않는 토큰은 삭제하세요

## 라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요

## 관련 링크

- [Model Context Protocol 문서](https://modelcontextprotocol.io)
- [Mattermost API 문서](https://api.mattermost.com)
- [Claude Desktop](https://claude.ai/desktop)

## 지원

문제가 발생하거나 질문이 있으시면 [GitHub Issues](https://github.com/jhanglim/mattermost-mcp-server/issues)에 등록해주세요.