discord-mcp

How it works

Related MCP server: Discord MCP Server

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 exact Discord tool schemas on demand. The search 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.14.4; its core exports, CLI surface, environment schema, and 192-tool registry are covered by contract tests. See the changelog and v1.0 readiness checklist before depending on an unstable surface.

License

MIT