discord-mcp
Connect your AI client to Discord through a typed, production-ready MCP server.
192 tools for messages, moderation, members, channels, commands, webhooks, and more.
Quickstart · Browse 192 tools · View on npm · Documentation
How it works
Quick start
Requires Node.js 22.12 or later.
# Install the MCP server
npm install -g @discord-mcp/cli
# Generate a client-specific configuration fragment for Codex
discord-mcp init --client codex
# Verify your Discord token and local configuration
export DISCORD_TOKEN="Bot YOUR_DISCORD_BOT_TOKEN"
discord-mcp doctor --online
On PowerShell, set the token with:
$env:DISCORD_TOKEN = "Bot YOUR_DISCORD_BOT_TOKEN"
init supports Codex, Claude Desktop, Claude Code, Cursor, and a generic MCP client. It prints a complete configuration fragment; merge it into an existing client configuration rather than overwriting it. The Codex fragment forwards DISCORD_TOKEN from its launch environment instead of storing the token in ~/.codex/config.toml. See the installation guide for non-interactive and client-specific setup.
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 and a narrow MCP_CATEGORIES allowlist. The
OpenAI remote MCP guide
covers HTTPS, Responses API, Codex configuration, and the current OAuth boundary.
What you get
| Area | Examples |
|---|---|
| Messages and channels | Send, edit, pin, search, manage threads, forums, and permissions |
| Moderation and safety | Bans, role changes, AutoMod rules, bulk actions, and audit-aware operations |
| Community operations | Members, roles, invites, onboarding, events, polls, soundboard, and voice |
| Application APIs | Slash commands, interactions, application emojis, webhooks, and entitlements |
| Agent workflows | Tool output schemas, predictable errors, migration adapters, and client config generation |
Explore the complete, generated tool reference and practical recipes.
Built for production use
- Safety controls - destructive operations require explicit confirmation and can be governed by category-level controls.
- 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
| Command | Purpose |
|---|---|
discord-mcp serve | Start the local stdio MCP server (default), or serve --http for a bearer-protected Streamable HTTP endpoint. |
discord-mcp init | Generate an MCP client configuration snippet. |
discord-mcp doctor | Check Node.js, token format, environment, audit configuration, and optional network connectivity. |
discord-mcp migrate | Create a migration report from a supported Discord MCP setup. |
Run discord-mcp --help or see the full CLI reference for flags and examples.
Packages
| Package | Use it when |
|---|---|
| @discord-mcp/cli | You want to run Discord MCP from an AI client or terminal. |
| @discord-mcp/core | You are building an integration on the typed Discord MCP tool and server primitives. |
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.13.2; 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.