yeoamlog/slack-mcp-server

Slack MCP Server - Complete Implementation

📋 프로젝트 개요

FastMCP v2를 사용하여 구현한 완전한 Slack API 연동 MCP 서버입니다. 과제 가이드라인에 따라 필수 기능 4개, 선택 기능 4개, 그리고 보너스 뽀모도로 타이머 기능 4개를 모두 구현했습니다.

🎯 주요 특징

• ✅ 완전한 UTF-8 한글 지원 - 모든 메시지에서 한글 완벽 지원
• ✅ 이중 토큰 시스템 - Bot Token + User Token으로 모든 기능 지원
• ✅ 스마트 파일 업로드 - 크기별 최적 업로드 방식 자동 선택
• ✅ 뽀모도로 타이머 - 자동 알림 기능이 포함된 시간 관리 도구
• ✅ 비동기 처리 - 고성능 asyncio 기반 구현
• ✅ 상세한 에러 핸들링 - 모든 API 호출에 대한 적절한 예외 처리

🚀 기능 목록

🔴 필수 기능 (Required Features - 4개)

1. send_slack_message - 메시지 전송

   • 채널 또는 DM에 메시지 전송
   • 스레드 답글 지원
   • 완전한 UTF-8 한글 지원

2. get_slack_channels - 채널 목록 조회

   • 공개/비공개 채널 구분
   • 멤버십 상태 확인
   • 보관된 채널 필터링

3. get_slack_channel_history - 메시지 히스토리 조회

   • 최신 메시지부터 조회
   • 시간 범위 지정 가능
   • 메시지 메타데이터 포함

4. send_slack_direct_message - DM 전송

   • 특정 사용자에게 1:1 메시지 전송
   • 자동 DM 채널 생성
   • 봇 사용자 필터링

🟡 선택 기능 (Optional Features - 4개)

5. get_slack_users - 사용자 목록 조회

   • 사용자 타입별 분류 (관리자, 멤버, 게스트, 봇)
   • DM 가능 사용자 필터링
   • 상세한 프로필 정보

6. search_slack_messages - 메시지 검색 (User Token 필요)

   • 키워드 기반 전체 워크스페이스 검색
   • 정렬 및 필터링 옵션
   • 검색 결과 메타데이터

7. upload_file_to_slack - 스마트 파일 업로드

   • 파일 크기별 최적 업로드 방식
   • 다양한 파일 형식 지원
   • 자동 미리보기 및 코드 하이라이팅

8. add_slack_reaction - 메시지 반응 추가

   • 이모지 반응 추가
   • 다양한 이모지 형식 지원

🟢 보너스 기능 (Bonus Features - 4개)

9. start_pomodoro_timer - 뽀모도로 타이머 시작

   • 5가지 타이머 타입 (study, work, break, meeting, custom)
   • 자동 시작/종료 알림
   • 사용자 정의 시간 및 메시지

10. cancel_pomodoro_timer - 타이머 취소

    • 실행 중인 타이머 즉시 중단
    • 취소 알림 전송

11. list_active_timers - 활성 타이머 목록

    • 현재 실행 중인 모든 타이머
    • 진행률 및 남은 시간 표시

12. get_timer_status - 타이머 상태 조회

    • 특정 타이머의 상세 상태
    • 실시간 진행 상황

🛠️ 유틸리티 기능

13. test_slack_connection - 연결 테스트
14. get_workspace_info - 워크스페이스 정보
15. get_file_preview - 파일 미리보기
16. verify_or_create_file - 파일 확인/생성

📦 설치 및 실행 방법

1. 프로젝트 초기화

# 프로젝트 클론 또는 다운로드 후
cd slack-mcp

# uv 패키지 매니저 설치 (없는 경우)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 가상환경 생성 및 활성화
uv venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows

# 의존성 설치
uv sync
# 또는
uv pip install -r requirements.txt

2. 환경 변수 설정

.env 파일을 생성하고 다음과 같이 설정:

# 필수: Slack Bot Token (xoxb-로 시작)
SLACK_BOT_TOKEN=xoxb-your-bot-token-here

# 선택: Slack User Token (xoxp-로 시작) - 검색, 파일업로드용
SLACK_USER_TOKEN=xoxp-your-user-token-here

# 선택: 기본 채널 ID (테스트용)
SLACK_TEST_CHANNEL_ID=C08UZKK9Q4R

# 선택: 로그 레벨
LOG_LEVEL=INFO

3. Slack App 설정

필요한 Bot Token Scopes:

channels:read        # 채널 목록 조회
channels:history     # 채널 메시지 히스토리 조회
chat:write          # 메시지 전송
im:read             # DM 채널 읽기
im:write            # DM 메시지 전송
im:history          # DM 히스토리 조회
users:read          # 사용자 정보 조회
reactions:write     # 반응 추가

추가 User Token Scopes (선택 기능용):

search:read         # 메시지 검색
files:write         # 파일 업로드

4. 서버 실행

# MCP 서버 실행
python slack_mcp_server.py

# 또는 직접 실행
uv run slack_mcp_server.py

💡 사용법 및 예시

기본 메시지 전송

# Claude/LLM이 도구 호출 시
send_slack_message(
    channel="C08UZKK9Q4R", 
    text="안녕하세요! MCP에서 보내는 메시지입니다! 🚀"
)

파일 업로드 (스마트 처리)

# 다양한 크기의 파일을 자동으로 최적 방식으로 업로드
upload_file_to_slack(
    file_path="./report.pdf",
    channels="C08UZKK9Q4R",
    title="분석 보고서",
    comment="월간 데이터 분석 결과입니다."
)

뽀모도로 타이머 사용

# 수업 타이머 시작 (50분)
start_pomodoro_timer(
    timer_type="study",
    channel_id="C08UZKK9Q4R",
    duration_minutes=50,
    custom_name="파이썬 고급 문법 학습"
)

# 활성 타이머 확인
list_active_timers()

# 타이머 취소
cancel_pomodoro_timer("study_20250602_143022_123456")

메시지 검색 (User Token 필요)

# 워크스페이스 전체에서 메시지 검색
search_slack_messages(
    query="MCP 서버",
    count=10,
    sort="timestamp"
)

🏗️ 프로젝트 구조

slack-mcp/
├── .env                     # 환경 변수 (Git 제외)
├── .env.example            # 환경 변수 템플릿
├── .gitignore              # Git 무시 파일
├── README.md               # 이 파일
├── requirements.txt        # 의존성 목록
├── pyproject.toml         # 프로젝트 설정
├── slack_api_client.py    # Slack API 클라이언트 (핵심 모듈)
├── pomodoro_timer.py      # 뽀모도로 타이머 모듈
└── slack_mcp_server.py    # FastMCP 서버 메인

🔧 기술적 구현 세부사항

이중 토큰 시스템

• Bot Token (xoxb-): 일반적인 봇 기능 (메시지 전송, 채널 조회 등)
• User Token (xoxp-): 사용자 권한 필요한 기능 (검색, 대용량 파일 업로드)

스마트 파일 업로드 전략

1. 작은 텍스트 파일 (< 50KB): 메시지 내용으로 직접 전송
2. 중간 파일 (50KB - 1MB): 코드 스니펫으로 업로드
3. 일반 파일 (1MB - 100MB): 표준 파일 업로드
4. 대용량 파일 (100MB - 1GB): User Token으로 업로드
5. 초대용량 파일 (> 1GB): 파일 정보만 공유

비동기 처리 및 동시성

• asyncio 기반 완전 비동기 구현
• 뽀모도로 타이머의 병렬 실행 지원
• 락(Lock)을 통한 클라이언트 초기화 안전성 보장

UTF-8 한글 지원

headers = {
    'Content-Type': 'application/json; charset=utf-8'
}

🐛 개발 과정에서 겪은 어려움과 해결 방법

1. 함수들 간의 Input 변수명 통일 어려움

문제: API 함수마다 매개변수 이름이 달라서 일관성 부족

• channel vs channel_id vs channels
• text vs message vs content

해결책:

• Slack API 공식 문서 기준으로 변수명 통일(향후 업데이트 예정)
• 내부 함수에서는 일관된 네이밍 컨벤션 적용
• docstring에 명확한 매개변수 설명 추가

async def send_message(
    self, 
    channel: str,      # 가능한 부분들은 channel 로 통일 예정
    text: str,         # 통일: text
    thread_ts: Optional[str] = None
) -> Dict[str, Any]:

2. Input-Output 변수명 찾기 어려움

문제: Slack API 응답의 복잡한 중첩 구조로 필요한 데이터 추출 어려움

해결책:

• API 응답을 로그로 출력하여 구조 파악
• 공통 데이터 추출 함수 작성
• 응답 데이터 정규화 및 포맷팅

# 응답 데이터 정규화 예시
formatted_messages.append({
    'text': msg.get('text', ''),
    'user': msg.get('user', 'Unknown'),
    'timestamp': readable_time,
    'ts': msg.get('ts', ''),
    # ... 필요한 필드만 추출
})

3. Outdated file_upload 함수를 최신 버전으로 사용하기까지 많은 시행착오

문제: Slack의 파일 업로드 API가 여러 번 변경되어 기존 방식 deprecated

해결책:

• files.upload (deprecated) → files.getUploadURLExternal + files.completeUploadExternal
• Slack SDK와 기존 REST API의 하이브리드 접근법
• 파일 크기별 다른 업로드 전략 구현

# 새로운 파일 업로드 플로우
# 1. 업로드 URL 요청
upload_response = await self._make_request('files.getUploadURLExternal', 'POST', upload_data)

# 2. 외부 URL로 파일 업로드
async with self._session.put(upload_url, data=file_content) as response:
    # 파일 업로드

# 3. 업로드 완료 처리
complete_response = await self._make_request('files.completeUploadExternal', 'POST', complete_data)

4. User Token이 필요한 경우 vs Bot Token만으로 해결되는 경우

문제: 어떤 기능에 어떤 토큰이 필요한지 파악하기 어려움

해결책:

• 기능별 토큰 요구사항 명확히 분류
• 이중 토큰 시스템으로 자동 선택
• 토큰 부족 시 명확한 안내 메시지

# Bot Token으로 가능한 기능
- 메시지 전송 (chat.postMessage)
- 채널 목록 (conversations.list)
- 사용자 목록 (users.list)
- 파일 업로드 (< 100MB)

# User Token이 필요한 기능  
- 메시지 검색 (search.messages)
- 대용량 파일 업로드 (> 100MB)

5. GET vs POST의 차이

문제: 언제 GET을 쓰고 언제 POST를 써야 하는지 혼란

해결책:

• Slack API 문서의 HTTP 메소드 정확히 확인
• 데이터 조회는 GET, 데이터 생성/수정은 POST
• 통일된 _make_request 함수로 처리

# GET: 데이터 조회
await self._make_request('conversations.list', 'GET', params)
await self._make_request('users.list', 'GET', params)

# POST: 데이터 생성/수정
await self._make_request('chat.postMessage', 'POST', data)
await self._make_request('files.getUploadURLExternal', 'POST', data)

6. 기타 해결한 이슈들

• Rate Limiting: 지수 백오프와 재시도 로직
• Error Handling: 각 에러 코드별 맞춤형 해결 제안
• UTF-8 Encoding: 한글 메시지 완벽 지원
• Async Safety: 뽀모도로 타이머의 동시 실행 처리

📊 성능 및 제한사항

파일 업로드 제한

• 무료 플랜: 최대 5GB 워크스페이스 스토리지
• 개별 파일: 최대 1GB (유료 플랜에서)
• Bot Token: 최대 100MB 파일 업로드
• User Token: 최대 1GB 파일 업로드

API Rate Limits

• Tier 1 메소드: 1+ per minute
• Tier 2 메소드: 20+ per minute
• Tier 3 메소드: 50+ per minute
• Tier 4 메소드: 100+ per minute

🔍 테스트 방법

1. 연결 테스트

# 서버 실행 후 Claude에서 테스트
test_slack_connection()

2. 기본 기능 테스트

# 채널 목록 조회
get_slack_channels()

# 메시지 전송 테스트  
send_slack_message("C08UZKK9Q4R", "테스트 메시지입니다! 🎉")

3. 고급 기능 테스트

# 파일 업로드 테스트
upload_file_to_slack("./test.txt", title="테스트 파일")

# 뽀모도로 타이머 테스트
start_pomodoro_timer("work", duration_minutes=25, custom_name="테스트 작업")

🤝 기여 방법

1. 이슈 제보: GitHub Issues 사용
2. 기능 제안: Feature Request 템플릿 사용
3. 코드 기여: Pull Request 환영
4. 문서 개선: README 및 docstring 개선

📄 라이선스

이 프로젝트는 MIT 라이선스를 따릅니다.

🙋‍♂️ 문의 및 지원

• 개발자: JunHyuck Kwon
• 버전: 8.5.2 (Complete Implementation)
• 최종 업데이트: 2025-06-04

과제 완성도: ✅ 필수 4개 + ✅ 선택 4개 + ✅ 보너스 4개 + ✅ 유틸리티 4개 = 총 16개 기능 완전 구현

이 프로젝트를 통해 실제 업무에서 활용할 수 있는 고품질 Slack 연동 도구를 구축할 수 있습니다! 🚀