discord-mcp

MCP server that wraps a subset of the Discord REST API v10 using a bot token.

Security

• Never commit the bot token. Pass DISCORD_BOT_TOKEN only via your MCP client env block (see examples/).

• If a token was pasted into chat or committed anywhere, reset it in the Discord Developer Portal and use the new token locally.

Tools

Gateway intents (Presence, Server Members, Message Content) apply to the Gateway websocket. This MCP uses HTTP only; channel permissions still apply (e.g. Read Message History, Send Messages).

OpenClaw 公式の Discord（推奨）

OpenClaw と Discord をつなぐ正式な方法は、Gateway の channels.discord です。Bot トークンと openclaw config patch だけで Gateway が Discord に接続し、DM・サーバーでエージェントが応答します。手順は Discord — OpenClaw をそのまま実行してください。サンプルパッチは ../openclaw-mcp/examples/discord_channel.patch.json5 を参照。

• 同じ DISCORD_BOT_TOKEN で、下記の reply-bot（別プロセス）と同時に動かさないでください。WebSocket が二重になり競合します。

• HTTP の /v1/chat/completions 経由で返したい場合だけ、従来どおり reply-bot を使います（別経路）。

公式 Discord のみ使う: VM から discord-mcp（reply-bot）を削除する

OpenClaw の channels.discord だけ運用するなら、ゲスト上の clone + Docker / reply-bot は不要です。次で止めて消して構いません（パスは環境に合わせて読み替え）。

# ゲスト SSH 内
cd /root/discord-mcp   # または clone したディレクトリ（例: ~/discord-mcp）
COMPOSE_PROFILES=prod docker compose down
docker rm -f discord-reply-bot 2>/dev/null || true
docker rmi discord-reply-bot:latest 2>/dev/null || true
cd .. && rm -rf discord-mcp

OpenClaw Gateway（openclaw gateway / systemd）はそのまま。DISCORD_BOT_TOKEN は Gateway の環境（例: ~/.openclaw/.env）に残し、公式手順の config patch だけで Discord に接続します。

Reply bot（補助: HTTP で OpenClaw に転送）

The MCP alone cannot listen for messages. For DMs and @mentions (and replies to the bot when Discord fills the reference), run the optional Gateway bot:

1. In the Developer Portal → your app → Bot, enable Message Content Intent (Privileged Gateway Intents).

2. Install extras and start the process (keep this terminal open, or run under tmux / a process manager):

cd projects/discord-mcp
source .venv/bin/activate
pip install -e ".[reply-bot]"
export DISCORD_BOT_TOKEN='…'   # same token as MCP
python -m discord_mcp.reply_bot
# or: discord-reply-bot

uvx のデフォルトでは reply-bot 用の discord.py は入りません。リポジトリを clone しない場合は例えば次でも可です。

pip install "discord-mcp[reply-bot] @ git+https://github.com/taka392/discord-mcp.git"
DISCORD_BOT_TOKEN='…' discord-reply-bot

Behavior:

• 既定は OpenClaw のみです。OPENCLAW_GATEWAY_URL と OPENCLAW_GATEWAY_TOKEN（または OPENCLAW_GATEWAY_PASSWORD）を discord-reply-bot に渡すと、OpenClaw Gateway の POST /v1/chat/completions にユーザ文を送り、アシスタント本文を Discord に返信します。Cursor ゲートウェイには送りません（.env に CURSOR_AGENT_GATEWAY_URL が残っていても無視されます）。

  • Gateway で gateway.http.endpoints.chatCompletions.enabled を有効にしてください（無効だと HTTP 404 などになります）。

  • 主な環境変数: OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, 任意で OPENCLAW_CHAT_MODEL（未指定時は google/gemini-3.1-pro-preview）、OPENCLAW_SESSION_USER（未設定時は discord:<Discord ユーザー ID>）、OPENCLAW_MESSAGE_CHANNEL（既定 discord）、OPENCLAW_SESSION_KEY, OPENCLAW_MODEL_HEADER, OPENCLAW_PROMPT_PREFIX, OPENCLAW_GATEWAY_TIMEOUT_SEC。Gemini を使うには Gateway 側に Google プロバイダの認証（GEMINI_API_KEY 等）が必要です。

  • Cursor の mcp.json の openclaw の OPENCLAW_GATEWAY_TOKEN（または PASSWORD）を reply-bot の .env に同じ値で渡してください。URL は OpenClaw と同じホストなら http://127.0.0.1:<gateway-port>（Mac の MCP が使う Tailscale URL と同じである必要はありません）。

  • OpenClaw が未設定のときは、DM／メンションでも 設定不足の説明が返ります（旧来の短文エコーはしません）。

• Cursor の HTTP ゲートウェイだけ使う場合（cursor-cli-homelab を別ホスト／別 composeで動かしているとき）: .env に DISCORD_LLM_BACKEND=cursor と、到達可能な CURSOR_AGENT_GATEWAY_URL（例: http://192.168.x.x:9888）を書いてください。**POST /v1/prompt** で agent -p` の標準出力を返します。

  • ゲートウェイ側に CURSOR_API_KEY、任意で AGENT_APPROVE_MCPS=true など。リポジトリ付属の docker compose には agent-gateway は含みません（agent_gateway/ は手動同期用の参照実装のまま残しています）。

• DM と サーバー（@またはボットへの返信） の両方で上記のいずれかが使われます。

Discord の本文に含まれる <@…> 形式のメンションは、LLM に渡す前にプレースホルダへ置き換えます（モデルが「ユーザーIDは解決できない」と返すのを防ぐため）。

Docker（reply-bot を OpenClaw と同一 VM で動かす場合のみ・任意）

channels.discord だけで足りるなら VM に置く必要はありません（上の「VM から削除する」を参照）。docker compose は discord-reply-bot の 1 サービスのみです。OpenClaw Gateway 本体は 含みません（ホスト上の openclaw gateway / systemd と同居させます）。

• network_mode: host のため、.env の OPENCLAW_GATEWAY_URL は http://127.0.0.1:<port>（例: http://127.0.0.1:18789）。ポートはその VM で Gateway が待ち受けているものに合わせる。

• Mac で docker compose up だけだとコンテナは立ちません（profile prod）。誤実行でリソースを食わないため。

• 本番 VMでは .env の COMPOSE_PROFILES=prod（.env.example に同梱）か、./scripts/homelab_docker_up.sh。

• ローカル試験のみ: COMPOSE_PROFILES=prod docker compose up -d --build（Linux が前提。Docker Desktop の挙動は環境による）。

• 必須: .env に DISCORD_BOT_TOKEN と OPENCLAW_GATEWAY_URL（ループバック） / OPENCLAW_GATEWAY_TOKEN（または PASSWORD）。

• Cursor 経路に切り替えるときだけ .env に DISCORD_LLM_BACKEND=cursor と、到達可能な CURSOR_AGENT_GATEWAY_URL。

• DISCORD_BOT_TOKEN・OPENCLAW_GATEWAY_TOKEN は Git に載せないこと。

旧構成（別 VM に Discord ボットだけ置く）をやめた場合: もう使わない VM 上で docker compose down のうえ、コンテナ／compose を削除してください。Tailscale 越し URL は不要になるため、.env の OPENCLAW_GATEWAY_URL はループバックに統一します。

ゲスト（OpenClaw VM）での手順例:

git clone https://github.com/taka392/discord-mcp.git
cd discord-mcp
./scripts/homelab_docker_up.sh
# 初回は .env が無いので .env.example がコピーされる → DISCORD_BOT_TOKEN と OPENCLAW_* を編集して再度

手動でも同じです。

cp .env.example .env
# DISCORD_BOT_TOKEN, OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789, OPENCLAW_GATEWAY_TOKEN
COMPOSE_PROFILES=prod docker compose up -d --build
docker compose logs -f

停止・更新:

COMPOSE_PROFILES=prod docker compose down
COMPOSE_PROFILES=prod docker compose up -d --build

restart: unless-stopped なのでゲスト再起動後もコンテナが戻る（Docker が起動時に有効な前提）。

Proxmox QEMU VM（ゲストエージェント）

OpenClaw Gateway を動かしている QEMU VM（Discord 専用 VM など 別 vmid ではない）に discord-mcp を clone し、Mac から .env を流し込んで docker compose まで実行します。

1. ~/.cursor/mcp.json に mcpServers.discord.env.DISCORD_BOT_TOKEN と openclaw のトークン（またはパスワード）を用意する。

2. proxmox-mcp と同じ PROXMOX_* をシェルにエクスポートする。

3. --vmid には その OpenClaw ホストの vmid を渡す。毎回省略したい場合は export OPENCLAW_QEMU_VMID=<vmid>。

4. Gateway ポートが 18789 でないときは OPENCLAW_GATEWAY_LOCAL_URL または --local-gateway-url を指定。

cd projects/discord-mcp
export PROXMOX_BASE_URL=... PROXMOX_TOKEN_ID=... PROXMOX_TOKEN_SECRET=... PROXMOX_VERIFY_TLS=false
export OPENCLAW_QEMU_VMID=101   # OpenClaw が乗っている VM（例。100 とは限らない）
python3 scripts/push_gateway_env_guest_exec.py --vmid 101
# 例: python3 scripts/push_gateway_env_guest_exec.py --vmid 101 --repo-dir /root/discord-mcp --local-gateway-url http://127.0.0.1:18789

Mac から OpenClaw VM へ SSH でデプロイ

scripts/deploy_remote.sh は リモートで git pull → scp で .env → homelab_docker_up.sh まで行います。生成する OPENCLAW_GATEWAY_URL はデフォルトで http://127.0.0.1:18789（OPENCLAW_GATEWAY_LOCAL_URL で変更可）。Gateway が別ホストのときは export DISCORD_USE_MCP_GATEWAY_URL=1 とすると mcp.json の OPENCLAW_GATEWAY_URL を書き込みます。

cd /path/to/discord-mcp
export HOMELAB_SSH='root@<OpenClaw-VM の IP or tailscale>'
# optional: export OPENCLAW_GATEWAY_LOCAL_URL='http://127.0.0.1:18789'
# optional: export DISCORD_USE_MCP_GATEWAY_URL=1   # Gateway が別マシン（MCP の URL を .env に）
# optional: export HOMELAB_REPO_DIR='/root/discord-mcp'
./scripts/deploy_remote.sh

注意: DISCORD_BOT_TOKEN だけ export したモードでは、リモート .env にトークンとループバック URLだけ入り OPENCLAW_GATEWAY_TOKEN は手で追記してください。

Discord から 「ゲートウェイが利用できません (503)」 は DISCORD_LLM_BACKEND=cursor かつ CURSOR_API_KEY 未設定なときに出やすいです（Cursor 経路）。

OpenClaw 既定では、同一 VM 上で Gateway が待ち受けているか（ss -tlnp 等）、OPENCLAW_GATEWAY_URL / トークン、Gateway の chat completions 有効化を確認してください。

127.0.0.1:18789 に接続できない と出るときの整理:

1. **127.0.0.1 は「そのプロセスが動いているマシン自身」**です。Discord ボットが VM100 など別ホストで動いていて、OpenClaw が VM105 だけなら、.env の http://127.0.0.1:18789 は VM100 の自分自身 を指し、OpenClaw には届きません。

2. ボットも OpenClaw も VM105 に置くなら、同じゲストで OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789 が正しく、VM105 上で ss -tlnp | grep 18789 に Gateway が見える必要があります。

3. ボットだけ別 VM のままにするなら、.env は http://<VM105 の tailscale IPv4>:18789（105 上で tailscale ip -4）か、mcp.json の HTTPS の Gateway URL（push_gateway_env_guest_exec.py --use-mcp-gateway-url）にしてください。

4. VM105 に discord-mcp を clone して compose する場合、ゲストに Docker（と compose プラグイン） が必要です。無いと docker: command not found で失敗します。

Local check

cd projects/discord-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
DISCORD_BOT_TOKEN='your token' python -m discord_mcp.check

Cursor registration

After publishing to GitHub, merge the snippet from examples/cursor_mcp_config.example.json into ~/.cursor/mcp.json and reload Cursor.

License

MIT