Discord MCP

A Python MCP server for reading messages, inspecting channels and servers, and managing Discord through its REST API. Runs locally over stdio with one environment variable: DISCORD_TOKEN.

The token is sent verbatim in the Authorization header. This server never adds Bot, Bearer, or another prefix. It does not attempt to detect or change the credential type.

Install

Requires Python 3.11+.

git clone https://github.com/RestartFU/discord-mcp.git
cd discord-mcp
python3 -m venv .venv
.venv/bin/pip install .

Configure an MCP client with the absolute path to the installed executable:

{
  "mcpServers": {
    "discord": {
      "command": "/absolute/path/to/discord-mcp/.venv/bin/discord-mcp",
      "env": {
        "DISCORD_TOKEN": "your-token-exactly-as-supplied"
      }
    }
  }
}

On Windows, use .venv\\Scripts\\discord-mcp.exe. You can also supply DISCORD_TOKEN through the parent process environment and omit env. .env files are not loaded automatically. Keep credentials out of source control.

Start by calling get_current_user, then list_guilds, list_channels, and read_messages. Enable Discord Developer Mode to copy IDs, or use the IDs returned by these tools. IDs are strings to preserve precision.

Related MCP server: discord-mcp

Tools

discord_request covers other REST operations such as bans, kicks, permission overwrites, webhooks, emojis, scheduled events, archived threads, polls, and role edits. It accepts only API-relative paths under https://discord.com/api/v10; the credential is not forwarded to redirects or arbitrary hosts.

Example: inspect permission overwrites with get_channel, then update one:

{
  "method": "PUT",
  "path": "/channels/CHANNEL_ID/permissions/ROLE_ID",
  "body": {"type": 0, "allow": "1024", "deny": "0"},
  "reason": "Allow the selected role to view this channel"
}

Upload a file by passing files alongside a message body to discord_request:

{
  "method": "POST",
  "path": "/channels/CHANNEL_ID/messages",
  "body": {"content": "Attached note", "allowed_mentions": {"parse": []}},
  "files": [{"filename": "note.txt", "data_base64": "SGVsbG8h", "content_type": "text/plain"}]
}

Uploads are limited to 10 files and 10 MiB total per request. The dedicated send/edit tools suppress mention parsing; the general REST tool uses your payload as supplied.

Access and behavior

This is REST access, not a complete Discord desktop client: no voice/video streaming, Gateway event subscription, or automatic CAPTCHA handling. Operations succeed only where Discord accepts the supplied Authorization value and grants the required permissions. Raw credentials are not guaranteed to work with every endpoint. Discord's documented authentication uses typed Authorization values; this implementation deliberately leaves your supplied value unchanged.

History returns at most 100 messages per request; use the oldest message ID as before for older pages. Server and member lists also support pagination. Search may return an indexing response instead of results. See Discord's message documentation for content access requirements and endpoint fields.

Requests are serialized per process, and 429 rate limits are retried up to three times using Discord's delay. Long waits are returned as errors and retained as a local cooldown. Network errors and 5xx responses are not retried automatically because a write may already have succeeded. Multiple server processes do not share rate-limit state.

The credential is redacted from returned data and API error text. Tool results can still contain private Discord content, invite codes, or webhook credentials; the MCP client receiving them must be trusted. Tool annotations identify reads and destructive operations. The general REST tool is conservatively marked destructive because it can write or delete.

Development

.venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/pytest

Tests use mocked Discord HTTP responses and a real MCP stdio handshake; no Discord token or live messages are required. The implementation uses the official MCP Python SDK, pinned to its 1.x API.