Discord MCP

Discord MCP

Discord サーバーとチャンネルを読み取り、明示的に許可した場合に限りメッセージを送信する、ローカルの Model Context Protocol サーバーです。

• TypeScript + MCP SDK v1
• ローカルの stdio トランスポート
• Discord REST API v10（Gateway 接続不要）
• サーバー／チャンネルの許可リスト
• デフォルトで読み取り専用
• メンション通知を強制的にブロック
• 自分のボットが作成したメッセージのみ編集／削除

1つの 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 좌표를 한 항목으로 연결

4つの配布物は同じサーバーバンドルを使用し、バンドルに実際に含まれる依存関係のライセンス原文と、決定的な CycloneDX 1.6 SBOM も esbuild metafile から生成します。そのため、同じリリースバージョンでも、パッケージマネージャーごとに異なる推移的依存関係を再解決することはありません。

提供機能

読み取りツールはデフォルトで公開されます。

ツール	説明
discord_get_bot	ボットアカウントと現在の安全設定を確認
discord_list_guilds	ボットが参加しているサーバーの一覧を取得
discord_get_guild	サーバーのメタデータを取得
discord_list_channels	サーバーのチャンネル一覧を取得
discord_get_channel	チャンネルのメタデータを取得
discord_get_messages	チャンネルのメッセージを最大100件取得
discord_get_message	単一のメッセージを取得

DISCORD_ENABLE_WRITES=true の場合、次のツールが追加されます。

ツール	説明
discord_send_message	通常のメッセージまたは返信を送信
discord_edit_own_message	このボットが直接作成したメッセージのみ編集

DISCORD_ENABLE_DELETES=true も設定すると、discord_delete_own_message が追加されます。削除の呼び出しには confirm: true も必要です。

MCP リソースも提供します。

• 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 でアプリケーションを作成し、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 ではなく正確なバージョンを固定してください。

チャネル	実行コマンド	必要なランタイム
npm / npx	npx -y @hypark5540/[email protected]	Node.js 22+
pnpm	pnpm dlx --package=@hypark5540/[email protected] discord-mcp	Node.js 22+
Yarn	yarn dlx -p @hypark5540/[email protected] discord-mcp	Node.js 22+
Bun パッケージランナー	bunx --package @hypark5540/[email protected] discord-mcp	Bun + Node.js 22+
PyPI / uvx	uvx --from hypark-discord-mcp==0.1.1 discord-mcp	Python 3.9+ + Node.js 22+
PyPI / pipx	pipx run --spec hypark-discord-mcp==0.1.1 discord-mcp	Python 3.9+ + Node.js 22+
Docker / GHCR	以下の docker run の例	Docker
Claude Desktop MCPB	GitHub Release の discord-mcp-0.1.1.mcpb	Claude Desktop
MCP Registry	io.github.hypark5540/discord-mcp	クライアントが選択したパッケージによります

bunx は npm パッケージのインストールフロントエンドとしてサポートしています。Node の shebang をそのまま実行するもので、Bun 自体のランタイムを強制する bunx --bun モードはサポート対象外です。

グローバルインストールは、既存の discord-mcp コマンドがない隔離された環境でのみ、次のように使用できます。

npm install --global @hypark5540/[email protected]
pip install hypark-discord-mcp==0.1.1
hypark-discord-mcp --version

npm と Python の両チャネルでは、固有の hypark-discord-mcp コマンドエイリアスを提供しています。サードパーティの既存 npm/PyPI パッケージも discord-mcp というグローバルコマンドをインストールするため、グローバルインストール時に競合が発生する可能性があります。通常は隔離された npx/uvx での実行を推奨します。グローバルにインストールした場合は、固有のエイリアスを使用してください。 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 入力欄を通じて、OS のキーチェーン／資格情報マネージャーに保存されます。同じリリースの 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 が指定されているため、システムのキーチェーンに保存されます。確認画面を省略するオプションは使用しないでください。

ChatGPT Desktop、Codex、その他のクライアント

クライアント	推奨接続方法	シークレットの受け渡し
ChatGPT Desktop / Codex CLI・IDE	共通の ~/.codex/config.toml local stdio 設定	env_vars = ["DISCORD_TOKEN"]
Claude Code / その他の stdio MCP	バージョンを固定した npx 設定	クライアントのシークレットストア
ChatGPT Web	local stdio は未対応	別途ホスト型の remote MCP が必要

詳しい設定はクライアント別ガイドに、キーチェーン・環境変数とトークンのローテーションについては シークレット管理ガイドに記載されています。ChatGPT、Claude、Cursor、Gemini などの エージェントにインストール自体を任せる場合は、AI インストールプロンプトをそのまま 使用できます。

4. ソースから実行

Node.js 22 以上が必要です。

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

deps:locked はすべての依存関係インストールスクリプトをブロックしたうえで、ロックされレビュー済みの [email protected] のみを明示的に再ビルドします。

.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/[email protected]"],
      "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 や環境変数参照に対応している場合は、上記の箇所にトークンの値を 保存せず、そうした機能を優先して使用してください。

環境変数

変数	デフォルト値	説明
DISCORD_TOKEN	必須	Discord Bot Token
DISCORD_BOT_TOKEN	-	DISCORD_TOKEN の互換 alias
DISCORD_ENABLE_WRITES	false	送信／編集ツールを登録
DISCORD_ENABLE_DELETES	false	削除ツールを登録。writes も true である必要があります
DISCORD_ALLOW_UNRESTRICTED_WRITES	false	allowlist のない全チャンネルへの書き込みを意図的に許可
DISCORD_ALLOWED_GUILD_IDS	空	カンマ区切りのサーバー ID。空の場合、ボットが参照できるすべてのサーバーを許可
DISCORD_ALLOWED_CHANNEL_IDS	空	カンマ区切りのチャンネル ID。空の場合、許可されたサーバー内のすべての guild channel を許可
DISCORD_MAX_RESPONSE_CHARS	50000	シリアライズされた tool/resource の結果の最大文字数（1000～200000）
DISCORD_MCP_NODE	PATH 上の node	PyPI ランチャーで使用する Node.js 実行ファイルのパス

サーバー ID とチャンネル ID は、Discord の Developer Mode を有効にした後、Copy ID で取得できます。両方の allowlist を設定すると、共通部分のみが許可されます。DM とグループ DM は 常に拒否されます。読み取りモードでは、allowlist が両方とも空の場合、ボットがアクセスできる すべての guild channel を読み取れます。書き込みモードでは、少なくとも 1 つの allowlist が 必要です。このチェックを解除するには、DISCORD_ALLOW_UNRESTRICTED_WRITES=true を別途 明示する必要があります。

安全設計

• Bot Token のみを使用し、ユーザートークン／self-bot には対応しません。
• 任意の Discord API endpoint を呼び出す汎用ツールはありません。
• 書き込みツールと削除ツールは、起動時に環境変数で個別に有効化する必要があります。
• すべての送信／編集リクエストで allowed_mentions: { parse: [] } を強制するため、 @everyone、ロール、ユーザーの文字列が含まれていても通知は送信されません。
• 送信には Discord nonce による重複防止を適用します。
• 編集／削除の前に作成者 ID を確認し、webhook メッセージや他のユーザーのメッセージは 拒否します。
• Discord メッセージは信頼できない外部データとして扱い、応答をローカルに 保存したりキャッシュしたりしません。
• 別のチャンネルを参照する Discord の返信／スレッドメタデータは本文を除去し、 allowlist の境界を迂回できないようにします。
• API エラーは、トークン、リクエストヘッダー、元のレスポンス body を公開しない文面に変換します。

Discord の guild channel 一覧 API は、ボットが実際には View Channel 権限を持たない チャンネルの名前や topic などのメタデータも返す場合があります。機密性の高いサーバーでは、 guild allowlist だけでなく channel allowlist も設定してください。チャンネル一覧には 通常のチャンネルと現在の active thread が含まれます。archived thread は ID を指定して直接 取得する必要があります。

allowlist なしでも実行できますが、実際の使用環境では、ボット専用のテストサーバーと DISCORD_ALLOWED_GUILD_IDS、DISCORD_ALLOWED_CHANNEL_IDS を併用することを 推奨します。

開発

npm run dev
npm run typecheck
npm test
npm run build
npm run check
npm run build:mcpb
npm run verify:mcpb
npm run build:pypi

テストでは、実際に Discord を呼び出さずに次の項目を検証します。

Vitest は、import 可能な src モジュールについて、statements、branches、functions、lines の ファイルごとのカバレッジ 100% を必須とします。薄い process bootstrap である src/index.ts は、カバレッジ計算の 代わりに、コンパイル結果とバンドルに対する実際の stdio handshake で検証します。Codecov の project/patch ステータスも、許容誤差なしで 100% を要求します。

• MCP の initialize、tool/resource の一覧表示と呼び出し
• feature flag に応じた書き込み／削除ツールの公開
• Snowflake、pagination cursor、メッセージ長の検証
• guild/channel allowlist による事前ブロック
• 他人のメッセージの編集拒否と削除確認
• メンションのブロックと nonce の適用
• 最大応答サイズの制限
• コンパイル結果と PyPI 用バンドルに対する実際の MCP initialize/tools handshake
• Claude MCPB の公式 CLI による pack/unpack/manifest の検証、決定的なバイト列と stdio handshake
• npm、PyPI、MCP Registry、OCI メタデータのバージョン一致

CI では Node.js 22/24 で検査し、生成された npm tarball と Python wheel をそれぞれクリーンな 環境にインストールした後、stdio handshake を再実行します。Python wheel ランチャーは Ubuntu/Windows の Python 3.9/3.14 でも個別に確認します。MCPB も独立して 2 回 ビルドし、バイト列が同一であることを確認してから、公式 CLI で再度解凍したサーバーを実行します。 リリース準備と OIDC Trusted Publishing の設定については、 docs/releasing.mdを 参照してください。

プライバシーとセキュリティ報告

このサーバーは telemetry を送信せず、Discord の応答を別途保存することもありません。ローカルの MCP クライアントからのリクエストに必要な Discord REST 呼び出しのみを実行します。データフローと 保存範囲についてはPRIVACY.md、脆弱性を非公開で報告する方法については SECURITY.mdを確認してください。公開 issue やログには Bot Token を絶対に 含めないでください。

문제 해결

• 401 / 토큰 거부: Bot 메뉴에서 토큰을 재발급하고 DISCORD_TOKEN을 갱신하세요. Bot 접두사는 직접 붙이지 않습니다.
• 403 / 권한 없음: 채널의 View Channel, Read Message History, 필요 시 Send Messages를 확인하세요.
• 메시지 내용이 비어 있음: Developer Portal에서 Message Content Intent를 활성화했는지 확인하세요.
• 쓰기 도구가 목록에 없음: MCP 클라이언트 프로세스의 DISCORD_ENABLE_WRITES가 문자열 true인지 확인하고 클라이언트를 재시작하세요.
• allowlist 오류: ID는 이름이나 URL이 아니라 17~20자리 숫자 문자열이어야 합니다.

Discord의 공식 권한·intent·rate limit 세부사항은 OAuth2 and Permissions, Gateway Intents, Message Resource, Rate Limits을 참고하세요.