Discord MCP

Discord를 도구로 노출하는 원격 MCP 서버(Streamable HTTP)로, Claude → 설정 → 커넥터 → Add custom connector에서 연결하도록 설계되었습니다 (https://claude.ai/ask-your-org/setup, Custom 옵션).

노출되는 기능

discord.py를 사용하는 Discord API 도구:

• list_guilds — 봇이 접근할 수 있는 서버.

• list_channels(guild_id) — 서버의 채널.

• list_members(guild_id, limit) — 서버의 멤버.

• list_roles(guild_id) — 서버의 역할.

• send_message(channel_id, content) — 메시지 보내기.

• read_messages(channel_id, limit, before_message_id) — 기록 읽기.

• create_thread(channel_id, name, message_id?, auto_archive_minutes) — 스레드 생성.

• add_reaction(channel_id, message_id, emoji) / remove_reaction(...) — 반응.

• add_role_to_member(guild_id, user_id, role_id) / remove_role_from_member(...) — 역할.

모든 ID(서버, 채널, 메시지, 사용자, 역할)는 Discord의 스노우플레이크(snowflake)이며 문자열 형태입니다.

Related MCP server: Discord MCP Server

1. Discord 봇 만들기

1. Discord Developer Portal에 접속하여 New Application을 만듭니다.

2. Bot에서 봇을 만들고 Token을 복사합니다(Reset Token 버튼). 이 값이 DISCORD_BOT_TOKEN입니다.

3. 같은 섹션의 Bot → Privileged Gateway Intents에서 다음을 활성화합니다:

   • Server Members Intent (list_members 및 역할 관리에 필요).

   • Message Content Intent (read_messages에서 메시지 내용을 읽는 데 필요).

4. OAuth2 → URL Generator에서:

   • Scopes: bot.

   • Bot Permissions (사용 목적에 맞게 조정): View Channels, Send Messages, Read Message History, Create Public Threads, Add Reactions, Manage Roles.

   • 생성된 URL을 열고 봇을 사용할 서버로 초대합니다.

5. add_role_to_member / remove_role_from_member를 사용하려면 봇의 역할이 할당하려는 역할보다 위에(더 높은 계층) 있어야 합니다.

2. 환경 변수 설정

.env.example을 .env로 복사하고 다음을 입력합니다:

cp .env.example .env

• DISCORD_BOT_TOKEN: 이전 단계의 토큰.

• MCP_AUTH_TOKEN: 서버를 보호하기 위한 자체 비밀 키입니다. python -c "import secrets; print(secrets.token_urlsafe(32))"로 생성하세요. Claude.ai는 각 요청에서 Authorization: Bearer <token> 헤더로 이 값을 전송합니다(4단계 참조).

• 나머지 변수는 합리적인 기본값이 있습니다 — .env.example의 주석을 참조하세요.

3. 서버 실행

로컬 (Docker 없이)

python -m venv .venv && source .venv/bin/activate
pip install -e .
python -m discord_mcp   # o: discord-mcp

기본적으로 http://0.0.0.0:8000/mcp에서 수신 대기합니다.

Docker 사용

docker compose up --build

또는 수동으로:

docker build -t discord-mcp .
docker run --env-file .env -p 8000:8000 discord-mcp

배포 (Render / Railway / Fly.io / 모든 VPS)

이 이미지는 자체 영구 상태가 없는 일반 HTTP 컨테이너입니다(봇의 상태는 메모리와 Discord에 저장됨). 따라서 Docker를 지원하는 모든 프로바이더에서 실행할 수 있습니다:

• 2단계의 환경 변수를 프로바이더 패널에 설정합니다.

• 포트 8000(또는 PORT에 정의한 포트)을 HTTPS로 노출합니다 — Claude.ai에서는 MCP 서버가 https://로 접근 가능해야 합니다.

• 배포 후 커넥터 URL은 https://<tu-dominio>/mcp가 됩니다.

프로덕션에서 DNS 리바인딩 공격에 대한 보호를 강화하려면 ALLOWED_HOSTS(서버의 공개 호스트 이름)와 ALLOWED_ORIGINS (예: https://claude.ai)를 설정하세요.

4. claude.ai에서 커스텀 커넥터로 연결

1. https://claude.ai/ask-your-org/setup(또는 설정 → 커넥터)에 접속하여 Add custom connector / Custom을 선택합니다.

2. Name: Discord(또는 원하는 이름).

3. URL: https://<tu-dominio>/mcp.

4. Request headers / Advanced settings에서 다음을 추가합니다:

   • Header: Authorization

   • 값: Bearer <el mismo valor que pusiste en MCP_AUTH_TOKEN>

5. 저장한 후 Claude에게 *"사용 가능한 Discord 서버 목록을 보여줘"*라고 요청하여 테스트합니다 — list_guilds를 호출해야 합니다.

인증을 사용하지 않으려면(빠른 테스트 전용, 프로덕션에서는 절대 안 됨) MCP_AUTH_TOKEN을 비워 두고 헤더를 생략하세요.

개발

pip install -e ".[dev]"
pytest

테스트는 설정, 인증 미들웨어, 그리고 실제 Discord 연결이 필요 없는 DiscordService 로직을 다룹니다(실제 Discord API에 대한 통합 테스트는 없습니다).

아키텍처 참고 사항

• discord.py 봇은 ASGI 서버(Starlette/uvicorn)와 동일한 이벤트 루프에서 백그라운드 작업으로 실행됩니다. 앱의 lifespan과 함께 시작되고 종료됩니다 (src/discord_mcp/server.py).

• MCP 서버는 공식 mcp SDK의 mcp.server.MCPServer를 사용하는 Streamable HTTP 전송 방식을 사용합니다. 이는 Claude 커스텀 커넥터가 지원하는 원격 전송 방식입니다.

• 인증은 커스텀 ASGI 미들웨어(auth_middleware.py)가 검증하는 정적 베어러 토큰입니다. 커스텀 커넥터의 "Request headers" 메커니즘을 위해 설계되었으며, 완전한 OAuth 흐름은 구현하지 않습니다.