Slack MCP Server - Complete Implementation

Slack MCP サーバー - 完全実装

📋 プロジェクト概要

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. 関数間での入力変数名の統一が難しい

問題：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. 入出力の変数名を見つけるのが難しい

問題：Slack API の応答が複雑な入れ子構造になっているため、必要なデータを抽出するのが困難です。

解決策：

• API の応答をログに出力して構造を把握
• 共通のデータ抽出関数を作成
• 応答データを正規化してフォーマット

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

3. 古い file_upload 関数から最新の方式に移行するまで、多くの試行錯誤が必要

問題：Slack のファイルアップロード API は何度も変更されており、従来の方式は非推奨になっています。

解決策：

• files.upload（非推奨）→ 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 が必要な場合と Bot Token のみで対応できる場合

問題：どの機能にどのトークンが必要なのか把握するのが困難です。

解決策：

• 機能ごとのトークン要件を明確に分類
• 二重トークンシステムで自動選択
• トークンが不足している場合は明確な案内メッセージを表示

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

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

5. GET と 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 연동 도구를 구축할 수 있습니다! 🚀