Slack MCP Server

# Slack MCP Server ## 프로젝트 개요 및 기능 설명 이 프로젝트는 FastMCP v2를 사용하여 Slack API와 연동되는 MCP(Model Context Protocol) 서버를 구축하는 것을 목표로 합니다. Slack 워크스페이스와의 다양한 상호작용을 제공하며, UTF-8 인코딩을 통한 한글 메시지 지원을 포함합니다. ### **주요 기능** - Slack 채널에 메시지 전송 - 채널 목록 조회 및 관리 - 채널 메시지 히스토리 조회 - 사용자 간 다이렉트 메시지 전송 - 워크스페이스 사용자 목록 조회 ## 설치 및 실행 방법 ### **1. 의존성 설치** ```bash cd 0527/slack-mcp pip install -r requirements.txt ``` ### **2. 가상환경 설정 (권장)** ```bash python -m venv .venv # Windows .venv\Scripts\activate # macOS/Linux source .venv/bin/activate ``` ### **3. MCP 서버 실행** ```bash python slack_mcp_server.py ``` ### **4. 테스트 스크립트 실행** ```bash python main.py ``` ## 환경 변수 설정 방법 ### **1. Slack 앱 생성 및 설정** 1. [Slack API 사이트](https://api.slack.com/apps)에서 새 앱 생성 2. **OAuth & Permissions** 섹션에서 다음 Bot Token Scopes 추가: - `channels:read` (공개 채널 목록 조회) - `groups:read` (비공개 채널 목록 조회) - `channels:history` (채널 메시지 히스토리 조회) - `groups:history` (비공개 채널 메시지 히스토리 조회) - `chat:write` (메시지 전송) - `users:read` (사용자 정보 조회) - `im:write` (다이렉트 메시지 전송) - `mpim:write` (그룹 DM 전송) 3. **Install App to Workspace** 클릭하여 워크스페이스에 설치 4. **Bot User OAuth Token** (xoxb-로 시작하는 토큰) 복사 ### **2. .env 파일 생성** 프로젝트 루트에 `.env` 파일을 생성하고 다음과 같이 설정: ```bash # .env 파일 SLACK_BOT_TOKEN=xoxb-your-slack-bot-token-here TEST_CHANNEL_ID=C08UATXFD8B TEST_CHANNEL_NAME=testhyun TEAM_ID=A08TL5C310F ``` ## 각 도구의 사용법 및 예시 ### **1. 메시지 전송 기능** - **도구명**: `send_slack_message` - **매개변수**: - `channel`: 채널명 (예: testhyun) - `text`: 테스트 - **기능**: 지정된 Slack 채널에 메시지 전송 - **특별 요구사항**: UTF-8 인코딩으로 한글 메시지 지원 **사용 예시:** ```python send_slack_message( channel="testhyun", text="테스트" ) ``` ### **2. 채널 목록 조회 기능** - **도구명**: `get_slack_channels` - **매개변수**: 없음 - **기능**: 접근 가능한 모든 채널 목록 조회 - **반환 정보**: 채널 ID, 이름, 공개/비공개 여부, 멤버십 상태 **사용 예시:** ```python get_slack_channels() ``` ### **3. 채널 메시지 히스토리 조회 기능** - **도구명**: `get_slack_channel_history` - **매개변수**: - `channel_id`: 조회할 채널의 ID (예: C08UATXFD8B) - `limit`: 조회할 메시지 수 (기본값: 10, 최대: 100) - **기능**: 지정된 채널의 최근 메시지 히스토리 조회 - **반환 정보**: 메시지 내용, 작성자, 타임스탬프 **사용 예시:** ```python get_slack_channel_history( channel_id="C08UATXFD8B", limit=10 ) ``` ### **4. 다이렉트 메시지 전송 기능** - **도구명**: `send_slack_direct_message` - **매개변수**: - `user_id`: 메시지를 받을 사용자의 ID - `text`: 테스트 - **기능**: 특정 사용자에게 1:1 다이렉트 메시지 전송 **사용 예시:** ```python send_slack_direct_message( user_id="U1234567890", text="테스트" ) ``` ### **5. 사용자 목록 조회 기능** - **도구명**: `get_slack_users` - **매개변수**: 없음 - **기능**: 워크스페이스의 사용자 목록 조회 (다이렉트 메시지 전송 시 참고용) - **반환 정보**: 사용자 ID, 이름, 실제 이름, 이메일, 관리자 여부 **사용 예시:** ```python get_slack_users() ``` ## 구현 과정에서 겪은 어려움과 해결 방법 ### **1. Slack API 인증 문제** - **어려움**: 초기 Bot Token 설정 시 권한 부족으로 인한 `missing_scope` 오류 발생 - **해결 방법**: Slack 앱 설정에서 필요한 모든 Bot Token Scopes를 추가하고 재설치 ### **2. 한글 메시지 인코딩 문제** - **어려움**: 한글 메시지 전송 시 인코딩 오류 발생 - **해결 방법**: UTF-8 인코딩을 명시적으로 설정하고 Slack API 요청 시 적절한 헤더 설정 ### **3. 채널 접근 권한 문제** - **어려움**: 봇이 특정 채널에 접근할 수 없는 `not_in_channel` 오류 - **해결 방법**: 봇을 해당 채널에 수동으로 초대하거나 공개 채널에서 테스트 진행 ### **4. FastMCP 서버 구조 이해** - **어려움**: FastMCP의 도구 정의 및 매개변수 타입 지정 방법 학습 - **해결 방법**: 공식 문서 참조 및 예제 코드 분석을 통한 점진적 구현 ## 추가로 구현한 기능 ### **1. 포괄적인 오류 처리** - 각 API 호출에 대한 상세한 오류 메시지 및 상태 코드 반환 - 네트워크 오류, 인증 오류, 권한 오류 등에 대한 구체적인 해결 방안 제시 ### **2. 사용자 친화적인 응답 형식** - API 응답을 구조화된 딕셔너리 형태로 반환하여 디버깅 용이성 향상 - 성공/실패 상태와 함께 상세한 메타데이터 제공 ### **3. 테스트 스크립트 (`main.py`)** - 모든 기능을 체계적으로 테스트할 수 있는 종합 테스트 스크립트 - 실시간 결과 확인 및 디버깅 정보 제공 ### **4. 환경별 설정 관리** - `.env` 파일을 통한 환경 변수 관리 - 개발/운영 환경 분리 가능한 구조 ## 주의사항 - Slack Bot Token이 반드시 필요합니다. - 봇이 해당 채널에 추가되어야 메시지를 전송할 수 있습니다. - 비공개 채널의 경우, 봇이 해당 채널의 멤버여야 합니다. - API Rate Limit을 고려하여 사용하세요. ## 문제 해결 ### **자주 발생하는 오류** 1. **`not_in_channel`**: 봇이 해당 채널에 추가되지 않음 - 해결: Slack에서 봇을 채널에 초대 2. **`invalid_auth`**: 토큰이 유효하지 않음 - 해결: `.env` 파일의 `SLACK_BOT_TOKEN` 확인 3. **`missing_scope`**: 필요한 권한이 없음 - 해결: Slack 앱 설정에서 필요한 Bot Token Scopes 추가 4. **Import 오류**: 필요한 패키지가 설치되지 않음 - 해결: `pip install -r requirements.txt` 실행