Slack MCP Server - Complete Implementation

📋 프로젝트 개요

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

🎯 주요 특징

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

🚀 기능 목록

🔴 필수 기능 (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 연동 도구를 구축할 수 있습니다! 🚀

This server cannot be installed

security - not tested

license - not tested

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A comprehensive Slack integration server that enables sending messages, managing channels, uploading files, and running Pomodoro timers through FastMCP v2.

Related MCP Servers

Slack MCP Server
modelcontextprotocol
A
security
-
license
A
quality
MCP Server for the Slack API, enabling Claude to interact with Slack workspaces.
Last updated -
11,120
71,283
MIT License
Slack Search MCP Server
takuya0206
-
security
-
license
-
quality
An MCP server that enables LLMs to access Slack's search functionality to retrieve users, channels, messages, and thread replies from a Slack workspace.
Last updated -
3
Slack MCP
korotovsky
A
security
-
license
A
quality
The most powerful MCP server for Slack Workspaces. This integration supports both Stdio and SSE transports, proxy settings and does not require any permissions or bots being created or approved by Workspace admins 😏.
Last updated -
2
823
MIT License
Slack MCP Server
teresjsiu
-
security
-
license
-
quality
A FastMCP-based server that provides complete Slack integration for Cursor IDE, allowing users to interact with Slack API features using natural language.
Last updated -

View all related MCP servers

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. 고급 기능 테스트

🤝 기여 방법

📄 라이선스

🙋‍♂️ 문의 및 지원

Related MCP Servers

Slack MCP Server

Slack Search MCP Server

Slack MCP

Slack MCP Server

New MCP Servers

MCP directory API