Discord MCP Server
A comprehensive Model Context Protocol (MCP) server for Discord integration. This server exposes all Discord functionality as MCP tools, enabling seamless integration with AI assistants like OpenAI, LangChain, Cursor, and Claude.
🌟 Features
- Complete Discord API Coverage: Channels, messages, threads, reactions, roles, webhooks, and more
- MCP Standard Compliance: JSON-RPC 2.0 based standardized API
- High Performance: Redis caching, rate limiting, automatic retries with exponential backoff
- Security First: Mention filtering, minimal permissions, audit logging
- Production Ready: Docker support, CI/CD pipeline, comprehensive monitoring
- Advanced AI Features: Message summarization, activity analysis, intelligent filtering
🚀 Quick Start
Prerequisites
- Python 3.12+
- Discord Bot Token
- Redis 6.0+ (optional - uses in-memory cache if not available)
Installation
-
Clone the repository
git clone https://github.com/tristan-kkim/discord-mcp.git cd discord-mcp -
Install dependencies
pip install -r requirements.txt -
Configure environment
cp .env.example .env # Edit .env with your Discord Bot Token -
Run the server
python run.py
Docker Deployment
# Using Docker Compose (recommended)
export DISCORD_BOT_TOKEN=your_bot_token_here
docker-compose up -d
# Or using Docker directly
docker build -t discord-mcp .
docker run -d -p 8000:8000 -e DISCORD_BOT_TOKEN=your_token discord-mcp
🔧 MCP Client Integration
Cursor IDE
- Open Cursor Settings → MCP Servers
- Add server:
http://localhost:8000/mcp - Start using Discord tools in your AI conversations
OpenAI ChatGPT
- Create a Custom GPT
- Add Action with URL:
http://your-server:8000/mcp - Configure with your Discord server details
Claude Desktop
Add to your MCP configuration:
{
"mcpServers": {
"discord-mcp": {
"command": "uvx",
"args": ["discord-mcp@latest"],
"env": {
"DISCORD_BOT_TOKEN": "your_bot_token"
}
}
}
}
📚 Available MCP Tools
Channel & Guild Management
discord.list_guilds- List all guilds the bot is member ofdiscord.list_channels- List channels in a guilddiscord.get_channel- Get channel informationdiscord.create_channel- Create a new channeldiscord.update_channel- Update channel settingsdiscord.delete_channel- Delete a channel
Message Management
discord.list_messages- List messages in a channeldiscord.get_message- Get specific messagediscord.send_message- Send a messagediscord.edit_message- Edit a messagediscord.delete_message- Delete a messagediscord.search_messages- Search messages with filters
Thread Management
discord.create_thread- Create a threaddiscord.list_threads- List active/archived threadsdiscord.archive_thread- Archive a threaddiscord.unarchive_thread- Unarchive a thread
Reactions, Pins & Webhooks
discord.add_reaction- Add reaction to messagediscord.remove_reaction- Remove reactiondiscord.list_reactions- List all reactionsdiscord.pin_message- Pin a messagediscord.unpin_message- Unpin a messagediscord.create_webhook- Create webhookdiscord.send_via_webhook- Send message via webhook
Role & Permission Management
discord.list_roles- List guild rolesdiscord.add_role- Assign role to memberdiscord.remove_role- Remove role from memberdiscord.get_permissions- Get permission information
Advanced AI Features
discord.summarize_messages- AI-powered message summarizationdiscord.rank_messages- Intelligent message rankingdiscord.sync_since- Delta synchronizationdiscord.analyze_channel_activity- Channel activity analysis
🔍 API Reference
Endpoints
GET /- Server statusGET /health- Health checkGET /metrics- Prometheus-compatible metricsPOST /mcp- MCP JSON-RPC endpoint
Example Usage
# List available tools
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "mcp_list_tools", "id": 1}'
# Send a message
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "mcp_call_tool",
"params": {
"tool": "discord.send_message",
"params": {
"channel_id": "123456789",
"content": "Hello from MCP!"
}
},
"id": 1
}'
🔒 Security
Bot Token Security
- Never expose your bot token - Treat it like a password
- Use environment variables - Never hardcode in source code
- Minimal permissions - Only grant necessary Discord permissions
Required Discord Permissions
Send Messages- Send messages to channelsRead Message History- Read message historyManage Messages- Edit/delete messagesAdd Reactions- Add reactions to messagesManage Channels- Create/modify channels (if needed)Manage Roles- Manage roles (if needed)
Built-in Security Features
- Automatic
@everyoneand@heremention filtering - Rate limiting with Discord API compliance
- Audit logging for all operations
- Input validation and sanitization
📊 Monitoring & Observability
Health Checks
curl http://localhost:8000/health
Metrics
curl http://localhost:8000/metrics
Logging
All logs are structured JSON with fields:
request_id- Unique request identifiertool- MCP tool being calledchannel_id- Discord channel contextlatency_ms- Response timesuccess- Operation success status
🚀 Production Deployment
Environment Variables
| Variable | Description | Default | Required |
|---|---|---|---|
DISCORD_BOT_TOKEN | Discord Bot Token | - | ✅ |
REDIS_URL | Redis connection URL | redis://localhost:6379 | ❌ |
LOG_LEVEL | Logging level | INFO | ❌ |
RATE_LIMIT_ENABLED | Enable rate limiting | true | ❌ |
CACHE_TTL | Cache TTL in seconds | 300 | ❌ |
HOST | Server host | 0.0.0.0 | ❌ |
PORT | Server port | 8000 | ❌ |
Cloud Deployment
Heroku
heroku create your-discord-mcp
heroku config:set DISCORD_BOT_TOKEN=your_token
git push heroku main
Railway
railway login
railway init
railway add redis
railway deploy
AWS ECS/Fargate
# Use provided Dockerfile
docker build -t discord-mcp .
# Deploy to ECS with environment variables
🧪 Testing
# Install test dependencies
pip install pytest pytest-asyncio pytest-cov
# Run unit tests
pytest tests/test_tools/
# Run integration tests
pytest tests/test_integration/
# Run with coverage
pytest --cov=. --cov-report=html
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
📚 Documentation
- Wiki: Complete Documentation
- Installation Guide: Step-by-step Setup
- Quick Start: 5-minute Setup
- API Reference: Complete API Docs
- Security Guide: Best Practices
🆘 Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
🔄 Changelog
v1.0.0 (2024-10-29)
- 🎉 Initial release
- ✅ Complete Discord API integration
- ✅ MCP standard compliance
- ✅ Docker support
- ✅ Advanced AI features
- ✅ Security enhancements
- ✅ Comprehensive documentation
한국어 문서
Discord MCP 서버
Discord와 통신하는 Model Context Protocol(MCP) 서버입니다. 모든 Discord 기능을 MCP Tool 형태로 노출하여 OpenAI, LangChain, Cursor 등의 MCP 클라이언트에서 안전하게 사용할 수 있습니다.
🌟 주요 기능
- 완전한 Discord API 지원: 채널, 메시지, 스레드, 리액션, 역할, 웹훅 등 모든 Discord 기능
- MCP 표준 준수: JSON-RPC 2.0 기반의 표준화된 API
- 고성능: Redis 캐싱, Rate limit 관리, 지수 백오프 재시도
- 보안 우선: 멘션 필터링, 최소 권한, 감사 로그
- 프로덕션 준비: Docker 지원, CI/CD 파이프라인, 포괄적 모니터링
- 고급 AI 기능: 메시지 요약, 활동 분석, 지능형 필터링
🚀 빠른 시작
사전 요구사항
- Python 3.12+
- Discord Bot Token
- Redis 6.0+ (선택사항 - 없으면 메모리 캐시 사용)
설치
-
저장소 클론
git clone https://github.com/tristan-kkim/discord-mcp.git cd discord-mcp -
의존성 설치
pip install -r requirements.txt -
환경 설정
cp .env.example .env # .env 파일에 Discord Bot Token 설정 -
서버 실행
python run.py
Docker 배포
# Docker Compose 사용 (권장)
export DISCORD_BOT_TOKEN=your_bot_token_here
docker-compose up -d
# 또는 Docker 직접 사용
docker build -t discord-mcp .
docker run -d -p 8000:8000 -e DISCORD_BOT_TOKEN=your_token discord-mcp
🔧 MCP 클라이언트 통합
Cursor IDE
- Cursor 설정 → MCP 서버 열기
- 서버 추가:
http://localhost:8000/mcp - AI 대화에서 Discord 도구 사용 시작
OpenAI ChatGPT
- Custom GPT 생성
- Action 추가:
http://your-server:8000/mcp - Discord 서버 세부사항으로 구성
Claude Desktop
MCP 구성에 추가:
{
"mcpServers": {
"discord-mcp": {
"command": "uvx",
"args": ["discord-mcp@latest"],
"env": {
"DISCORD_BOT_TOKEN": "your_bot_token"
}
}
}
}
📚 사용 가능한 MCP 도구
채널 및 길드 관리
discord.list_guilds- 봇이 속한 모든 길드 목록discord.list_channels- 길드의 채널 목록discord.get_channel- 채널 정보 조회discord.create_channel- 새 채널 생성discord.update_channel- 채널 설정 업데이트discord.delete_channel- 채널 삭제
메시지 관리
discord.list_messages- 채널의 메시지 목록discord.get_message- 특정 메시지 조회discord.send_message- 메시지 전송discord.edit_message- 메시지 편집discord.delete_message- 메시지 삭제discord.search_messages- 필터로 메시지 검색
스레드 관리
discord.create_thread- 스레드 생성discord.list_threads- 활성/아카이브된 스레드 목록discord.archive_thread- 스레드 아카이브discord.unarchive_thread- 스레드 언아카이브
리액션, 핀 및 웹훅
discord.add_reaction- 메시지에 리액션 추가discord.remove_reaction- 리액션 제거discord.list_reactions- 모든 리액션 목록discord.pin_message- 메시지 고정discord.unpin_message- 메시지 고정 해제discord.create_webhook- 웹훅 생성discord.send_via_webhook- 웹훅으로 메시지 전송
역할 및 권한 관리
discord.list_roles- 길드 역할 목록discord.add_role- 멤버에게 역할 부여discord.remove_role- 멤버에서 역할 제거discord.get_permissions- 권한 정보 조회
고급 AI 기능
discord.summarize_messages- AI 기반 메시지 요약discord.rank_messages- 지능형 메시지 순위discord.sync_since- 델타 동기화discord.analyze_channel_activity- 채널 활동 분석
🔒 보안
Bot Token 보안
- Bot 토큰을 절대 노출하지 마세요 - 비밀번호처럼 취급
- 환경변수 사용 - 소스코드에 하드코딩 금지
- 최소 권한 - 필요한 Discord 권한만 부여
필요한 Discord 권한
Send Messages- 채널에 메시지 전송Read Message History- 메시지 기록 읽기Manage Messages- 메시지 편집/삭제Add Reactions- 메시지에 리액션 추가Manage Channels- 채널 생성/수정 (필요시)Manage Roles- 역할 관리 (필요시)
내장 보안 기능
@everyone및@here멘션 자동 필터링- Discord API 준수 Rate limiting
- 모든 작업에 대한 감사 로그
- 입력 검증 및 정제
📊 모니터링 및 관찰성
헬스체크
curl http://localhost:8000/health
메트릭
curl http://localhost:8000/metrics
로깅
모든 로그는 다음 필드가 포함된 구조화된 JSON입니다:
request_id- 고유 요청 식별자tool- 호출되는 MCP 도구channel_id- Discord 채널 컨텍스트latency_ms- 응답 시간success- 작업 성공 상태
🚀 프로덕션 배포
환경 변수
| 변수 | 설명 | 기본값 | 필수 |
|---|---|---|---|
DISCORD_BOT_TOKEN | Discord Bot Token | - | ✅ |
REDIS_URL | Redis 연결 URL | redis://localhost:6379 | ❌ |
LOG_LEVEL | 로깅 레벨 | INFO | ❌ |
RATE_LIMIT_ENABLED | Rate limiting 활성화 | true | ❌ |
CACHE_TTL | 캐시 TTL (초) | 300 | ❌ |
HOST | 서버 호스트 | 0.0.0.0 | ❌ |
PORT | 서버 포트 | 8000 | ❌ |
클라우드 배포
Heroku
heroku create your-discord-mcp
heroku config:set DISCORD_BOT_TOKEN=your_token
git push heroku main
Railway
railway login
railway init
railway add redis
railway deploy
AWS ECS/Fargate
# 제공된 Dockerfile 사용
docker build -t discord-mcp .
# 환경 변수와 함께 ECS에 배포
🧪 테스트
# 테스트 의존성 설치
pip install pytest pytest-asyncio pytest-cov
# 단위 테스트 실행
pytest tests/test_tools/
# 통합 테스트 실행
pytest tests/test_integration/
# 커버리지와 함께 실행
pytest --cov=. --cov-report=html
🤝 기여하기
기여를 환영합니다! 자세한 내용은 기여 가이드를 참조하세요.
- 저장소 포크
- 기능 브랜치 생성 (
git checkout -b feature/amazing-feature) - 변경사항 커밋 (
git commit -m 'Add amazing feature') - 브랜치에 푸시 (
git push origin feature/amazing-feature) - Pull Request 열기
📄 라이선스
이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.
📚 문서
- Wiki: 완전한 문서
- 설치 가이드: 단계별 설정
- 빠른 시작: 5분 설정
- API 참조: 완전한 API 문서
- 보안 가이드: 모범 사례
🆘 지원
- 이슈: GitHub Issues
- 토론: GitHub Discussions
🔄 변경 로그
v1.0.0 (2024-10-29)
- 🎉 초기 릴리즈
- ✅ 완전한 Discord API 통합
- ✅ MCP 표준 준수
- ✅ Docker 지원
- ✅ 고급 AI 기능
- ✅ 보안 강화
- ✅ 포괄적 문서화