mcp-discord

Name: MCP Discord
Author: goul4rt

가장 완벽한 오픈 소스 Discord용 MCP 서버.

License: MIT Node.js TypeScript GitHub stars

모든 MCP 클라이언트(Claude, Cursor, 커스텀 에이전트)가 Discord를 완전히 제어할 수 있도록 합니다(메시지, 관리, 채널, 역할 등). delfus.app의 프로덕션 환경에서 탄생했으며, 커뮤니티를 위해 오픈 소스로 공개되었습니다.

포르투갈어 (BR)

왜 mcp-discord인가요?

8개 카테고리, 30개 이상의 도구 — 서버, 채널, 메시지, 반응, 멤버, 역할, 관리 및 모니터링
듀얼 모드 — 독립형(자체 프로세스)으로 실행하거나 기존 discord.js 봇에 플러그인으로 통합
REST 전용 또는 게이트웨이 — 가벼운 REST 전용 모드 또는 실시간 기능을 위한 전체 WebSocket 게이트웨이 중 선택 가능
두 가지 전송 방식 — stdio(기본값, Claude Desktop / Claude Code용) 또는 Bearer 토큰 인증을 사용하는 HTTP
프로덕션 검증 — delfus.app에서 구축 및 운영 중

빠른 시작

사전 요구 사항

Node.js 18 이상
Discord 봇 토큰

설치

# Clone the repository
git clone https://github.com/goul4rt/mcp-discord.git
cd mcp-discord

# Install dependencies
npm install

# Build
npm run build

설정

cp .env.example .env

.env 파일을 편집하고 Discord 봇 토큰을 추가하세요:

DISCORD_TOKEN=your-bot-token-here

실행

# stdio transport (default — for MCP clients like Claude)
npm start

# HTTP transport (for remote/web clients)
npm run start:http

MCP 클라이언트 설정

Claude Desktop / Claude Code

MCP 설정 파일에 추가하세요:

{
    "mcpServers": {
        "discord": {
            "command": "node",
            "args": ["dist/standalone.js"],
            "cwd": "/path/to/mcp-discord",
            "env": {
                "DISCORD_TOKEN": "your-bot-token-here"
            }
        }
    }
}

게이트웨이 사용 시 (실시간 기능)

{
    "mcpServers": {
        "discord": {
            "command": "node",
            "args": ["dist/standalone.js"],
            "cwd": "/path/to/mcp-discord",
            "env": {
                "DISCORD_TOKEN": "your-bot-token-here",
                "DISCORD_USE_GATEWAY": "true"
            }
        }
    }
}

도구

서버 / 길드 (2개 도구)

도구	설명
`list_servers`	봇이 액세스할 수 있는 모든 Discord 서버 나열
`get_server_info`	특정 서버에 대한 상세 정보 가져오기

채널 (7개 도구)

도구	설명
`get_channels`	서버의 모든 채널 나열
`get_channel`	채널에 대한 상세 정보 가져오기
`create_channel`	텍스트, 음성, 카테고리, 공지, 포럼 또는 스테이지 채널 생성
`edit_channel`	채널 이름, 주제, NSFW, 슬로우 모드, 위치, 카테고리 편집
`delete_channel`	채널 영구 삭제
`create_thread`	채널 내 스레드 생성 (메시지에서 생성 가능)
`archive_thread`	스레드 보관

메시지 (8개 도구)

도구	설명
`send_message`	텍스트, 리치 임베드 및 답글이 포함된 메시지 전송
`read_messages`	페이지네이션을 사용하여 최근 메시지 읽기 (최대 100개)
`search_messages`	내용, 작성자 또는 채널별로 메시지 검색
`edit_message`	봇 메시지 편집
`delete_message`	단일 메시지 삭제
`delete_messages_bulk`	2~100개의 메시지 대량 삭제 (14일 이내)
`pin_message`	메시지 고정
`unpin_message`	메시지 고정 해제

반응 (2개 도구)

도구	설명
`add_reaction`	이모지 반응 추가 (유니코드 또는 커스텀)
`remove_reaction`	반응 제거

멤버 / 사용자 (4개 도구)

도구	설명
`list_members`	페이지네이션을 사용하여 서버 멤버 나열
`get_member`	상세 멤버 정보 가져오기 (역할, 별명, 가입일)
`get_user`	ID로 모든 Discord 사용자 정보 가져오기
`search_members`	사용자 이름 또는 별명으로 멤버 검색

역할 (4개 도구)

도구	설명
`list_roles`	권한, 색상 및 멤버 수가 포함된 모든 역할 나열
`create_role`	새 역할 생성
`add_role`	멤버에게 역할 추가
`remove_role`	멤버에게서 역할 제거

관리 (4개 도구)

도구	설명
`timeout_user`	사용자 일시적 뮤트 (최대 28일)
`kick_user`	서버에서 사용자 추방
`ban_user`	메시지 삭제 옵션과 함께 사용자 차단
`unban_user`	사용자 차단 해제

모니터링 (2개 도구)

도구	설명
`get_audit_log`	서버 감사 로그 보기 (차단, 추방, 변경 사항)
`check_mentions`	봇이나 사용자에 대한 최근 @멘션 찾기

아키텍처

┌─────────────────────────────────────────────────┐
│                  MCP Client                      │
│          (Claude, Cursor, custom)                │
└──────────────────┬──────────────────────────────┘
                   │ stdio or HTTP
┌──────────────────▼──────────────────────────────┐
│               MCP Server                         │
│         (transport + tool routing)                │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│            Tool Registry                         │
│         (30 tools, Zod validation)               │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│          DiscordProvider (interface)              │
├─────────────────────┬───────────────────────────┤
│ StandaloneProvider  │  IntegratedProvider        │
│ (own token + REST/  │  (uses host bot's          │
│  optional gateway)  │   existing connection)      │
└─────────────────────┴───────────────────────────┘
                   │
┌──────────────────▼──────────────────────────────┐
│              Discord API                         │
└─────────────────────────────────────────────────┘

공급자 추상화: MCP 도구는 discord.js를 직접 건드리지 않습니다. 두 가지 구현을 가진 DiscordProvider 인터페이스를 호출합니다:

StandaloneProvider — 봇 토큰을 사용하여 자체 연결을 생성합니다. 게이트웨이 옵션이 포함된 REST 우선 방식입니다. 별도의 프로세스로 실행할 때 사용하세요.
IntegratedProvider — 호스트 봇으로부터 기존 discord.js Client를 수신합니다. 오버헤드가 없으며 캐시와 게이트웨이를 공유합니다. 기존 봇에 임베드할 때 사용하세요.

통합 가이드

mcp-discord를 기존 discord.js 봇 내의 플러그 봇 내부의 플러그인으로 사용하려면:

import { IntegratedProvider, createMcpServer } from 'mcp-discord';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Your existing discord.js client
const provider = new IntegratedProvider({ client: myDiscordClient });
await provider.connect();

const server = createMcpServer({ provider });
const transport = new StdioServerTransport();
await server.connect(transport);

IntegratedProvider는 봇의 기존 게이트웨이 연결을 사용하므로 추가 WebSocket, 추가 인증, 추가 메모리가 필요하지 않습니다.

설정 참조

변수	필수	기본값	설명
`DISCORD_TOKEN`	예	—	Discord 봇 토큰
`DISCORD_USE_GATEWAY`	아니요	`false`	실시간 기능을 위해 Discord WebSocket 게이트웨이에 연결
`MCP_TRANSPORT`	아니요	`stdio`	전송 모드: `stdio` 또는 `http`
`MCP_PORT`	아니요	`3100`	HTTP 서버 포트 (`MCP_TRANSPORT=http`일 때만)
`MCP_AUTH_TOKEN`	아니요	—	HTTP 전송 인증을 위한 Bearer 토큰

기여

기여를 환영합니다! 개발 설정, 코드 스타일 및 새 도구 추가 방법은 CONTRIBUTING.md를 참조하세요.

라이선스

MIT

작성자

@goul4rt가 제작했습니다. delfus.app에서 탄생했으며 커뮤니티를 위해 오픈 소스로 공개되었습니다.

MCP Discord