Slack MCP Server

Slack MCP Server

프로젝트 개요 및 기능 설명

이 프로젝트는 FastMCP v2를 사용하여 Slack API와 연동되는 MCP(Model Context Protocol) 서버를 구축하는 것을 목표로 합니다. Slack 워크스페이스와의 다양한 상호작용을 제공하며, UTF-8 인코딩을 통한 한글 메시지 지원을 포함합니다.

주요 기능

• Slack 채널에 메시지 전송
• 채널 목록 조회 및 관리
• 채널 메시지 히스토리 조회
• 사용자 간 다이렉트 메시지 전송
• 워크스페이스 사용자 목록 조회

설치 및 실행 방법

1. 의존성 설치

2. 가상환경 설정 (권장)

3. MCP 서버 실행

4. 테스트 스크립트 실행

환경 변수 설정 방법

1. Slack 앱 생성 및 설정

1. Slack API 사이트에서 새 앱 생성
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 파일을 생성하고 다음과 같이 설정:

각 도구의 사용법 및 예시

1. 메시지 전송 기능

• 도구명: send_slack_message
• 매개변수:
  • channel: 채널명 (예: testhyun)
  • text: 테스트
• 기능: 지정된 Slack 채널에 메시지 전송
• 특별 요구사항: UTF-8 인코딩으로 한글 메시지 지원

사용 예시:

2. 채널 목록 조회 기능

• 도구명: get_slack_channels
• 매개변수: 없음
• 기능: 접근 가능한 모든 채널 목록 조회
• 반환 정보: 채널 ID, 이름, 공개/비공개 여부, 멤버십 상태

사용 예시:

3. 채널 메시지 히스토리 조회 기능

• 도구명: get_slack_channel_history
• 매개변수:
  • channel_id: 조회할 채널의 ID (예: C08UATXFD8B)
  • limit: 조회할 메시지 수 (기본값: 10, 최대: 100)
• 기능: 지정된 채널의 최근 메시지 히스토리 조회
• 반환 정보: 메시지 내용, 작성자, 타임스탬프

사용 예시:

4. 다이렉트 메시지 전송 기능

• 도구명: send_slack_direct_message
• 매개변수:
  • user_id: 메시지를 받을 사용자의 ID
  • text: 테스트
• 기능: 특정 사용자에게 1:1 다이렉트 메시지 전송

사용 예시:

5. 사용자 목록 조회 기능

• 도구명: get_slack_users
• 매개변수: 없음
• 기능: 워크스페이스의 사용자 목록 조회 (다이렉트 메시지 전송 시 참고용)
• 반환 정보: 사용자 ID, 이름, 실제 이름, 이메일, 관리자 여부

사용 예시:

구현 과정에서 겪은 어려움과 해결 방법

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 실행