Lets an AI client inspect, back up, and manage Discord guilds with guarded mutations and JSON-based restore planning.
Also known as TheStreamCode/discord-management-mcp
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.2.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is Discord Management MCP?
Discord Management lets an AI client inspect, back up, and manage Discord guilds with guarded mutations and JSON-based restore planning.
Summary generated from the project's README
About Discord Management MCP server
Managing Discord communities with an AI client is made safer through this local MCP server that provides tools for inspecting, backing up, and modifying guilds. It operates over stdio, ensuring that your bot token and JSON backup files remain on your own machine rather than being sent to a hosted service. The server is compatible with clients like Claude Desktop, Cursor, Windsurf, and Cline by using a local command and the DISCORD_TOKEN environment variable.
Developers can access 54 distinct tools covering moderation, roles, channels, and server settings. To prevent accidental changes, every mutation requires an explicit confirmation and an audit reason. High-impact operations are further protected by a safety matrix that requires a recent backup before proceeding. This setup allows for a controlled workflow where you can create a snapshot with discord_backup_create, review a proposed change with a restore plan, and then apply or roll back settings as needed.
What you can do with it
- 1Audit and inventory Discord settingsUse the server to list all guilds and inspect current channel or role configurations.
- 2Create a safety snapshotGenerate a local JSON backup of your server settings before performing risky administrative tasks.
- 3Plan and execute server changesReview a diff of proposed changes and apply them using a verified restore plan.
- 4Perform moderated administrative actionsModify roles or channels while providing a mandatory reason for the audit log.
Written from the project's README. Every use case is checked against a quote from it.
How to install Discord Management MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Discord Management MCP in Claude Code
$ claude mcp add --env 'DISCORD_TOKEN=<YOUR_DISCORD_TOKEN>' discord-management-mcp -- npx -y discord-management-mcpInstall Discord Management MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"discord-management-mcp": {
"command": "npx",
"args": [
"-y",
"discord-management-mcp"
],
"env": {
"DISCORD_TOKEN": "<YOUR_DISCORD_TOKEN>"
}
}
}
}Install Discord Management MCP in VS Code
.vscode/mcp.json
{
"servers": {
"discord-management-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"discord-management-mcp"
],
"env": {
"DISCORD_TOKEN": "<YOUR_DISCORD_TOKEN>"
}
}
}
}Install Discord Management MCP in VS Code CLI
$ code --add-mcp '{"name":"discord-management-mcp","type":"stdio","command":"npx","args":["-y","discord-management-mcp"],"env":{"DISCORD_TOKEN":"<YOUR_DISCORD_TOKEN>"}}'Install Discord Management MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"discord-management-mcp": {
"command": "npx",
"args": [
"-y",
"discord-management-mcp"
],
"env": {
"DISCORD_TOKEN": "<YOUR_DISCORD_TOKEN>"
}
}
}
}Install Discord Management MCP in Codex
$ codex mcp add discord-management-mcp --env 'DISCORD_TOKEN=<YOUR_DISCORD_TOKEN>' -- npx -y discord-management-mcpInstall Discord Management MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.discord-management-mcp] command = "npx" args = ["-y", "discord-management-mcp"] [mcp_servers.discord-management-mcp.env] DISCORD_TOKEN = "<YOUR_DISCORD_TOKEN>"
Install Discord Management MCP in Gemini CLI
$ gemini mcp add -s user -e 'DISCORD_TOKEN=<YOUR_DISCORD_TOKEN>' discord-management-mcp npx -- -y discord-management-mcpInstall Discord Management MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"discord-management-mcp": {
"command": "npx",
"args": [
"-y",
"discord-management-mcp"
],
"env": {
"DISCORD_TOKEN": "<YOUR_DISCORD_TOKEN>"
}
}
}
}Configuration
DISCORD_TOKENRequiredSecretDiscord bot token from Developer Portal > Bot > Token.
BACKUP_DIRRelative directory for local JSON backups. It must stay inside the project directory.
ENABLE_GUILD_MEMBERSEnables the Guild Members gateway intent.
ENABLE_MESSAGE_CONTENTEnables message-content tools and requires the Discord Message Content intent.
LOG_LEVELStderr log level: error, warn, info, or debug.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablethestreamcode/discord-management-mcp is public and reachablegithub.com/thestreamcode/discord-management-mcp ↗Pass
- Package names this repository as its sourcediscord-management-mcp names thestreamcode/discord-management-mcp as sourcenpmjs.com/package/discord-management-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for discord-management-mcpnpmjs.com/package/discord-management-mcp/v/0.2.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/thestreamcode/discord-management-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from discord-management-mcpPass
- No critical advisory in the package or its dependencies123 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubDiscord 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"
}
}
}
}
| 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.
Quick start
The short version, with the full walkthrough in setup and first use:
- 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.
- Invite it. OAuth2 > URL Generator > scope
botplus 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. - Copy the server ID. Enable Developer Mode, right-click the server icon, Copy Server ID. This number is the
guildIdargument, not the bot's application ID. - Register the client. Use the configuration in Register with your client with
DISCORD_TOKENinenv, or put the token in.env.localin the working directory. - Verify and back up. Ask the client to run
discord_list_guilds, thendiscord_backup_createfor your server, and readcoverage.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:
| 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: trueand 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:
discord_backup_createwrites a JSON snapshot toBACKUP_DIRatomically, strips invite codes, webhook tokens, and other secrets, and records channel coverage incoverage.channels.discord_backup_diffanddiscord_backup_restore_planshow what would change. A plan includes aplanHashandNOT_RESTOREDwarnings for captured sections that Discord cannot recreate.discord_backup_restore_applycan verify anexpectedPlanHash, 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.
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.
Safety model
- Every Discord mutation requires
confirm: trueand a non-emptyreason; 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: trueacknowledgement. discord_set_incident_actionsis 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. 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 is useful to you, consider sponsoring its maintenance.
Discord Management MCP questions
How do I add Discord Management MCP to Claude Code?
Run claude mcp add --env 'DISCORD_TOKEN=<YOUR_DISCORD_TOKEN>' discord-management-mcp -- npx -y discord-management-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Discord Management MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What credentials does the server need?
The server only requires a Discord bot token. Do not use the Application ID, Public Key, or OAuth2 client secret.
Can the server restore everything in a Discord server?
No, Discord cannot restore original IDs after delete and recreate, message or audit-log history, exact invite codes, or webhook tokens.
Why is my message content returning empty?
You must enable the Message Content intent in the Discord Developer Portal and set the ENABLE_MESSAGE_CONTENT environment variable to true.