@devli13/mcp-discord

Discord용 MCP 서버입니다. Claude Code, Paperclip 에이전트, Gemini CLI 또는 모든 MCP 호환 클라이언트에서 메시지 전송, 중재, 채널 관리, 서버 검사를 수행하세요.

순수 REST 래퍼입니다. 게이트웨이도 없고 데이터베이스도 없습니다. 26개의 잘 문서화된 도구로 구성된 Discord v10 API이며, 경로별 속도 제한 및 구조화된 오류 결과를 제공합니다.

이유

Discord API는 방대하며 원시 curl을 통해 호출할 때 에이전트가 사용하기 어렵습니다. 에이전트는 속도 제한에 걸리거나, 429 오류를 잘못 처리하거나, 감사 로그 사유를 누락하거나, 페이지네이션 커서를 잊어버리곤 합니다. 이 MCP는 이러한 문제를 해결하여 에이전트가 "스팸 메시지 삭제", "#mod-log에 일일 요약 게시", "@user를 1시간 동안 타임아웃"과 같은 의도에 집중할 수 있도록 합니다.

사람이 사용하기에도 좋습니다. Claude Code에 연결하면 "내 Discord #dev 채널의 최근 50개 메시지 요약해줘"라고 말하기만 하면 Claude가 즉시 수행합니다.

Related MCP server: Discord Bridge MCP Server

설치

npm install -g @devli13/mcp-discord

또는 npx 사용 (설치 불필요):

DISCORD_BOT_TOKEN=<your-token> npx -y @devli13/mcp-discord

설정

1. Discord 봇 생성

1. https://discord.com/developers/applications로 이동 → New Application 클릭

2. 애플리케이션에 Bot 추가

3. 봇 토큰 복사 — 이것이 DISCORD_BOT_TOKEN입니다.

4. OAuth2 URL 생성기(범위: bot)를 사용하여 봇을 서버에 초대하세요. MCP가 수행해야 할 작업에 따라 권한을 선택하세요(예: 삭제를 위한 메시지 관리, 타임아웃을 위한 멤버 중재).

2. MCP 클라이언트에 연결

Claude Code:

claude mcp add discord \
  --env DISCORD_BOT_TOKEN=<your-token> \
  -- npx -y @devli13/mcp-discord

Paperclip mcp-gateway (.mcp.json):

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@devli13/mcp-discord"],
      "env": {
        "DISCORD_BOT_TOKEN": "<your-token>"
      }
    }
  }
}

Gemini CLI (~/.gemini/config.json):

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@devli13/mcp-discord"]
    }
  }
}

3. (선택 사항) 권한 있는 인텐트 활성화

서버 멤버 목록을 가져오거나(discord_list_members) 인바운드 이벤트를 위한 컴패니언 플러그인과 함께 이 MCP를 사용하려면, 봇의 개발자 포털 설정에서 Server Members Intent 및 Message Content Intent를 활성화하세요. 대부분의 MCP 작업에는 필요하지 않으며 특정 엔드포인트에만 필요합니다.

도구 참조

모든 도구는 discord_* 접두사가 붙으며 JSON 블록(성공 시) 또는 형식화된 오류 메시지(실패 시)를 반환합니다. 오류를 던지지 않으며 모든 도구는 사용 가능한 문자열 결과를 반환합니다.

메시지 (8)

반응 (3)

채널 및 스레드 (5)

중재 (6)

서버 정보 (4)

제외된 기능 (의도적):

• ban/unban — 의도적입니다. Discord UI를 사용하세요. 되돌릴 수 없는 작업은 에이전트 호출 한 번으로 수행되어서는 안 됩니다.

• 채널 생성/삭제/수정 — 영향 범위가 크므로 UI를 사용하세요.

• Webhook CRUD — 대부분의 에이전트 흐름에 필요하지 않으며 향후 릴리스에 추가될 수 있습니다.

• 음성 작업, 스티커/이모지 관리 — v0.1 범위 밖입니다.

예시: Claude Code를 통한 채널 요약

User: Summarize the last 30 messages in the #dev channel of my Discord server, guild ID 1234...

Claude (calls discord_list_channels → finds #dev → calls discord_list_messages → writes summary)

예시: Paperclip 에이전트 일일 요약

// From an agent's prompt:
"Post the daily digest to channel 1234. Summarize the last 24h of activity
using discord_list_messages with limit=100, then format as an embed via
discord_send_message."

오류 처리

모든 도구는 사용 가능한 텍스트 결과를 반환합니다. 오류 발생 시:

Error (DISCORD_50001, HTTP 403): Missing Access
Details: [...]
(This error is transient and may succeed on retry.)

MCP는 이미 429(속도 제한) 및 5xx(서버 오류)에 대해 지수 백오프를 사용하여 내부적으로 재시도를 처리합니다.

속도 제한

Discord에는 두 가지 속도 제한 계층이 있습니다:

1. 경로별 — 각 API 엔드포인트는 독립적인 버킷을 가집니다. 이 MCP는 429 오류를 방지하기 위해 (메서드 + 경로 템플릿)별로 요청을 직렬화합니다.

2. 글로벌 — 봇당, 모든 엔드포인트에 걸쳐 적용됩니다. MCP는 전역적으로 Retry-After 헤더를 준수합니다.

이 부분은 신경 쓸 필요가 없습니다. 만약 전역 제한에 반복적으로 도달한다면, 사람이 개입해야 할 작업을 수행하고 있을 가능성이 높습니다.

보안

• 봇 토큰을 절대 커밋하지 마세요. 이 MCP는 시작 시 DISCORD_BOT_TOKEN 환경 변수에서 토큰을 읽습니다.

• 최소 권한 초대 URL을 사용하세요. 메시지 관리만 필요하다면 봇에게 관리자 권한을 주지 마세요.

• 감사 로그 사유 — 모든 중재 도구는 Discord 감사 로그에 표시되는 reason 인수를 허용합니다. 이를 활용하세요.

개발

git clone https://github.com/devli13/mcp-discord.git
cd mcp-discord
npm install
npm test           # smoke tests (no live Discord calls)
npm run lint       # syntax check all files
npm start          # boot server over stdio (needs DISCORD_BOT_TOKEN)

컴패니언 프로젝트 — 인바운드 이벤트

이 MCP는 아웃바운드 REST 호출(전송, 삭제, 중재)을 처리합니다. Discord 게이트웨이 WebSocket을 유지하지 않으므로 인바운드 이벤트(사용자가 봇을 @멘션, DM, 새 멤버 가입 등)에 반응할 수 없습니다.

Paperclip 설정에서 인바운드 Discord 이벤트를 처리하려면 @devli13/paperclip-plugin-discord를 사용하세요. 이는 @mvanhorn/paperclip-plugin-discord의 포크 버전으로, 자유 형식 @멘션 라우팅, DM 지원, 컨텍스트별 직렬화된 메시지 큐, 다운타임 멘션 백필 기능을 제공합니다.

두 프로젝트는 함께 작동하도록 설계되었습니다. 플러그인이 이벤트를 수신하여 에이전트를 호출하고, 에이전트는 이 MCP를 사용하여 응답하고 중재합니다. 설정에 따라 하나 또는 둘 다 사용하세요.

저작자 표시

ATTRIBUTION.md를 참조하세요. 요약하자면, @mvanhorn의 paperclip-plugin-discord 포크와 함께 구축되었으며, 해당 프로젝트의 게이트웨이 처리 방식이 이 설계 패턴에 영감을 주었습니다.

라이선스

MIT — LICENSE를 참조하세요.