Discord Management

Safe-by-default Discord management from any MCP client

CI License npm

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"
      }
    }
  }
}

Client	Registration
Claude Desktop	Add the entry above to the MCP servers configuration.
Claude Code	Add a local stdio server with the same command and arguments.
Cursor	Add the entry above to the MCP configuration.
VS Code	Add the same command and arguments in the client's MCP configuration.
Codex	Add a stdio server entry with the same command and arguments.
Windsurf	Add the entry above to the MCP configuration.
Cline	Add the server in the MCP settings panel.

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.

Set up

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.

Why this one

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:

Capability	Typical preview-only server	Discord Management MCP
Read-only inspection	Yes	Yes, 23 read-only tools
Execute changes	No	Yes, 31 mutating and moderation tools
Local backup before risky changes	Rarely	JSON schema v2 snapshots with channel coverage
Restore	No	Plan with plan hash, apply with pre-restore backup
Rollback guarantee	Not offered	Best effort, reported honestly with NOT_RESTORED warnings
Data path	Often hosted	Local stdio only

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.

Domain	Tools
Guild, member, and audit inventory	17
Backups and restore	6
Channels	6
Roles	7
Moderation and AutoMod	13
Server configuration	5
Total	54

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.

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.

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.

Variable	Purpose	Default
DISCORD_TOKEN	Discord bot token from Developer Portal > Bot > Token	Required
BACKUP_DIR	Relative directory for local JSON backups; it must stay inside the project directory	backups
LOG_LEVEL	Stderr log level: error, warn, info, or debug; logs are JSON lines	info
ENABLE_MESSAGE_CONTENT	Enables message-content tools and requires the Discord Message Content intent	false
ENABLE_GUILD_MEMBERS	Enables the Guild Members gateway intent for workflows that require it	false

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.

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. High-impact tools additionally require a backupId from the same guild, or an explicit allowWithoutBackup: true acknowledgement. discord_set_incident_actions is the exception for emergency use. Check the guard matrix before retrying.

Channels are missing from a backup or channel list

The bot can only back up channels it can view. Starting 2026-11-16, Discord omits channels the bot cannot view from GET /guilds/{id}/channels, and gateway payloads can carry obfuscated channel objects. Backups record this in coverage.channels and warn when coverage is incomplete. Grant VIEW_CHANNEL where the channels matter, and treat complete: false as a partial rollback point. See channel coverage and obfuscation.

Restore reports skipped or lossy operations

Discord cannot recreate original IDs, message or audit-log history, exact invite codes, webhook tokens, managed integration objects, or every community and discovery setting. Check the plan's planHash and its NOT_RESTORED warnings, then review the reported operations before retrying.

Logs are too quiet or too noisy

Set LOG_LEVEL to error, warn, info, or debug. Logs are JSON lines on stderr, so stdout stays reserved for MCP protocol traffic. Use debug while diagnosing a tool call and error for quiet hosts.

Development

Requirements: Node.js 24 or newer and npm from the lockfile.

git clone https://github.com/TheStreamCode/discord-management-mcp.git
cd discord-management-mcp
npm ci
npm run lint
npm run typecheck
npm test
npm run build
npm run verify:mcp
npm run preflight
npm run pack:check
npm audit --omit=dev --audit-level=high

npm run verify:mcp starts the built server over stdio with a placeholder token and checks the advertised MCP surface: 54 tools, deterministic tool listing, titles, descriptions, input and output schemas, and annotation hints. It never calls the Discord API.

Tests use mocks and must not contact Discord. Live mutations are never part of routine verification. The repository keeps its engineering guidance in AGENTS.md; it is not shipped in the npm package. See CONTRIBUTING.md for contribution rules.

Support

See SUPPORT.md. Use GitHub Issues for reproducible bugs and feature proposals, and report vulnerabilities privately through GitHub Security Advisories.

Contributing

See CONTRIBUTING.md. Pull requests must pass npm run preflight, npm run verify:mcp, and the required CI checks.

License

MIT, see LICENSE. Copyright (c) 2026 Michael Gasperini (Mikesoft).

This independently developed project is not affiliated with, endorsed by, sponsored by, or approved by Discord Inc. Discord is a trademark of Discord Inc. See NOTICE for the applicable Discord terms and policies.

---

Maintained by Michael Gasperini (Mikesoft). If this project helps you manage Discord communities safely, consider sponsoring its maintenance.