🚀 Slack MCP Server
FastMCP를 사용한 완전한 Slack 통합 MCP 서버입니다. Cursor IDE에서 Slack API의 모든 기능을 자연어로 사용할 수 있게 해줍니다.
📋 목차
✨ 특징
필수 기능 (과제 요구사항)
- ✅ 메시지 전송: 채널에 메시지 전송
- ✅ 채널 목록 조회: 접근 가능한 모든 채널 조회
- ✅ 채널 히스토리 조회: 지정된 채널의 메시지 히스토리
- ✅ 다이렉트 메시지: 1:1 메시지 전송
추가 기능
- ✅ 사용자 목록 조회: 워크스페이스 사용자 정보
- ✅ 반응 추가: 메시지에 이모지 반응 추가
- ✅ 메시지 검색: 키워드 기반 메시지 검색
- ✅ 연결 테스트: API 연결 상태 확인
기술적 특징
- 🚀 FastMCP 기반: 최신 MCP 프레임워크 사용
- ⚡ 비동기 처리: aiohttp를 이용한 고성능 API 호출
- 🛡️ 완전한 에러 처리: 상세한 오류 메시지와 복구 가능한 예외 처리
- 📝 타입 힌트: 완전한 타입 안정성
- 🧪 포괄적 테스트: 자동화된 테스트 스위트
- 📊 로깅: 구조화된 로깅 시스템
- 🔧 자동 설치: 원클릭 설치 스크립트
📋 요구사항
- Python 3.8+
- pip (패키지 관리자)
- Cursor IDE (MCP 클라이언트)
- Slack Bot Token (xoxb-로 시작)
Slack Bot 권한
Slack 앱에 다음 권한이 필요합니다:
Bot Token Scopes:
- channels:history # 채널 메시지 읽기
- channels:read # 채널 정보 조회
- chat:write # 메시지 전송
- groups:history # 비공개 그룹 메시지 읽기
- groups:read # 비공개 그룹 정보 조회
- im:history # DM 메시지 읽기
- im:read # DM 정보 조회
- im:write # DM 전송
- mpim:history # 멀티파티 DM 메시지 읽기
- mpim:read # 멀티파티 DM 정보 조회
- mpim:write # 멀티파티 DM 전송
- reactions:write # 반응 추가
- search:read # 메시지 검색
- users:read # 사용자 정보 조회
🚀 빠른 설치
1. 자동 설치 (권장)
cd slack-mcp
python install.py
설치 스크립트가 다음을 자동으로 처리합니다:
- 패키지 설치
- 환경 변수 설정
- Cursor MCP 설정 업데이트
- 설치 테스트 실행
2. Cursor 재시작
설치 완료 후 Cursor를 재시작하면 Slack MCP 도구를 사용할 수 있습니다.
🔧 수동 설치
1. 저장소 클론
git clone <repository-url>
cd slack-mcp
2. 패키지 설치
pip install -r requirements.txt
3. 환경 변수 설정
.env 파일 생성:
# Slack Bot Token (xoxb-로 시작하는 토큰)
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
# 선택적: 로그 레벨 설정
LOG_LEVEL=INFO
4. Cursor MCP 설정
~/.cursor/mcp.json 파일에 다음 추가:
{
"mcpServers": {
"slack": {
"command": "python",
"args": ["/path/to/slack-mcp/slack_mcp_server.py"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-your-bot-token-here"
}
}
}
}
5. 테스트 실행
python test_slack_mcp.py
📖 사용법
Cursor에서 새 채팅을 시작하고 다음과 같이 자연어로 Slack 기능을 사용할 수 있습니다:
메시지 전송
#general 채널에 "안녕하세요!"라는 메시지를 보내주세요
채널 정보 조회
사용 가능한 Slack 채널 목록을 보여주세요
메시지 히스토리
#general 채널의 최근 메시지 10개를 가져와주세요
다이렉트 메시지
사용자 U1234567890에게 "회의 준비 완료"라는 DM을 보내주세요
메시지 검색
"프로젝트"라는 키워드가 포함된 메시지를 검색해주세요
🛠️ 사용 가능한 도구
| 도구 | 설명 | 파라미터 |
|---|---|---|
send_slack_message | 채널에 메시지 전송 | channel, text |
get_slack_channels | 채널 목록 조회 | 없음 |
get_slack_channel_history | 채널 히스토리 조회 | channel_id, limit |
send_slack_direct_message | 다이렉트 메시지 전송 | user_id, text |
get_slack_users | 사용자 목록 조회 | 없음 |
add_slack_reaction | 메시지에 반응 추가 | channel, timestamp, name |
search_slack_messages | 메시지 검색 | query, count |
test_slack_connection | 연결 테스트 | 없음 |
📁 프로젝트 구조
slack-mcp/
├── 📄 README.md # 이 파일
├── 📄 requirements.txt # Python 패키지 의존성
├── 📄 slack_api.py # Slack API 클라이언트
├── 📄 slack_mcp_server.py # FastMCP 서버 구현
├── 📄 test_slack_mcp.py # 테스트 스크립트
├── 📄 install.py # 자동 설치 스크립트
├── 📄 mcp_config.json # MCP 설정 템플릿
├── 📄 env_example.txt # 환경 변수 템플릿
└── 📄 .gitignore # Git 무시 파일
👨💻 개발자 가이드
개발 환경 설정
# 개발 모드로 패키지 설치
pip install -r requirements.txt
# 환경 변수 설정
cp env_example.txt .env
# .env 파일을 편집하여 실제 토큰 입력
# 테스트 실행
python test_slack_mcp.py
새로운 도구 추가
slack_api.py에 API 메서드 추가slack_mcp_server.py에 MCP 도구 데코레이터 추가test_slack_mcp.py에 테스트 케이스 추가
로깅
서버는 다음 위치에 로그를 기록합니다:
- 콘솔 출력: 실시간 로그 확인
- 파일 로그:
slack_mcp.log
디버깅
# 상세 로그와 함께 테스트 실행
LOG_LEVEL=DEBUG python test_slack_mcp.py
# 서버 직접 실행 (디버깅용)
python slack_mcp_server.py
🔍 문제 해결
자주 발생하는 문제
1. "SLACK_BOT_TOKEN 환경 변수가 설정되지 않았습니다"
해결책:
.env파일에 올바른 토큰이 있는지 확인- 토큰이
xoxb-로 시작하는지 확인
2. "invalid_auth" 에러
해결책:
- Slack Bot Token이 유효한지 확인
- 토큰이 올바른 워크스페이스용인지 확인
- 필요한 권한이 모두 부여되었는지 확인
3. "channel_not_found" 에러
해결책:
- 채널 ID가 올바른지 확인
- 봇이 해당 채널에 추가되었는지 확인
- 공개 채널인지 또는 봇이 초대되었는지 확인
4. Cursor에서 MCP 도구가 보이지 않음
해결책:
- Cursor를 완전히 재시작
~/.cursor/mcp.json설정 파일 확인- 파일 경로가 올바른지 확인
로그 확인
# 서버 로그 확인
tail -f slack_mcp.log
# 테스트 로그와 함께 실행
python test_slack_mcp.py 2>&1 | tee debug.log
수동 연결 테스트
# Python에서 직접 테스트
python -c "
import asyncio
from slack_api import get_slack_client
import os
from dotenv import load_dotenv
load_dotenv()
token = os.getenv('SLACK_BOT_TOKEN')
client = get_slack_client(token)
async def test():
result = await client.test_connection()
print(result)
asyncio.run(test())
"
📋 과제 요구사항 대비 현황
| 요구사항 | 상태 | 구현 위치 |
|---|---|---|
| 필수 기능 | ||
| 메시지 전송 | ✅ 완료 | send_slack_message |
| 채널 목록 조회 | ✅ 완료 | get_slack_channels |
| 채널 히스토리 조회 | ✅ 완료 | get_slack_channel_history |
| 다이렉트 메시지 | ✅ 완료 | send_slack_direct_message |
| 선택 기능 | ||
| 사용자 목록 조회 | ✅ 완료 | get_slack_users |
| 반응 추가 | ✅ 완료 | add_slack_reaction |
| 메시지 검색 | ✅ 완료 | search_slack_messages |
| 기술 요구사항 | ||
| FastMCP 사용 | ✅ 완료 | slack_mcp_server.py |
| 에러 처리 | ✅ 완료 | 모든 도구에 try-catch |
| 타입 힌트 | ✅ 완료 | 모든 함수에 타입 힌트 |
| 로깅 | ✅ 완료 | 구조화된 로깅 시스템 |
| 테스트 | ✅ 완료 | test_slack_mcp.py |
| 문서화 | ✅ 완료 | 이 README 및 코드 주석 |
🏆 추가 구현 사항
과제 요구사항을 넘어서 다음 기능들을 추가로 구현했습니다:
- 🔄 자동 설치 시스템: 원클릭 설치 스크립트
- 🧪 포괄적 테스트: 모든 기능에 대한 자동화된 테스트
- 📊 상세한 응답 포맷팅: 구조화된 성공/실패 응답
- ⚡ 비동기 HTTP 클라이언트: 고성능 aiohttp 사용
- 🛡️ 세션 관리: HTTP 세션 재사용으로 성능 최적화
- 🔧 개발자 도구: 디버깅 및 문제 해결 도구
- 📁 완전한 프로젝트 구조: 생산 준비 완료된 코드 구조
📄 라이선스
MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.
🚀 시작하기
# 1. 프로젝트 클론
git clone <repository-url>
cd slack-mcp
# 2. 자동 설치 실행
python install.py
# 3. Cursor 재시작
# 이제 Cursor에서 Slack MCP 도구를 사용할 수 있습니다!
문제가 있으시면 Issues에 보고해주세요.