Slack MCP Server - Complete Implementation

📋 프로젝트 개요

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

🎯 주요 특징

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

Related MCP server: Slack Search MCP Server

🚀 기능 목록

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

send_slack_message - 메시지 전송
- 채널 또는 DM에 메시지 전송
- 스레드 답글 지원
- 완전한 UTF-8 한글 지원
get_slack_channels - 채널 목록 조회
- 공개/비공개 채널 구분
- 멤버십 상태 확인
- 보관된 채널 필터링
get_slack_channel_history - 메시지 히스토리 조회
- 최신 메시지부터 조회
- 시간 범위 지정 가능
- 메시지 메타데이터 포함
send_slack_direct_message - DM 전송
- 특정 사용자에게 1:1 메시지 전송
- 자동 DM 채널 생성
- 봇 사용자 필터링

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

get_slack_users - 사용자 목록 조회
- 사용자 타입별 분류 (관리자, 멤버, 게스트, 봇)
- DM 가능 사용자 필터링
- 상세한 프로필 정보
search_slack_messages - 메시지 검색 (User Token 필요)
- 키워드 기반 전체 워크스페이스 검색
- 정렬 및 필터링 옵션
- 검색 결과 메타데이터
upload_file_to_slack - 스마트 파일 업로드
- 파일 크기별 최적 업로드 방식
- 다양한 파일 형식 지원
- 자동 미리보기 및 코드 하이라이팅
add_slack_reaction - 메시지 반응 추가
- 이모지 반응 추가
- 다양한 이모지 형식 지원

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

start_pomodoro_timer - 뽀모도로 타이머 시작
- 5가지 타이머 타입 (study, work, break, meeting, custom)
- 자동 시작/종료 알림
- 사용자 정의 시간 및 메시지
cancel_pomodoro_timer - 타이머 취소
- 실행 중인 타이머 즉시 중단
- 취소 알림 전송
list_active_timers - 활성 타이머 목록
- 현재 실행 중인 모든 타이머
- 진행률 및 남은 시간 표시
get_timer_status - 타이머 상태 조회
- 특정 타이머의 상세 상태
- 실시간 진행 상황

🛠️ 유틸리티 기능

test_slack_connection - 연결 테스트
get_workspace_info - 워크스페이스 정보
get_file_preview - 파일 미리보기
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-): 사용자 권한 필요한 기능 (검색, 대용량 파일 업로드)

스마트 파일 업로드 전략

작은 텍스트 파일 (< 50KB): 메시지 내용으로 직접 전송
중간 파일 (50KB - 1MB): 코드 스니펫으로 업로드
일반 파일 (1MB - 100MB): 표준 파일 업로드
대용량 파일 (100MB - 1GB): User Token으로 업로드
초대용량 파일 (> 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="테스트 작업")

🤝 기여 방법

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

📄 라이선스

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

🙋‍♂️ 문의 및 지원

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

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

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

Slack MCP Server - Complete Implementation

📋 프로젝트 개요

🎯 주요 특징

🚀 기능 목록

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

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

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

🛠️ 유틸리티 기능

📦 설치 및 실행 방법

1. 프로젝트 초기화

2. 환경 변수 설정

3. Slack App 설정

필요한 Bot Token Scopes:

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

4. 서버 실행

💡 사용법 및 예시

기본 메시지 전송

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

뽀모도로 타이머 사용

메시지 검색 (User Token 필요)

🏗️ 프로젝트 구조

🔧 기술적 구현 세부사항

이중 토큰 시스템

스마트 파일 업로드 전략

비동기 처리 및 동시성

UTF-8 한글 지원

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

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

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

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

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

5. GET vs POST의 차이

6. 기타 해결한 이슈들

📊 성능 및 제한사항

파일 업로드 제한

API Rate Limits

🔍 테스트 방법

1. 연결 테스트

2. 기본 기능 테스트

3. 고급 기능 테스트

🤝 기여 방법

📄 라이선스

🙋‍♂️ 문의 및 지원

Resources

New MCP Servers

Latest Blog Posts

MCP directory API