Discord Management MCP

Discord Management MCP

Safe-by-default Discord management from any MCP client

Discord Management MCP is a local Model Context Protocol (MCP) server for inspecting, backing up, and managing Discord guilds. It runs over stdio, keeps the bot token and backup files on the operator's machine, and places confirmation, backup, and restore guards in front of every mutation. The server exposes 54 tools across guild inventory, moderation, roles, channels, server settings, backups, and restore planning.

It works with any MCP client that supports local stdio servers, including Claude Desktop, Claude Code, Cursor, VS Code, Codex, Windsurf, and Cline. This independently developed project is not affiliated with, endorsed by, sponsored by, or approved by Discord Inc.

New to Discord bots? The setup and first use guide walks through creating the application, inviting the bot with the right permissions, copying the server ID, registering the client, verifying the connection, and running the first safe backup and restore.

Install

The published package runs with one command:

npx --yes discord-management-mcp

The package is published on npm as discord-management-mcp and declares MCP registry metadata for io.github.TheStreamCode/discord-management-mcp through package.json and server.json.

Register with your client

Every client needs the same command, arguments, and DISCORD_TOKEN environment variable. Paste the equivalent of this entry into the client's MCP configuration:

{

"mcpServers": { "discord-management": { "command": "npx", "args": ["--yes", "discord-management-mcp"], "env": { "DISCORD_TOKEN": "your_bot_token" } } } }

Claude Desktop, Cursor, Windsurf, and Cline accept the mcpServers JSON shape shown above. Clients that use a different configuration schema accept the same command, args, and env values. See each client's own documentation for the exact file or command.

Quick start

The short version, with the full walkthrough in setup and first use:

1. Create the bot. Developer Portal > New Application > Bot > Reset Token. That token is the only credential the server needs. Do not use the Application ID, Public Key, or OAuth2 client secret.
2. Invite it. OAuth2 > URL Generator > scope bot plus the permissions you need. Start with View Channels, Manage Channels, Manage Roles, Manage Server, View Audit Log, and the moderation permissions you plan to use. Then drag the bot role above the roles it must edit.
3. Copy the server ID. Enable Developer Mode, right-click the server icon, Copy Server ID. This number is the guildId argument, not the bot's application ID.
4. Register the client. Use the configuration in Register with your client with DISCORD_TOKEN in env, or put the token in .env.local in the working directory.
5. Verify and back up. Ask the client to run discord_list_guilds, then discord_backup_create for your server, and read coverage.channels.complete.

Example first request:

Use discord_list_guilds, then discord_backup_create for the server I name, and report the backup ID and coverage.

Then change things only through the guarded path: create a backup, review the target objects, apply one small change, and confirm the result. Every mutation needs an audit reason:

{

"guildId": "123456789012345678", "confirm": true, "reason": "Create the approved community announcements channel" }

High-impact operations also require a guild-matched backupId unless the operator explicitly accepts allowWithoutBackup: true. The tool catalog lists the exact policy for every mutating tool.

Features

Many Discord MCP servers stop at read-only inspection or previewing a change, and some route the bot token through a hosted service. Discord Management MCP executes changes locally, but only through a guard and recovery path:

What that means in practice:

• Local by design. The bot token, snapshots, restore plans, and stdio transport stay on the operator's machine. There is no hosted relay and no public HTTP listener.
• Preview, then apply. Backups can be diffed and turned into a restore plan before anything changes, and plans carry a hash that apply can verify.
• Backup to restore promise. A risky change can point at a same-guild snapshot; restore apply writes a fresh pre-restore backup before its first Discord mutation.
• An explicit safety matrix. Every Discord mutation needs confirm: true and a reason. The listed high-impact tools need a same-guild backup. Emergency incident actions stay available without one.
• Truthful recovery. Restore reports skipped, lossy, applied, and failed operations instead of promising an impossible full rollback.

Backup to restore

The recovery path has three steps:

1. discord_backup_create writes a JSON snapshot to BACKUP_DIR atomically, strips invite codes, webhook tokens, and other secrets, and records channel coverage in coverage.channels.
2. discord_backup_diff and discord_backup_restore_plan show what would change. A plan includes a planHash and NOT_RESTORED warnings for captured sections that Discord cannot recreate.
3. discord_backup_restore_apply can verify an expectedPlanHash, creates a pre-restore backup, then applies supported role and channel fields conservatively. Deletes remain opt-in.

Discord cannot restore original IDs after delete and recreate, message or audit-log history, exact invite codes, webhook tokens, or every community and discovery setting. The server reports those limits instead of hiding them. See safety and backups for the full model.

Tool coverage

The server registers 54 tools. See the tool catalog for every name and the guard matrix for the backup policy.

Read-only tools are annotated as read-only and never require confirmation. Mutating Discord tools require confirm: true plus a non-empty audit reason, and mutations run through a shared queue so they cannot interleave. discord_backup_create only writes a local snapshot and does not require confirmation.

Requirements

• Node.js 24 or newer.
• A Discord application with a bot token.
• The bot invited to the target guild with only the permissions required for the intended tools.

ENABLE_MESSAGE_CONTENT and ENABLE_GUILD_MEMBERS are opt-in and require the matching privileged intents in the Discord Developer Portal. Since 2026-06-10, Discord reviews privileged intent usage at 10,000 users rather than 100 servers, and approved apps must reapply annually. See configuration for details.

Configuration

Configuration is read from the process environment first, then from .env.local in the working directory. Boolean values accept true/false, yes/no, on/off, or 1/0.

See the configuration reference for token rules, logging behavior, and privileged-intent setup.

Privacy and security

Everything runs locally over stdio: the bot token, backup files, restore plans, and the server process itself never leave the operator's machine. Mutations are guarded by explicit confirmation and by backups that are validated for size, depth, structure, symlinks, and guild identity before planning or restore. A restore creates a pre-restore backup before its first Discord mutation and stops truthfully on operation failure. See design and trust boundaries and safety and backups for the full model, and SECURITY.md for private vulnerability reporting.

Safety model

• Every Discord mutation requires confirm: true and a non-empty reason; the reason is passed to Discord where audit-log reasons are supported.
• High-impact tools require a backup from the same guild, or an explicit allowWithoutBackup: true acknowledgement.
• discord_set_incident_actions is intentionally exempt: it is used during raids, and its changes are reversible.
• Restore apply creates its own pre-restore backup and retains its ID on every error path.
• Backup writes are atomic, and backup paths are confined to the project directory with symlink and junction rejection.
• Read-only tools are implemented and annotated as read-only.

See safety and backups for the guard matrix, channel coverage, and restore behavior, and design and trust boundaries for the runtime model. Report vulnerabilities privately through SECURITY.md.

Troubleshooting

The server exits because DISCORD_TOKEN is missing or invalid

Set the Bot Token in the process environment or in .env.local in the working directory. A value that looks like a Discord Application Public Key is rejected with an explicit message: use the Bot Token, not the Application ID, Public Key, or OAuth2 client secret.

Message content comes back empty

Message-content tools need both ENABLE_MESSAGE_CONTENT=true and the Message Content Intent enabled in the Discord Developer Portal. Without both, Discord can return empty content, embeds, and attachments fields. Restart the server after changing either side. If the app is approaching the review threshold, remember that privileged intent access is reviewed at 10,000 users and must be renewed annually.

A mutation is rejected before it reaches Discord

Mutating tools require confirm: true and a non-empty reason.