discord-mcp

Live demo

An 87-second live walkthrough of an AI agent building a complete gaming community from a fresh Discord server through its caller-owned bot. It covers channels, safe role permissions, Community, Welcome Screen, onboarding, AutoMod, Components V2 cards, and final API readback. Watch the full demo in the docs.

The current blueprint lifecycle adds a target-bound dry run, exact human approval, checkpointed resume, and authenticated Activity Evidence after final Discord readback. Complete the verified-outcome tutorial in a private test guild.

Completed it—or found the first blocker? Share a voluntary, credential-safe outcome report. discord-mcp sends no report from your installation.

If you want a shortcut after a local run, discord-mcp activity --report prints that fixed URL without reading or exporting the journal. It does not open a browser, access the network, prefill or submit an issue, or expose journal records. Review every field and submit the form yourself. The local journal contains only timestamps plus predefined command or blueprint-stage, status, outcome, transport, and signal values; it contains no Discord IDs, names, message content, tokens, paths, or raw errors.

Community and feedback

Use GitHub Discussions for setup Q&A, recurring-workflow ideas, and redacted showcases. Start with the community welcome or watch and discuss the official live-build showcase.

Never post a bot token, authorization header, client configuration, Discord ID, private server or channel name, message content, screenshot, terminal log, plan material, evidence ID, or Activity Evidence file. Report authorization or security issues through GitHub's private advisory form.

How it works

Quick start

Requires Node.js 22.12 or later.

# Install the MCP server
npm install -g @discord-mcp/cli

# Keep the caller-owned bot token in this terminal
export DISCORD_TOKEN="Bot YOUR_DISCORD_BOT_TOKEN"

# Verify the bot, choose its real Discord server, save a non-secret profile,
# and generate a safe Codex fragment
discord-mcp setup --profile devbot --client codex

# Verify the rest of the local configuration
discord-mcp doctor --profile devbot --online

# Explain the bot's verified guild access before a planned write
discord-mcp doctor --profile devbot --access --guild-id <GUILD_ID> --json

# Verify the real MCP path without changing Discord
discord-mcp smoke --profile devbot

On PowerShell, set the token before running the same setup and verification commands:

$env:DISCORD_TOKEN = "Bot YOUR_DISCORD_BOT_TOKEN"

setup supports Codex, Claude Desktop, Claude Code, Google Antigravity CLI, Cursor Agent CLI, the official Grok Build CLI, DeepSeek Harness, legacy Gemini CLI enterprise/API-key deployments, the Cursor editor, and a generic MCP client. It sends the current token only to Discord, verifies the bot identity, chooses a guild boundary, and saves a versioned local profile containing only non-secret metadata. The generated client fragment runs a pinned @discord-mcp/cli package through npx, then serve --profile devbot, so it does not depend on an absolute installation or cache path. It forwards DISCORD_TOKEN from the caller's launch environment; neither the profile nor the generated fragment stores the token value. Antigravity, Cursor Agent, and Grok Build inherit the launch environment and keep credentials out of their MCP configuration. Gemini's compatibility fragment includes only ${DISCORD_TOKEN} because Gemini sanitizes inherited sensitive variables unless its MCP entry explicitly opts in. DeepSeek Harness receives a Cordis YAML patch with DISCORD_TOKEN: !!js process.env.DISCORD_TOKEN for explicit secret forwarding. Use --client deepseek-harness --output discord-mcp.cordis.yml, then start Harness with dsh web --patch ./discord-mcp.cordis.yml. A profile is locked to its first verified bot ID, so --force cannot silently reassign it to another bot. Use profile list, profile show, and profile remove for lifecycle management. The older init command remains available as a stateless snippet generator. See the installation guide for non-interactive and client-specific setup.

For MCP clients that do not natively defer large tool catalogs, set MCP_TOOL_SURFACE=progressive. The model initially receives only the direct Discord-non-mutating build_discord_server architecture front door when authorized, its direct guild_blueprint_apply and guild_blueprint_evidence completion steps, plus mcp_tools_search and read, write, and destructive dispatchers. Other tools load as compact matches on demand. A single match already includes its schema; for multiple matches, search the selected tool's exact name before dispatch, or use detail: "full" when several contracts are needed together. The result chooses the dispatcher whose annotations match the selected tool's risk. MCP_CATEGORIES remains the authorization boundary; progressive mode does not bypass confirmation, dry-run, audit, or other middleware.

Set ALLOWED_GUILDS to a comma-separated list of server IDs to enforce the bot's guild boundary inside discord-mcp. Direct guild calls use a constant-time check; channel, thread, webhook, invite, and guild-sticker routes are resolved before execution and cached. Global writes and opaque interaction-token routes that cannot prove a guild are unavailable while the allowlist is active. When that boundary is active, bot-application routes (the five application-emoji operations, application commands, SKUs, entitlements, and application metadata) are exposed only when DISCORD_EXPECTED_BOT_ID locks the token to one bot and they can target only that bot's application. Omit application_id where supported to have the server resolve the current bot application automatically. The resolution caches are bounded to prevent untrusted ID churn from growing memory without limit. users_list_current_user_guilds remains a read-only discovery tool; seeing a guild in that result does not authorize operations against it.

To run without a global install:

npx -y @discord-mcp/cli init --client cursor-cli

Remote OpenAI / Codex MCP

For the OpenAI Responses API or Codex, run a bearer-protected Streamable HTTP endpoint and place it behind an HTTPS reverse proxy:

export DISCORD_TOKEN="Bot YOUR_DISCORD_BOT_TOKEN"
export DISCORD_MCP_ACCESS_TOKEN="replace-with-a-long-random-secret"
discord-mcp serve --http --host 127.0.0.1 --port 3000

The endpoint is /mcp; send Authorization: Bearer <DISCORD_MCP_ACCESS_TOKEN>. It negotiates stable MCP 2026-07-28 while retaining stateless compatibility for 2025-era Streamable HTTP clients. Every authenticated client shares the deployment's caller-owned Discord bot identity, so use least-privilege Discord roles plus narrow ALLOWED_GUILDS and MCP_CATEGORIES allowlists. The OpenAI remote MCP guide covers HT