Thee Discord MCP

A safety-gated Discord administration MCP server built on Discord's official REST API. It combines broad guild management, dry-run planning, local resource tracking, audit reasons, and explicit safeguards around high-impact actions without turning every related operation into a separate tool.

What it manages

• Guild settings, roles, role order, and member role assignment

• Categories, text/announcement/voice/stage/forum/media channels, ordering, and permission overwrites

• Forum tags, posting guidelines, sorting, and layout

• Messages: list, send, edit, delete, pin, unpin, and bulk delete

• Message inspection, full JSON payloads, announcement crossposts, current paginated pins, and complete reaction cleanup

• Members: list/search, timeout, kick, ban, and unban

• Guild previews, role member counts, prune previews and guarded execution, bulk bans, integrations, incident actions, vanity URLs, and voice regions

• Reactions, invites, scheduled events, and forum/thread membership

• Public, private, and joined-private thread archives; threads created from messages; join/leave and member inspection

• Webhook lifecycle and execution with token/URL redaction

• Voice member inspection, moves, disconnects, server mute, and server deaf

• Stage instances, soundboard sounds, polls, and indexed message search

• Guild stickers with validated multipart uploads

• Guild templates, widgets, and guild or global application commands

• Application emojis and linked-role metadata schemas

• Optional one-to-one DMs restricted to an explicit user allowlist and disabled by default

• Membership Screening rule reads and guarded updates

• AutoMod rules, onboarding, welcome screen, emojis, and audit-log reads

• Idempotent JSON blueprints with a dry-run planner, snapshot-bound approvals, and restart-aware execution journals

• Bot and application profile management, including avatar and banner data URIs

• A tightly scoped raw REST escape hatch for new Discord endpoints and guild-owned resources

There are 49 MCP tools exposing 168 schema-declared operations. The operation count treats every top-level action choice as one operation and every single-purpose tool as one operation. Related work stays together: for example, one discord_guild_operations tool contains preview, role-count, prune, integration, vanity URL, bulk-ban, voice-region, and incident actions instead of publishing eleven separate executables. The smoke test calculates and locks both inventory totals so documentation drift fails validation.

Every guild call is limited to IDs in DISCORD_ALLOWED_GUILD_IDS. Direct messages have a separate DISCORD_ALLOWED_USER_IDS boundary, are empty by default, and verify the one-to-one DM recipient before every read or write. The raw escape hatch remains guild-scoped; it canonicalizes paths before authorization, verifies indirect guild/channel IDs in request bodies, and never becomes a general Discord request proxy.

discord_capabilities reports or searches the grouped operation families without contacting Discord, so a client can discover a narrow capability without loading a separate tool for every endpoint. Three static MCP resources expose the capability index, safety model, and public-release checklist at discord://capabilities, discord://safety, and discord://public-release. The committed machine-readable capability inventory is generated from the real MCP handshake and records each tool's actions, schema size, schema digest, annotations, and resource count; CI fails if it drifts. Empty 204 No Content responses are normalized to { "ok": true }; webhook credentials and uploaded data URIs are redacted from previews and tool results.

Coverage at a glance

Safety modes

The default is read-only. Permission overwrites, role permission changes, guild security settings, and blueprints containing those fields are privileged writes: they require full mode and a payload-bound confirmation returned by the matching dry-run, but not the separate destructive opt-in. Confirmations are held only in process memory, expire after DISCORD_CONFIRMATION_TTL_SECONDS (five minutes by default), are consumed before the Discord request begins, and become invalid after a server restart. Blueprint approval also binds to the exact planned actions and a stable live-guild precondition snapshot, so drift requires a new dry-run. Blueprint application never deletes unmanaged resources.

1. Create the Discord operator

Create a dedicated application in the Discord Developer Portal, add a bot, and invite it only to the server you want to manage. Never use a personal/user token.

For the full tool set, the bot may need:

• View Channels, Read Message History, Send Messages, Add Reactions, Manage Messages, Manage Threads

• Manage Channels, Manage Roles

• Moderate Members, Kick Members, Ban Members

• Move Members, Mute Members, Deafen Members

• Manage Guild, View Audit Log, Create Events, Manage Events

• Pin Messages and Set Voice Channel Status for the corresponding features

• Speak, Use Soundboard, and Use External Sounds for soundboard playback

• Create Instant Invite, Manage Webhooks, Create Guild Expressions, and Manage Guild Expressions only if you use related operations

Indexed guild-message search additionally requires the privileged Message Content intent in the Discord Developer Portal. Without it, Discord returns Missing Access; other read tools continue to work.

Administrator is convenient but not required or recommended. Discord role hierarchy still applies: the operator can manage only roles and members below its highest role.

2. Install and configure

Requires Node.js 20.19 or newer and pnpm.

git clone https://github.com/TheETR/Thee-Discord-MCP.git
cd Thee-Discord-MCP
pnpm install
Copy-Item .env.example .env

Open .env locally and set:

DISCORD_BOT_TOKEN=your_dedicated_bot_token
DISCORD_ALLOWED_GUILD_IDS=123456789012345678
DISCORD_ALLOWED_USER_IDS=
DISCORD_MODE=read-only
DISCORD_CONFIRMATION_TTL_SECONDS=300
DISCORD_REQUEST_TIMEOUT_MS=15000
DISCORD_REQUEST_RETRIES=3

Leave DISCORD_ALLOWED_USER_IDS empty unless the bot should communicate with specific users. Add only comma-separated Discord user IDs whose one-to-one DM access you intend to permit. Group DMs and arbitrary recipients are rejected.

Do not paste the token into messages, issue reports, or committed files. To copy a Discord server ID, enable Developer Mode in Discord, right-click the server, and choose Copy Server ID.

Build and verify:

pnpm check

3. Connect an MCP client

Add the server to your MCP client configuration. An editable example is included as mcp.config.example.toml:

[mcp_servers.thee-discord]
command = "node"
args = ["C:/path/to/Thee-Discord-MCP/dist/index.js"]
cwd = "C:/path/to/Thee-Discord-MCP"
startup_timeout_sec = 20
tool_timeout_sec = 120

Restart the client and export a snapshot before making changes. Review the channels, roles, forums, and permission overwrites while the server is still in read-only mode.

For a public bot release, call discord_health with action: "release_readiness" and an allowlisted guildId. It verifies the current token/application identity, public-install setting, legal URLs, install scopes, command registration, visible Message Content flags, guild membership, and the bot's role permissions. It intentionally reports member-flow acceptance and Server Profile traits as manual checks. The result applies only to the application authenticated by the active token; it cannot inspect a separate product bot.

Once the snapshot looks right, set DISCORD_MODE=safe-write, restart the MCP server, and apply ordinary changes. Keep destructive mode disabled until a specific deletion or moderation action is needed.

Blueprint workflow

examples/elalem.blueprint.json provides an English ELALEM support and community layout with restrained category styling, a welcome message, two forum templates, tags, staff privacy, and practical channel names.

See docs/ELALEM.md for the live-server handoff, current user-facing channel copy, and the remaining boundaries that require Discord's UI or another bot runtime.

See docs/API_COVERAGE.md for the full capability map, safety model, and deliberate boundaries.

Recommended flow:

1. discord_export_snapshot

2. Adjust the blueprint to preserve intentional existing resources.

3. discord_plan_blueprint or discord_apply_blueprint with dryRun: true.

4. Review every planned action.

5. Switch to safe-write and run discord_apply_blueprint with dryRun: false.

6. Export another snapshot and verify the result.

Blueprint channel mentions use {{channel:key}}; they are resolved to real clickable Discord mentions when a message is sent.

The blueprint deliberately performs no deletion. Existing channels or roles with different names are left alone unless their tracked key points to them. Review duplicate or obsolete resources separately before removing anything.

Actual blueprint runs persist a versioned journal before the first Discord write and around every planned action. The journal records precondition, plan, and blueprint digests; per-action pending/running/completed/failed state; returned resource IDs; recovery ancestry; and a final applied-plan digest. Version-1 state files migrate to version 2 on their next save. A retry of the same interrupted blueprint is linked as a recovery attempt, while deterministic message nonces plus a recent-message lookup reduce duplicate guide posts after an uncertain interruption. Discord has no multi-resource transaction or rollback, so inspect failed journals and rerun the same blueprint after correcting the cause.

Destructive operations

To permit a specific destructive action temporarily:

DISCORD_MODE=full
DISCORD_ENABLE_DESTRUCTIVE=true

Run the exact operation with dryRun: true, review the plan, then copy its expectedConfirmation into confirm before it expires. The token is single-use—even a failed downstream Discord request requires a fresh dry-run—and is bound to an operation-specific base such as DELETE CHANNEL <id>. High-fan-out operations such as bulk bans and pruning also include a digest derived from the exact target set, so a confirmation cannot authorize a different batch. Irreversible announcement crossposts and linked-role metadata replacement use the same full-mode gate. Return to safe-write or read-only afterward.

The raw REST tool treats every non-GET request as destructive. Its one-time confirmation includes a SHA-256-derived digest of the exact request body, so a confirmation for one payload cannot authorize another. Absolute URLs, fragments, control characters, encoded path separators, dot segments, duplicate slashes, cross-guild body references, and unverified channel references are rejected before the request is sent.

Discord platform boundaries

The server uses a bot token only. It does not automate user-only endpoints, self-bots, account sessions, or unsupported client APIs. For example, Discord's Server Profile Traits field is visible in the desktop client but its profile endpoint rejects bot tokens with Bots cannot use this endpoint; that field must currently be changed by a signed-in server administrator in Discord.

See Discord API Coverage for named surfaces and deliberate omissions, Security Review and Roadmap for threat boundaries and remaining hardening work, and ELALEM Server Handoff for the live server layout and runtime boundaries.

Development

pnpm typecheck
pnpm test
pnpm build

The server uses stdio, so stdout is reserved for MCP protocol traffic; operational messages go to stderr. Discord rate limits, transient timeouts, and retryable server failures are handled by @discordjs/rest. Each network attempt is bounded by DISCORD_REQUEST_TIMEOUT_MS (15 seconds by default), and DISCORD_REQUEST_RETRIES controls the bounded retry count (three by default).

License

MIT