Discord MCP server

A local Model Context Protocol server that lets an MCP client inspect and manage Discord through a bot account. It communicates over stdio, so it does not open an HTTP port.

The server uses a Discord bot token. It does not use, and must not be given, a Discord user token.

What it does

• Lists guilds, channels, roles, messages, users, and members.

• Creates, edits, moves, and deletes channels.

• Sends messages and creates forum posts.

• Creates, renames, assigns, removes, and deletes roles.

• Kicks and bans members.

• Can write local JSON snapshots of guild channels and roles for use before destructive changes.

Related MCP server: Discord MCP Server

Safety checks

• Every Discord write requires confirm: true and a non-empty reason.

• Destructive operations require a backup ID unless allowWithoutBackup: true is set.

• DISCORD_GUILD_ID can restrict requests to one guild.

• Backups are snapshots only. This project does not restore deleted Discord data.

Requirements

• Node.js 20 or newer.

• A Discord application with a bot.

• An MCP client that can start local stdio servers.

Setup

1. Create an application and bot in the Discord Developer Portal.

2. Copy the bot token. Keep it private and do not commit it.

3. Invite the bot to your server with the permissions it needs.

4. Copy the environment template:

   Copy-Item .env.example .env.local

5. Set DISCORD_BOT_TOKEN in .env.local. Set DISCORD_GUILD_ID if the bot can access more than one guild.

6. Install dependencies and build the server:

   npm install
   npm run typecheck
   npm run build

Environment variables

Bot permissions

Start with the smallest set of permissions your workflow needs:

• View Channels

• Read Message History

• Send Messages

Add these only when you use the related tools:

• Manage Channels

• Manage Roles

• Manage Messages

• Kick Members

• Ban Members

• Create Public Threads

• Send Messages in Threads

Discord will not let the bot manage roles above its highest role, even when Manage Roles is enabled.

Run the server

Build first, then start the compiled server:

npm start

For development, run the TypeScript entry point directly:

npm run dev

An MCP stdio server usually looks idle in the terminal. The MCP client communicates with it through standard input and output.

MCP client configuration

Use the included mcp-client-config.example.json as a starting point. Replace both /path/to/discord-mcp-server values with the absolute path to your checkout.

The resulting configuration looks like this:

{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": [
        "/path/to/discord-mcp-server/dist/index.js"
      ],
      "cwd": "/path/to/discord-mcp-server"
    }
  }
}

The MCP client must be able to read .env.local from the configured working directory.

Available tools

Read tools:

• discord_list_guilds

• discord_get_guild

• discord_list_channels

• discord_list_roles

• discord_get_user_profile

• discord_get_member_profile

• discord_get_guild_member_avatar

• discord_read_messages

• discord_backup_guild

Messaging tools:

• discord_send_message

• discord_delete_message

• discord_create_forum_post

Channel tools:

• discord_create_text_channel

• discord_create_voice_channel

• discord_create_forum_channel

• discord_create_announcement_channel

• discord_create_stage_channel

• discord_create_category

• discord_rename_channel

• discord_update_channel

• discord_move_channel

• discord_delete_channel

• discord_set_channel_permissions

Role tools:

• discord_create_role

• discord_rename_role

• discord_delete_role

• discord_assign_role

• discord_remove_role

Moderation tools:

• discord_kick_member

• discord_ban_member

Input rules and options

Guild-scoped tools accept an optional guildId. The server uses DISCORD_GUILD_ID when it is set. Otherwise, guildId is only optional when the bot can access exactly one guild.

All Discord write tools accept:

• confirm: must be true.

• reason: at least three characters. Discord receives this as the audit-log reason when the API supports one.

Destructive tools also accept:

• backupId: the filename returned by discord_backup_guild for the same guild.

• allowWithoutBackup: set to true to bypass backup verification.

Other options worth noting:

• discord_create_forum_post accepts autoArchiveDurationMinutes with one of 60, 1440, 4320, or 10080.

• discord_update_channel accepts name, topic, nsfw, rateLimitPerUser, bitrate, and userLimit.

• discord_move_channel accepts parentId, position, and lockPermissions.

• discord_set_channel_permissions accepts a targetId plus allow and deny permission-name arrays.

• discord_create_role accepts color, mentionable, hoist, and a list of Discord permission names. New roles have no permissions unless you provide them.

• discord_ban_member accepts deleteMessageSeconds from 0 to 604800.

• Channel creation tools accept parentId where Discord supports categories. Text-like channels also accept topic; voice channels accept userLimit.

Tool call examples

Every write needs an explicit confirmation and reason:

{
  "confirm": true,
  "reason": "Requested by the server owner"
}

Destructive calls also need the ID returned by discord_backup_guild:

{
  "confirm": true,
  "reason": "Removing an unused channel",
  "backupId": "2026-06-07T03-12-00-000Z-123456789012345678.json"
}

You can intentionally skip backup verification with allowWithoutBackup: true. Use that only when you have another recovery plan.

Development

npm run dev
npm run typecheck
npm run build

Before opening a pull request, run the type check and build, review the diff, and confirm that no .env, .env.local, backup, or generated dist files are staged.

Project structure

src/index.ts                    MCP server implementation
.env.example                    Environment variable template
mcp-client-config.example.json  MCP client configuration template

Security

• Never commit .env or .env.local.

• If a token is exposed, revoke it in the Discord Developer Portal and create a new one.

• Use a bot token, never a Discord user token.

• Keep bot permissions narrow and review them when adding a new tool.

• Treat files in backups/ as private. They can contain guild names and IDs, the owner ID, channel names, and role names.

License

MIT. See LICENSE.