Discord ↔ Claude Team 연동용 MCP 서버

Discord 봇을 MCP(Model Context Protocol) 서버로 감싸서, Claude Team plan의 Custom Connector로 등록해 사용하는 예제입니다.

Claude 채팅에서 "우리 팀 #dev-log 채널 최근 메시지 요약해줘", "#general에 '배포 완료' 메시지 보내줘" 같은 요청을 할 수 있게 됩니다.

⚠️ 중요한 한계: 이 연동은 "Claude 채팅을 열고 물어볼 때만" 동작합니다. Discord에 새 메시지가 올라올 때 Claude가 자동으로 반응하는 것(24시간 감시봇)은 이 구조로는 안 됩니다. 그런 자동 응답이 필요하면 별도의 상시 실행 Discord 봇을 만들어 Claude API를 직접 호출하는 방식(이 문서 범위 밖)이 필요합니다.

1. Discord 봇 생성

1. https://discord.com/developers/applications 접속 → New Application

2. 왼쪽 메뉴 Bot → Add Bot

3. Privileged Gateway Intents에서 Message Content Intent 켜기 (필수)

4. Reset Token 클릭 → 토큰 복사 (.env의 DISCORD_BOT_TOKEN에 사용, 절대 외부 노출 금지)

5. 왼쪽 메뉴 OAuth2 → URL Generator

   • Scopes: bot

   • Bot Permissions: View Channels, Send Messages, Read Message History

   • 생성된 URL로 접속해서 봇을 원하는 서버(길드)에 초대

Related MCP server: Discord Bridge MCP Server

2. 로컬에서 실행해보기

cd discord-mcp-server
cp .env.example .env
# .env 파일 열어서 DISCORD_BOT_TOKEN, MCP_AUTH_TOKEN 채워넣기
npm install
npm start

정상 실행되면:

[discord] logged in as YourBotName#1234
[server] MCP server listening on port 3000

로컬 테스트 (선택)

MCP Inspector로 도구가 잘 동작하는지 확인:

npx @modelcontextprotocol/inspector

Transport type을 Streamable HTTP로 선택하고 http://localhost:3000/mcp 입력, Authorization 헤더에 Bearer <MCP_AUTH_TOKEN> 추가 후 list_discord_guilds 도구 호출.

3. 외부에서 접근 가능하도록 배포 (필수)

Claude Team의 Custom Connector는 공개 HTTPS 주소만 등록할 수 있습니다 (로컬 http://localhost나 사설 IP는 불가). 아래 중 하나를 선택하세요.

옵션 A. 빠른 테스트용 — Cloudflare Tunnel / ngrok

# ngrok 예시
ngrok http 3000

발급된 https://xxxx.ngrok-free.app 주소를 사용 (무료 플랜은 재시작마다 주소가 바뀜 → 팀 상용에는 부적합, 데모/테스트용).

옵션 B. 실제 운영용 — 클라우드 배포 (권장)

Render, Fly.io, Railway, 자체 VPS + Docker 등 Node.js를 상시 실행할 수 있는 곳이면 어디든 가능합니다. 예시 (Render 기준):

1. 이 프로젝트를 GitHub 저장소에 push

2. Render 대시보드 → New Web Service → 저장소 연결

3. Build Command: npm install

4. Start Command: npm start

5. Environment Variables에 DISCORD_BOT_TOKEN, MCP_AUTH_TOKEN 등록

6. 배포 완료 후 발급되는 https://your-app.onrender.com 확인

배포 후 https://your-app.onrender.com/healthz가 {"ok": true}를 반환하는지 확인하세요.

4. Claude Team에 Custom Connector로 등록

1. Claude.ai 로그인 → 조직 Settings → Connectors

2. Add custom connector 클릭

3. 아래 정보 입력:

   • Name: Discord 팀 브릿지 (원하는 이름)

   • URL: https://your-app.onrender.com/mcp

   • 인증 방식 UI가 제공되면 Authorization 헤더에 Bearer <MCP_AUTH_TOKEN> 등록 (UI에 커스텀 헤더 입력란이 없다면, 사내 배포 전용 URL로 제한하거나 리버스 프록시 앞단에서 IP 화이트리스트를 거는 방식으로 보완하세요. 이 부분은 Claude 웹 UI 업데이트에 따라 달라질 수 있으니 실제 설정 화면에서 제공되는 인증 옵션을 확인하시기 바랍니다.)

4. 저장 후 새 채팅에서 커넥터를 켜고 테스트:

   "Discord 서버 목록 보여줘" → list_discord_guilds 호출 확인 "#general 채널 최근 메시지 10개 보여줘" → read_discord_messages 호출 확인

5. 조직 지침에 반영할 것

• MCP_AUTH_TOKEN은 팀 비밀번호 관리 도구(1Password, Vault 등)에 보관, 코드/저장소에 커밋 금지

• 봇 권한은 필요한 채널에만 부여 (전체 서버 관리 권한 X)

• 이 커넥터를 조직 전체에 배포하기 전에 보안팀 검토: 어떤 채널까지 읽기/쓰기가 가능한지 범위 명시

• 민감 채널(인사/재무 등)은 봇 초대에서 제외

파일 구조

discord-mcp-server/
├── package.json
├── .env.example
├── README.md
└── src/
    ├── server.js       # Express + MCP Streamable HTTP 엔드포인트
    ├── tools.js        # Claude에 노출되는 MCP 도구 정의
    └── discordClient.js # discord.js 봇 클라이언트 및 헬퍼 함수