Discord MCP

Connect your AI client to Discord through a typed, production-ready MCP server.
201 tools for Discord operations, Guild Templates, and explicit Emoji.gg inspiration discovery.

Quickstart · Browse 201 tools · Watch live demo · View on npm · Documentation

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.

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

# 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, Cursor, 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 default Codex fragment stores the token. 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
mcp_tools_search plus read, write, and destructive dispatchers, then loads
compact tool 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. 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

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 HTTPS, Responses API tool_search/defer_loading, Codex progressive
discovery, and the current OAuth boundary.

What you get

Explore the complete, generated tool reference and practical recipes.

Built for production use

• Safety controls - destructive operations require explicit confirmation; guild and category allowlists constrain the bot's blast radius server-side.
• Reliable Discord access - retries, timeouts, rate-limit handling, and circuit breaking protect agent workflows from transient API failures.
• Observability - OpenTelemetry traces and metrics, structured logs, and audit events make operations inspectable.
• Typed contracts - every tool is schema-defined; public core exports, CLI flags, configuration variables, and tool metadata are regression-tested.
• Supply-chain evidence - npm releases are published from GitHub Actions with signed SLSA provenance.

Read the architecture, operations guides, and v1.0 readiness plan for implementation details and current stability commitments.

Commands

Run discord-mcp --help or see the full CLI reference for flags and examples.

Packages

The CLI runs on macOS, Linux, and Windows. Its executable is always discord-mcp.

Migrate an existing setup

discord-mcp includes migration adapters for established community projects, including PaSympa, quadslab, and discord-ops. Start with:

discord-mcp migrate --list

Then use discord-mcp migrate --from <adapter> --source <path> to generate a tool-by-tool mapping report. The migration guides explain each adapter and its limits.

Develop locally

pnpm install
pnpm build
pnpm test

The repository is a pnpm workspace. For a real Discord smoke test, set DISCORD_TOKEN and run node packages/mcp-server/dist/cli.js; the MCP Inspector is useful for verifying tools/list interactively.

Project status

discord-mcp is pre-1.0. The current public release is v0.16.5; this source tree's core exports, CLI surface, environment schema, and 201-tool registry are covered by contract tests. See the changelog and v1.0 readiness checklist before depending on an unstable surface.

License

MIT