Discord MCP

Discord 서버와 채널을 읽고, 명시적으로 허용한 경우에만 메시지를 보내는 로컬 Model Context Protocol 서버입니다.

• TypeScript + MCP SDK v1
• 로컬 stdio 전송
• Discord REST API v10 (Gateway 연결 불필요)
• 서버/채널 allowlist
• 기본 read-only
• 멘션 알림 강제 차단
• 자기 봇이 작성한 메시지만 수정/삭제

TypeScript 구현 하나를 npm, PyPI, OCI 이미지와 Claude Desktop MCPB로 배포합니다. PyPI 패키지도 서버를 Python으로 다시 구현하거나 실행할 때 npx @latest를 호출하지 않고, 릴리스와 함께 고정된 같은 JS 코드를 wheel 내부에서 실행합니다.

TypeScript source
  ├─ esbuild → bundle/discord-mcp.cjs
  │              ├─ npm (npx / pnpm / Yarn / bunx)
  │              ├─ PyPI wheel (uvx / pipx / pip launcher)
  │              ├─ GHCR image (Docker)
  │              └─ MCPB (Claude Desktop one-click bundle)
  └─ server.json → MCP Registry에서 npm / PyPI / OCI 좌표를 한 항목으로 연결

네 배포 산출물은 동일한 서버 번들을 사용하며, 번들에 실제 포함된 의존성의 라이선스 원문과 결정적인 CycloneDX 1.6 SBOM도 esbuild metafile에서 함께 생성합니다. 따라서 같은 릴리스 버전이 패키지 매니저별로 서로 다른 전이 의존성을 다시 해석하지 않습니다.

제공 기능

읽기 도구는 기본으로 노출됩니다.

DISCORD_ENABLE_WRITES=true일 때 다음 도구가 추가됩니다.

DISCORD_ENABLE_DELETES=true까지 설정하면 discord_delete_own_message가 추가됩니다. 삭제 호출에는 confirm: true도 필요합니다.

MCP resource도 함께 제공합니다.

• discord://bot
• discord://guilds
• discord://guilds/{guild_id}
• discord://guilds/{guild_id}/channels
• discord://channels/{channel_id}
• discord://channels/{channel_id}/messages/{message_id}

1. Discord 봇 준비

1. Discord Developer Portal에서 Application을 만들고 Bot 메뉴에서 봇을 생성합니다.
2. Bot Token을 발급합니다. 토큰은 비밀번호와 같으므로 코드나 Git에 넣지 마세요.
3. 일반 채널의 메시지 본문을 읽으려면 Bot 메뉴의 Message Content Intent를 활성화합니다. REST로 메시지를 읽을 때도 이 설정이 적용됩니다.
4. OAuth2 URL Generator에서 bot scope를 선택하고 테스트 서버에 초대합니다.

권장 최소 권한:

• 읽기: View Channels, Read Message History
• 메시지 전송도 사용할 때: Send Messages
• thread에 전송할 때: Send Messages in Threads
• voice channel의 텍스트 타임라인을 읽을 때: Connect

Administrator, Manage Messages, Mention Everyone 권한은 필요하지 않습니다. 채널별 permission overwrite가 서버 권한보다 우선하므로, 특정 채널이 보이지 않으면 해당 채널 권한도 확인하세요.

2. 설치

권장 런타임은 Node.js 22 이상입니다. 배포 채널에 따라 다음 명령을 사용할 수 있습니다. 재현 가능한 MCP 설정을 위해 latest 대신 정확한 버전을 고정하세요.

bunx는 npm 패키지 설치 프런트엔드로 지원합니다. Node shebang을 그대로 실행하며 Bun 자체 런타임을 강제하는 bunx --bun 모드는 지원 범위가 아닙니다.

전역 설치는 기존 discord-mcp 명령이 없는 격리된 환경에서만 다음처럼 사용할 수 있습니다.

npm install --global @hypark5540/discord-mcp@0.1.1
pip install hypark-discord-mcp==0.1.1
hypark-discord-mcp --version

npm과 Python 채널 모두 고유한 hypark-discord-mcp 명령 alias를 제공합니다. 제3자의 기존 npm/PyPI 패키지도 discord-mcp라는 전역 명령을 설치하므로, 전역 설치 과정 자체가 충돌할 수 있습니다. 평소에는 격리된 npx/uvx 실행을 권장하고, 전역으로 설치했다면 고유 alias를 사용하세요. Python 패키지는 Node를 내장하지 않으며, 필요하면 DISCORD_MCP_NODE=/path/to/node로 실행 파일을 지정할 수 있습니다.

Docker에서는 -i로 stdio를 유지하고 -t는 사용하지 않습니다.

docker run --rm -i \
  -e DISCORD_TOKEN \
  -e DISCORD_ENABLE_WRITES=false \
  ghcr.io/hypark5540/discord-mcp:0.1.1

3. 클라이언트 원터치 연결

Cursor

아래 공식 버튼은 정확히 고정된 npm 패키지를 stdio MCP 서버로 등록합니다. 실제 토큰은 링크에 들어 있지 않고 ${env:DISCORD_TOKEN}을 참조하므로, Cursor를 시작하는 환경에 먼저 안전하게 설정하세요.

PyPI처럼 cursor:// 링크를 제거하는 페이지에서 보고 있다면 GitHub README의 Cursor 섹션에서 버튼을 누르세요.

Claude Desktop

Claude Desktop용 discord-mcp-0.1.1.mcpb를 다운로드한 뒤 파일을 열면 설치 화면이 나타납니다. Discord Bot Token은 MCPB 안에 저장되지 않고, 설치 화면의 sensitive 입력을 통해 운영체제 keychain/credential manager에 보관됩니다. 같은 릴리스의 SHA-256 파일로 다운로드한 번들을 확인할 수 있습니다. GitHub CLI가 있으면 gh attestation verify --repo hypark5540/discord-mcp discord-mcp-0.1.1.mcpb로 릴리스 워크플로의 서명된 provenance도 검증할 수 있습니다.

Gemini CLI

Gemini CLI는 저장소의 공식 Extension 매니페스트를 직접 설치할 수 있습니다.

gemini extensions install https://github.com/hypark5540/discord-mcp --ref=v0.1.1

설치 중 Token 설정은 sensitive: true이므로 시스템 keychain에 저장됩니다. 확인 화면을 건너뛰는 옵션은 사용하지 마세요.

ChatGPT Desktop, Codex와 나머지 클라이언트

정확한 설정은 클라이언트별 가이드, keychain·환경변수와 토큰 회전은 비밀 관리 가이드에 있습니다. ChatGPT, Claude, Cursor, Gemini 같은 에이전트에게 설치 자체를 맡길 때는 AI 설치 프롬프트를 그대로 사용할 수 있습니다.

4. 소스에서 실행

Node.js 22 이상이 필요합니다.

npm run deps:locked
cp .env.example .env
npm run build

deps:locked는 모든 의존성 설치 스크립트를 차단한 뒤, 잠금·검토된 esbuild@0.28.1만 명시적으로 재빌드합니다.

.env에서 최소한 토큰을 설정합니다.

DISCORD_TOKEN=your-bot-token
DISCORD_ENABLE_WRITES=false
DISCORD_ENABLE_DELETES=false
DISCORD_ALLOW_UNRESTRICTED_WRITES=false

직접 확인하려면 다음 명령을 실행할 수 있습니다.

npm start

stdio는 MCP 프레임 전용이므로 실행 후 일반 프롬프트가 나타나지 않는 것이 정상입니다. 상태 로그는 stderr에만 기록됩니다.

5. MCP 클라이언트 연결

npm 패키지를 실행하도록 등록하는 예시입니다. 클라이언트마다 설정 파일 위치는 다르지만 설정 형태는 대체로 다음과 같습니다.

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@hypark5540/discord-mcp@0.1.1"],
      "env": {
        "DISCORD_TOKEN": "<use-the-client-secret-store>",
        "DISCORD_ENABLE_WRITES": "false",
        "DISCORD_ALLOW_UNRESTRICTED_WRITES": "false",
        "DISCORD_ALLOWED_GUILD_IDS": "123456789012345678",
        "DISCORD_ALLOWED_CHANNEL_IDS": "234567890123456789"
      }
    }
  }
}

uvx를 선호하면 실행 부분만 다음처럼 바꿀 수 있습니다.

{
  "command": "uvx",
  "args": ["--from", "hypark-discord-mcp==0.1.1", "discord-mcp"]
}

소스 빌드를 직접 연결할 때는 기존처럼 command를 node, args를 ["/absolute/path/to/discord-mcp/dist/index.js"]로 지정합니다.

MCP 설정의 env가 .env보다 우선합니다. 다른 디렉터리에서 서버가 실행될 수 있으므로 MCP 클라이언트에서는 env에 토큰을 전달하는 방식을 권장합니다. 클라이언트가 native keychain이나 환경변수 참조를 지원하면 위 자리에는 토큰 원문을 저장하지 말고 그 기능을 우선 사용하세요.

환경변수

서버 ID와 채널 ID는 Discord의 Developer Mode를 켠 뒤 Copy ID로 얻을 수 있습니다. 두 allowlist를 모두 설정하면 교집합만 허용됩니다. DM과 그룹 DM은 항상 거부됩니다. 읽기 모드에서는 allowlist가 모두 비어 있으면 봇이 접근할 수 있는 모든 guild channel을 읽을 수 있습니다. 쓰기 모드는 allowlist를 하나 이상 요구하며, 이 검사를 해제하려면 DISCORD_ALLOW_UNRESTRICTED_WRITES=true를 별도로 명시해야 합니다.

안전 설계