discord-server-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| DISCORD_GUILD_ID | No | Default server when the bot is in several. | |
| DISCORD_PRESENCE | No | `off` keeps the bot offline (no gateway connection). | on |
| DISCORD_TOOLSETS | No | Comma-separated tool groups to offer, e.g. `messages,channels`. | all |
| DISCORD_BOT_TOKEN | No | A bot token. Bots added from the chat or with `init` are saved in `~/.discord-mcp/bots.json`. A token on the first line of `~/.discord-mcp/token.txt` is also read; `DISCORD_TOKEN_FILE` changes that path. | |
| DISCORD_ACTIVE_BOT | No | Name or id of the bot used when a request names no server (`use_bot` sets it). Defaults to the first bot. | |
| DISCORD_TOKEN_FILE | No | Path to a file whose first line contains a bot token. | ~/.discord-mcp/token.txt |
| DISCORD_WRITE_MODE | No | `preview`: every change is only shown. `readonly`: no changing tools at all. | full |
| DISCORD_SERVER_BOTS | No | JSON mapping of server id to bot name/id, choosing the bot per server, e.g. `{"<server id>": "<bot>"}` (`set_server_bot` sets it). | |
| DISCORD_PRESENCE_TEXT | No | Status text, e.g. `My Server` shows "Watching My Server". | |
| DISCORD_PRESENCE_TYPE | No | Presence activity type: `playing`, `listening`, `watching`, `competing`, or `custom`. | watching |
| DISCORD_ALLOWED_GUILDS | No | Comma-separated server ids the tools may touch. | all |
| DISCORD_PRESENCE_STATUS | No | Presence status: `online`, `idle`, `dnd`, or `invisible`. | online |
| DISCORD_CONFIRM_DESTRUCTIVE | No | Permanent actions (delete, kick, ban, purge, prune…) return a preview until called with `confirm: true`. | on |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tools to manage Discord servers through one or more bots. Start with setup_check (bots, their servers, what to fix); new bots are added with add_bot, which asks for the token in a private box (never ask for it in chat). Tools use the bot that is in the server you name. Call get_server before changing a server. Channels, roles and members can be named instead of using ids. Before changing the server or sending messages, show the user what will happen and get their confirmation; deleting is permanent. Nobody is pinged unless ping_roles/ping_users/ping_everyone are set. Every write tool accepts dry_run to preview; permanent actions need confirm: true. To build or complete a server show preview_blueprint, then apply_blueprint. Only the core tools are on at first: when a task needs more (role menus, welcomes, tickets, live events, background jobs and backups, AutoMod and moderation, webhooks and DMs, emojis, scheduled events, onboarding, raw API calls), call enable_tools with the pack first; if the new tools do not appear, call them through use_tool. Role menus, welcomes and tickets keep working while this server runs. Set up only the features the user chose, with the options they chose; when a feature has variants (where a log goes, which commands, who gets alerts), ask before building, and show the plan first.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| setup_checkA | Start here. Shows every configured bot with the servers it is in, what to fix (permissions, role position, intents), invite links, and this tool's settings. With no bot yet it gives the steps to create one. |
| list_botsA | List the configured bots, which one is used by default, and how many servers each is in. |
| add_botA | Add a Discord bot (several are supported) without the token ever going through the chat. method "box" (default) asks the app to show a private input box; if the app cannot, or the box is closed, it opens a one-time page on this computer (a http://127.0.0.1 link) where the user pastes the token in their browser. The token is checked and saved, and the bot can be used at once. Call it after the user created the bot (setup_check has the steps). |
| use_botB | Choose the default bot (used when a request does not name a server). Tools still pick the right bot automatically when a server is named. |
| remove_botA | Forget a saved bot on this computer (the bot itself stays on Discord and in its servers). |
| set_server_botB | Choose which bot to use in a server that several configured bots are in (saved on this computer). "auto" goes back to the default bot. |
| bot_invite_linkA | The link that adds a bot to a server the user manages (Administrator by default, or chosen permissions). |
| enable_toolsA | Turn on more Discord tools for this conversation. Only the core tools are on at first; call this as soon as a task needs one of these packs: automations (role menus, welcome messages with auto-roles, support tickets and their history, the server's own slash commands, staff slash commands (/ban, /lock, /purge…), moderation logs and searching them, staff alerts, support forums, rules (when X happens do Y), member verification, scheduled messages); live (what is happening now, waiting for a reply, mention or join); jobs (background jobs: message backups and restores, roles for many members at once); moderation (AutoMod, locking channels, purging messages, bans list, pruning, audit log, role audit, member export); messaging (webhooks (post with another name), DMs, pins list, announcements publishing, polls and reactions results); organizing (cloning channels, more forum tags, threads, following announcement channels, copying and syncing permissions); server_settings (onboarding, welcome screen, invites list, server stats and activity, bot profile, creating or leaving servers); expressions (emojis, stickers, soundboard, scheduled events, stage, application commands); api (direct Discord API calls for anything else). |
| use_toolA | Call a Discord tool from a pack by name, with its arguments. Use it when enable_tools turned a pack on but this app does not show the new tools yet. |
| configureA | Only when the user asks: change this Discord tool's own settings and save them on this computer: write mode, allowed servers, tool packs on at start, confirmation for permanent actions, default server and the bots' status. Most apply at once; tool groups, read-only mode and the status apply after restarting the app. |
| list_serversA | List every Discord server the configured bots can work on (the servers they were invited to): owner, members, which bot and whether it is administrator there, plus the links to add each bot to another server. |
| get_serverA | Overview of a server: settings, every category with its channels (type, topic, forum tags), roles (top to bottom) and the bot's own permissions. Start here before changing anything. |
| edit_serverC | Change server settings: name, description, icon, banner, splash, verification level, default notifications, content filter, AFK, system and rules channels. |
| create_inviteC | Create an invite link to a channel. |
| create_categoryC | Create a channel category. |
| create_channelA | Create a text, announcement, forum, media, voice or stage channel. Inside a category it takes the category's permissions unless overrides are given. Permission names: CreateInstantInvite, KickMembers, BanMembers, Administrator, ManageChannels, ManageGuild, AddReactions, ViewAuditLog, PrioritySpeaker, Stream, ViewChannel, SendMessages, SendTTSMessages, ManageMessages, EmbedLinks, AttachFiles, ReadMessageHistory, MentionEveryone, UseExternalEmojis, ViewGuildInsights, Connect, Speak, MuteMembers, DeafenMembers, MoveMembers, UseVAD, ChangeNickname, ManageNicknames, ManageRoles, ManageWebhooks, ManageGuildExpressions, UseApplicationCommands, RequestToSpeak, ManageEvents, ManageThreads, CreatePublicThreads, CreatePrivateThreads, UseExternalStickers, SendMessagesInThreads, UseEmbeddedActivities, ModerateMembers, ViewCreatorMonetizationAnalytics, UseSoundboard, CreateGuildExpressions, CreateEvents, UseExternalSounds, SendVoiceMessages, SendPolls, UseExternalApps, PinMessages. |
| edit_channelC | Change a channel, category or thread: name, topic, category, position, slowmode, NSFW, voice settings, forum settings. |
| delete_channelA | Delete a channel, category or thread. Cannot be undone. Channels inside a deleted category are kept, without category. |
| set_permissionsA | Set what a role, @everyone or a member can do in a channel or category (allow, deny, or remove the override). Permission names: CreateInstantInvite, KickMembers, BanMembers, Administrator, ManageChannels, ManageGuild, AddReactions, ViewAuditLog, PrioritySpeaker, Stream, ViewChannel, SendMessages, SendTTSMessages, ManageMessages, EmbedLinks, AttachFiles, ReadMessageHistory, MentionEveryone, UseExternalEmojis, ViewGuildInsights, Connect, Speak, MuteMembers, DeafenMembers, MoveMembers, UseVAD, ChangeNickname, ManageNicknames, ManageRoles, ManageWebhooks, ManageGuildExpressions, UseApplicationCommands, RequestToSpeak, ManageEvents, ManageThreads, CreatePublicThreads, CreatePrivateThreads, UseExternalStickers, SendMessagesInThreads, UseEmbeddedActivities, ModerateMembers, ViewCreatorMonetizationAnalytics, UseSoundboard, CreateGuildExpressions, CreateEvents, UseExternalSounds, SendVoiceMessages, SendPolls, UseExternalApps, PinMessages. |
| reorder_channelsB | Put channels in an order. Give the full order of categories (top to bottom), or the channels of one category in order, or both. |
| set_forum_tagsA | Replace the whole tag list of a forum or media channel. Existing tags keep their emoji unless a new one is given. |
| create_forum_postC | Create a post in a forum or media channel, with tags, embeds, files and link buttons. |
| create_threadB | Start a thread in a text or announcement channel, from a message or on its own. |
| read_messagesA | Read messages of a channel or thread (newest last). Use before/after to page. |
| get_messageA | Read one message in full (content, embeds, files, reactions). |
| send_messageA | Send a message to a channel or thread: text, embeds, files/images (local paths or URLs; show one inside an embed with image "attachment://name.png"), link buttons, a poll, a reply, and pings. Nobody is pinged unless listed in ping_roles/ping_users/ping_everyone. |
| edit_messageA | Edit a message the bot sent: text, embeds, link buttons, files (replaces the attachments when given). |
| delete_messagesA | Delete one or more messages (up to 100). Messages older than 14 days are deleted one by one. |
| pin_messageC | Pin or unpin a message. |
| reactA | Add reactions to a message, or remove them (the bot's own, someone's, one emoji for everyone, or all). |
| list_rolesA | List roles (top to bottom) with colour, permissions and member count hints. |
| create_roleB | Create a role. Permission names: CreateInstantInvite, KickMembers, BanMembers, Administrator, ManageChannels, ManageGuild, AddReactions, ViewAuditLog, PrioritySpeaker, Stream, ViewChannel, SendMessages, SendTTSMessages, ManageMessages, EmbedLinks, AttachFiles, ReadMessageHistory, MentionEveryone, UseExternalEmojis, ViewGuildInsights, Connect, Speak, MuteMembers, DeafenMembers, MoveMembers, UseVAD, ChangeNickname, ManageNicknames, ManageRoles, ManageWebhooks, ManageGuildExpressions, UseApplicationCommands, RequestToSpeak, ManageEvents, ManageThreads, CreatePublicThreads, CreatePrivateThreads, UseExternalStickers, SendMessagesInThreads, UseEmbeddedActivities, ModerateMembers, ViewCreatorMonetizationAnalytics, UseSoundboard, CreateGuildExpressions, CreateEvents, UseExternalSounds, SendVoiceMessages, SendPolls, UseExternalApps, PinMessages. |
| edit_roleA | Edit a role. "permissions" replaces all of them; use add_permissions/remove_permissions to change a few. Permission names: CreateInstantInvite, KickMembers, BanMembers, Administrator, ManageChannels, ManageGuild, AddReactions, ViewAuditLog, PrioritySpeaker, Stream, ViewChannel, SendMessages, SendTTSMessages, ManageMessages, EmbedLinks, AttachFiles, ReadMessageHistory, MentionEveryone, UseExternalEmojis, ViewGuildInsights, Connect, Speak, MuteMembers, DeafenMembers, MoveMembers, UseVAD, ChangeNickname, ManageNicknames, ManageRoles, ManageWebhooks, ManageGuildExpressions, UseApplicationCommands, RequestToSpeak, ManageEvents, ManageThreads, CreatePublicThreads, CreatePrivateThreads, UseExternalStickers, SendMessagesInThreads, UseEmbeddedActivities, ModerateMembers, ViewCreatorMonetizationAnalytics, UseSoundboard, CreateGuildExpressions, CreateEvents, UseExternalSounds, SendVoiceMessages, SendPolls, UseExternalApps, PinMessages. |
| delete_roleC | Delete a role. Cannot be undone. |
| list_membersA | List server members with their roles. Needs the Server Members Intent enabled for the bot in the Developer Portal (Bot tab). |
| get_memberB | Details of one member: names, roles, join date, timeout. |
| set_member_rolesC | Give roles to a member and/or take roles away. |
| timeout_memberA | Time a member out (they cannot talk or react) for a while, or end a timeout with minutes 0. |
| kick_memberA | Remove a member from the server (they can rejoin with an invite). |
| ban_memberB | Ban a user from the server, optionally deleting their recent messages. |
| check_permissionsA | What a member or role can actually do, on the server or in one channel, after roles and channel overrides. Also answers "who can see this channel?" when only a channel is given. |
| search_messagesB | Search recent messages across the server's text channels, forums' active posts and threads (and their titles) for words or an author. |
| import_discord_templateA | Load a Discord server template from a link (discord.new/CODE or discord.com/template/CODE, as shared on template websites) and return it as a blueprint you can show with preview_blueprint, edit, and build with apply_blueprint. Also gives the template's name, description and how many times it was used. |
| list_templatesA | List the built-in server templates for apply_blueprint. |
| preview_blueprintA | Show a visual preview of a server layout before building it: the channel sidebar as members will see it (categories, channel types, topics, forum tags, private areas), the roles with colours and key permissions, and a grid of who can see and write in each channel. With a server, also marks what is new, already there or moved. Use it to let the user approve or ask for changes; then apply_blueprint. |
| export_server_structureA | Export a server's roles, categories, channels, topics, forum tags and permissions as a blueprint (a backup without messages). Optionally save it to a JSON file; apply_blueprint can rebuild from it here or on another server. |
| apply_blueprintA | Build or complete a server from a blueprint: a built-in template (list_templates), a saved export (file), or a layout you write (blueprint: {roles, categories:[{name, overrides, channels:[{name, type, topic, slowmode, tags, overrides}]}], channels}). mode "plan" lists the steps without changing anything; "apply" does them. Only what is missing is created, matching names loosely (emojis and dashes ignored), so it is safe to run again to continue. Nothing is deleted. |
| job_statusC | Progress and result of a background job. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 48 tools
Most tools target a distinct resource+action (create_channel, edit_role, ban_member), and the blueprint family (import_discord_template, preview_blueprint, export_server_structure, apply_blueprint) is clearly delineated. The main friction is two tools both billed as entry points (get_server and setup_check say "Start here"), plus partial overlap between enable_tools, use_tool and configure, which an agent could hesitate between.
Everything is snake_case and the dominant pattern is verb_noun (create_channel, edit_role, delete_messages, set_permissions, search_messages). A handful break the verb-first pattern with noun phrases (setup_check, job_status, bot_invite_link, preview_blueprint) and even invert it (setup_check vs check_permissions), but the vocabulary remains readable and predictable.
48 exposed tools far exceeds the range where an agent can reliably pick without misfires, and several are meta-tools (enable_tools, use_tool, configure) that exist purely to navigate the surface. The gated pack system shows awareness of the problem, but the initial flat list is still very heavy for what is largely Discord CRUD.
Coverage is exceptional: full CRUD for channels, categories, threads, roles, messages, invites, permissions, member moderation, plus search, permission introspection and a complete blueprint import/export/preview/apply lifecycle. Remaining operations (AutoMod, webhooks, DMs, bans list, leaving servers) are deliberately reachable through enable_tools packs, so the domain has no dead ends.