Slack MCP Server
프로젝트 개요 및 기능 설명
이 프로젝트는 FastMCP v2를 사용하여 Slack API와 연동되는 MCP(Model Context Protocol) 서버를 구축하는 것을 목표로 합니다. Slack 워크스페이스와의 다양한 상호작용을 제공하며, UTF-8 인코딩을 통한 한글 메시지 지원을 포함합니다.
주요 기능
- Slack 채널에 메시지 전송
- 채널 목록 조회 및 관리
- 채널 메시지 히스토리 조회
- 사용자 간 다이렉트 메시지 전송
- 워크스페이스 사용자 목록 조회
설치 및 실행 방법
1. 의존성 설치
cd 0527/slack-mcp
pip install -r requirements.txt
2. 가상환경 설정 (권장)
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
3. MCP 서버 실행
python slack_mcp_server.py
4. 테스트 스크립트 실행
python main.py
환경 변수 설정 방법
1. Slack 앱 생성 및 설정
-
Slack API 사이트에서 새 앱 생성
-
OAuth & Permissions 섹션에서 다음 Bot Token Scopes 추가:
channels:read(공개 채널 목록 조회)groups:read(비공개 채널 목록 조회)channels:history(채널 메시지 히스토리 조회)groups:history(비공개 채널 메시지 히스토리 조회)chat:write(메시지 전송)users:read(사용자 정보 조회)im:write(다이렉트 메시지 전송)mpim:write(그룹 DM 전송)
-
Install App to Workspace 클릭하여 워크스페이스에 설치
-
Bot User OAuth Token (xoxb-로 시작하는 토큰) 복사
2. .env 파일 생성
프로젝트 루트에 .env 파일을 생성하고 다음과 같이 설정:
# .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 인코딩으로 한글 메시지 지원
사용 예시:
send_slack_message(
channel="testhyun",
text="테스트"
)
2. 채널 목록 조회 기능
- 도구명:
get_slack_channels - 매개변수: 없음
- 기능: 접근 가능한 모든 채널 목록 조회
- 반환 정보: 채널 ID, 이름, 공개/비공개 여부, 멤버십 상태
사용 예시:
get_slack_channels()
3. 채널 메시지 히스토리 조회 기능
- 도구명:
get_slack_channel_history - 매개변수:
channel_id: 조회할 채널의 ID (예: C08UATXFD8B)limit: 조회할 메시지 수 (기본값: 10, 최대: 100)
- 기능: 지정된 채널의 최근 메시지 히스토리 조회
- 반환 정보: 메시지 내용, 작성자, 타임스탬프
사용 예시:
get_slack_channel_history(
channel_id="C08UATXFD8B",
limit=10
)
4. 다이렉트 메시지 전송 기능
- 도구명:
send_slack_direct_message - 매개변수:
user_id: 메시지를 받을 사용자의 IDtext: 테스트
- 기능: 특정 사용자에게 1:1 다이렉트 메시지 전송
사용 예시:
send_slack_direct_message(
user_id="U1234567890",
text="테스트"
)
5. 사용자 목록 조회 기능
- 도구명:
get_slack_users - 매개변수: 없음
- 기능: 워크스페이스의 사용자 목록 조회 (다이렉트 메시지 전송 시 참고용)
- 반환 정보: 사용자 ID, 이름, 실제 이름, 이메일, 관리자 여부
사용 예시:
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을 고려하여 사용하세요.
문제 해결
자주 발생하는 오류
-
not_in_channel: 봇이 해당 채널에 추가되지 않음- 해결: Slack에서 봇을 채널에 초대
-
invalid_auth: 토큰이 유효하지 않음- 해결:
.env파일의SLACK_BOT_TOKEN확인
- 해결:
-
missing_scope: 필요한 권한이 없음- 해결: Slack 앱 설정에서 필요한 Bot Token Scopes 추가
-
Import 오류: 필요한 패키지가 설치되지 않음
- 해결:
pip install -r requirements.txt실행
- 해결: