discord-mcp
Allows operating a Discord bot through Discord's REST API v10, providing tools to read channels and message history, search messages, post and reply, manage channels, threads, and roles, moderate members, and read the audit log.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@discord-mcp what's been discussed in #trading-ideas this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
discord-mcp
An MCP server that lets Claude — or any MCP client — operate a Discord bot. Read channels, search history, post and reply, manage channels, threads and roles, moderate members, and read the audit log.
35 tools. Python 3.12+, no framework beyond the MCP SDK and httpx. Runs as a local
subprocess of your client, holds no state, and makes plain HTTPS calls to Discord's REST
API v10 — no gateway connection, nothing running in the background.
You: "What's been discussed in #trading-ideas this week?"
Claude: [discord_read_messages] → summarises the last 40 messages
You: "Reply to Sam's question about position sizing."
Claude: [discord_send_message] → posts as your bot, mentions suppressed by defaultSetup ← the Discord portal bit, in detail
What it can and can't do
Can: anything the bot's role is permitted to do, in any server the bot has been invited to. One running server handles as many Discords as the bot is in.
Can't, and these are not bugs:
Why | |
See a server the bot isn't in | Discord has no such thing. Someone with Manage Server has to add the bot. There is no way in from outside. |
Act as you | It acts as the bot, with the bot's name and avatar. Automating a human account ("self-botting") breaks Discord's ToS and gets accounts banned — don't ask it to, it can't. |
React to events live | No gateway connection, by design. It answers questions; it isn't notified of new messages. See architecture.md. |
Use Discord's message search | That endpoint is user-accounts-only. |
Read message text without the intent | Message Content is a privileged intent. Switch it on or every message comes back blank — see step 3 of Setup. |
Related MCP server: mcp-discord
Setup
Four steps, about five minutes. Step 1 is the one people get wrong.
1. Create the bot
Go to https://discord.com/developers/applications → New Application → give it a name (this becomes the bot's display name).
Bot tab → Reset Token → copy it somewhere safe. Discord shows it once. If you lose it, reset again — resetting invalidates the old one.
Still on the Bot tab, scroll to Privileged Gateway Intents and enable:
Message Content Intent — required. Without it, every message's text arrives as an empty string, with no error. This catches almost everyone.
Server Members Intent — only needed for
discord_list_members. Member search works without it.
Click Save Changes.
2. Invite it to your server
OAuth2 tab → copy your Client ID (also shown as Application ID on the General
Information tab), then open one of these URLs with CLIENT_ID replaced:
Everything the tools need — read, post, manage channels and roles, moderate:
https://discord.com/oauth2/authorize?client_id=CLIENT_ID&scope=bot&permissions=1494917180630Read and post only — no moderation, no channel or role management. A sensible place to start:
https://discord.com/oauth2/authorize?client_id=CLIENT_ID&scope=bot&permissions=274878024896Read only — view channels, read history, read the audit log:
https://discord.com/oauth2/authorize?client_id=CLIENT_ID&scope=bot&permissions=66688Open the URL, choose your server, authorise. The bot appears in the member list, offline — that's correct, it has no gateway connection.
You can widen permissions later in Server Settings → Roles without re-inviting. If you prefer to pick by hand, the OAuth2 URL Generator on that tab builds the URL for you.
3. Install and configure
git clone https://github.com/lburnscissp/discord-mcp.git
cd discord-mcp
uv sync
cp .env.example .envPut your token in .env:
DISCORD_BOT_TOKEN=your-token-here
# Optional: a default server, so tools don't need guild_id every call
DISCORD_GUILD_ID=To get a server ID: Discord → User Settings → Advanced → Developer Mode on, then right-click the server icon → Copy Server ID. Leaving it blank is fine — see Using it with several servers.
Check it works, with no network calls and no token needed:
uv run pytest(No uv? pip install -e ".[dev]" in a 3.12+ virtualenv does
the same job; replace uv run with your venv's python below.)
4. Register with your MCP client
Claude Code:
claude mcp add discord -- uv --directory "$(pwd)" run discord-mcpClaude Desktop — add to claude_desktop_config.json
(macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"discord": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/discord-mcp", "run", "discord-mcp"]
}
}
}Restart the client, then ask it: "discord whoami". You should get the bot's name back. Then "list my discord channels".
Tools
Read tools take response_format: markdown (default, compact and readable) or json
(full structured data). Tools that change a server take reason, which Discord records in
the audit log. Every tool is annotated read-only / destructive so your client can decide
what to confirm.
Servers
Tool | |
| Identify the bot. The cheapest check that your token works. |
| Every server the bot is in. Where you find a |
| Name, owner, member and online counts, creation date. |
Channels and threads
Tool | |
| Channels and categories, filterable by kind or name. Where you find a |
| One channel or thread in detail. |
| New channel or category. Needs Manage Channels. |
| Rename, retopic, move, set slowmode; archive or lock a thread. |
| Destructive. Deletes the channel and all its messages. |
| Active (unarchived) threads. |
| From a message, or standalone. |
Messages
Tool | |
| Recent messages with cursor pagination. |
| One message, with attachments, embeds and reactions. |
| Find a phrase in a channel's recent history, optionally by author. |
| Post or reply. Mentions suppressed unless |
| Edit a message the bot sent (Discord won't let bots edit others'). |
| Destructive. One message. |
| Add or remove the bot's reaction. |
| Pinned messages. |
| Pin or unpin. |
| Direct message a user. |
Members
Tool | |
| Prefix search on username or nickname. Turns a name into an ID. |
| Full member list. Needs the Server Members intent. |
| Nickname, roles, join date, timeout status. |
| Add or remove a role. |
Roles
Tool | |
| All roles, highest first, with IDs and permission bitfields. |
| New role, with colour and permissions. |
| Change name, colour, flags or permissions. |
| Destructive. Removes it from every member. |
Moderation
Tool | |
| Mute for up to 28 days. |
| Destructive. Removes them; they can rejoin with an invite. |
| Destructive. Blocks rejoining; can delete their recent messages. |
| Lift a ban. |
| Who's banned, and the reason recorded. |
| Destructive. 2–100 messages at once, under 14 days old. |
| Who did what, and why. Answers "who deleted that channel?" |
Using it with several servers
Every server-scoped tool takes an optional guild_id. The resolution order is simple:
the
guild_idyou pass, if you pass one;otherwise
DISCORD_GUILD_IDfrom.env;otherwise an error telling you to run
discord_list_guilds.
So one installation covers every server the bot is in. Set DISCORD_GUILD_ID to whichever
you use most and it becomes the default — "post this in #general" needs no ID — while
"list the channels in my other server, ID 123…" still works. Leave it unset if you treat
several equally; the client will pass the ID each time.
Running several bots (different identities, different servers) means registering the
server twice with different .env files — or two clones. The process reads its token at
startup.
Troubleshooting
Symptom | Cause and fix |
| Wrong or stale token. Reset it in the portal (Bot → Reset Token) and update |
| No |
Every message's text is empty | Message Content Intent is off — Discord blanks text, attachments and embeds together, with no error. Portal → Bot → Privileged Gateway Intents → enable → Save Changes. Takes effect on the next call; no re-invite needed. The read tools say so when they spot it. |
Messages shown as | Not an error — those are Discord's own join/pin/boost notices, which never have text. Real messages appear alongside them. |
| The bot isn't in that server, or can't see that channel. Check channel-level permission overrides, not just the role. |
| The role lacks the permission. For role changes, also check hierarchy: a bot can't touch a role positioned above its own. Drag its role higher in Server Settings → Roles. |
| Server Members Intent is off. Or use |
Bulk delete fails | Messages older than 14 days — Discord's limit, not ours. Delete them individually. |
Bot shows as offline | Expected. No gateway connection; it works over HTTP. |
Tools don't appear in the client | Check the client's MCP logs. Run |
Deeper debugging:
uv run discord-mcp -v # verbose logs on stderr
npx @modelcontextprotocol/inspector uv --directory . run discord-mcp # poke tools by hand
uv run discord-mcp --http --port 8765 # HTTP instead of stdioSecurity
The token is the whole bot. Anyone holding it can do everything the bot can, in every server it's in.
.envis git-ignored;*.key,*.pem,*credentials*and*secrets*are too. Never paste it into an issue, a chat, or a commit.If a token leaks, reset it. Deleting the file isn't enough — a committed secret stays in git history. Portal → Bot → Reset Token invalidates the old one immediately.
Give the bot the narrowest permissions you can live with. Start with the read-only or read-and-post invite above; widen later in Server Settings when something fails.
Mentions are suppressed by default so model-generated text can't accidentally
@everyone. Overriding that is explicit (allow_mentions=true).The HTTP transport binds to 127.0.0.1 only — this process holds a token and must not be reachable from your network.
Destructive tools are annotated so your client can require confirmation. Treat that as UX, not a security boundary: a client is free to ignore annotations, so don't give the bot Ban Members in a server where a wrong call would be a disaster.
Project layout
src/discord_mcp/
client.py every HTTP call: auth, 429 retry, Discord errors → actionable messages
formatting.py snowflake timestamps, Markdown/JSON renderers, pagination envelopes
server.py entry point: stdio (default) or --http
tools/
_common.py shared server instance, argument types, annotations — read this first
guilds.py channels.py messages.py members.py roles.py moderation.py
tests/ 34 tests, Discord mocked with respx, no token required
docs/ architecture.md, adding-a-tool.mdEvery module opens with a docstring explaining the Discord behaviour it's built around. docs/architecture.md is the guided tour.
Licence
MIT. Not affiliated with or endorsed by Discord.
Available Tools
35 toolsdiscord_ban_memberADestructive
Ban a user from the server (they cannot rejoin until unbanned), optionally deleting their recent messages.
Needs Ban Members. Confirm with the user before calling.
Returns: Confirmation.
Inputs: user_id (required), reason, guild_id, delete_message_days. Returns: result
discord_bulk_delete_messagesADestructive
Delete 2–100 messages from one channel in a single call. Irreversible. Needs Manage Messages.
Discord refuses messages older than 14 days — delete those one at a time with
discord_delete_message. Confirm with the user before calling.
Returns: Confirmation with the count deleted.
Inputs: channel_id (required), message_ids (required), reason. Returns: result
discord_create_channelA
Create a channel or category in a server. Needs the Manage Channels permission.
Returns: Confirmation with the new channel's label and ID.
Inputs: name (required), nsfw, type, topic, +3 more. Returns: result
discord_create_roleA
Create a role. Needs Manage Roles. New roles appear at the bottom of the hierarchy.
Returns: Confirmation with the role ID.
Inputs: name (required), color, hoist, reason, +3 more. Returns: result
discord_create_threadA
Start a thread — from an existing message, or standalone in a channel.
Returns: Confirmation with the thread ID. Post into it with discord_send_message using
the thread ID as channel_id.
Inputs: name (required), channel_id (required), reason, private, +2 more. Returns: result
discord_delete_channelADestructive
Permanently delete a channel or thread and every message in it. Irreversible.
Confirm with the user before calling. Needs Manage Channels.
Returns: Confirmation naming what was deleted.
Inputs: channel_id (required), reason. Returns: result
discord_delete_messageADestructive
Delete one message. Deleting others' messages needs Manage Messages. Irreversible.
For 2–100 recent messages at once use discord_bulk_delete_messages.
Returns: Confirmation.
Inputs: channel_id (required), message_id (required), reason. Returns: result
discord_delete_roleADestructive
Delete a role, removing it from every member. Irreversible — confirm with the user first.
Returns: Confirmation.
Inputs: role_id (required), reason, guild_id. Returns: result
discord_edit_channelAIdempotent
Rename, retopic, move, set slowmode on a channel — or archive/lock a thread.
Only the fields you pass are changed. Needs Manage Channels (Manage Threads for threads).
Returns: Confirmation listing the fields changed.
Inputs: channel_id (required), name, nsfw, topic, +6 more. Returns: result
discord_edit_messageAIdempotent
Replace the text of a message the bot sent. Cannot edit other users' messages.
Returns: Confirmation.
Inputs: content (required), channel_id (required), message_id (required). Returns: result
discord_edit_roleAIdempotent
Change a role's name, color, hoist/mentionable flags, or permissions. Only passed fields change.
Returns: Confirmation listing the fields changed.
Inputs: role_id (required), name, color, hoist, +4 more. Returns: result
discord_get_audit_logARead-onlyIdempotent
Read the server's audit log — who did what (bans, kicks, deletions, channel/role changes) and why.
Needs View Audit Log. Use to answer "who deleted that channel" or "why was X banned".
Returns: Markdown table (time, actor, action, target, reason) or JSON list of entries
{id, time, actor{id, username}, action, target_id, reason, changes}.
Inputs: limit, action, user_id, guild_id, +1 more. Returns: result
discord_get_channelARead-onlyIdempotent
Get one channel or thread: type, topic, parent, slowmode, and for threads the archive/lock state.
Returns: Markdown bullet list or JSON channel object.
Inputs: channel_id (required), response_format. Returns: result
discord_get_guildBRead-onlyIdempotent
Get details for one server: name, owner, member and online counts, creation date.
Returns: Markdown summary or JSON with id, name, owner_id, description,
approximate_member_count, approximate_presence_count, created_at, premium_tier.
Inputs: guild_id, response_format. Returns: result
discord_get_memberARead-onlyIdempotent
Get one member's profile in this server: nickname, roles, join date, timeout status.
Returns: Markdown bullets or JSON member object.
Inputs: user_id (required), guild_id, response_format. Returns: result
discord_get_messageARead-onlyIdempotent
Fetch one message by ID, including attachments, embeds and reactions.
Returns: Markdown block or JSON message object (same shape as discord_read_messages items).
Inputs: channel_id (required), message_id (required), response_format. Returns: result
discord_kick_memberADestructive
Remove a member from the server. They can rejoin with an invite. Needs Kick Members.
Confirm with the user before calling.
Returns: Confirmation.
Inputs: user_id (required), reason, guild_id. Returns: result
discord_list_bansARead-onlyIdempotent
List banned users and the reason recorded for each. Needs Ban Members.
Returns: Markdown table (user, reason) or JSON list of {user_id, username, reason}.
Inputs: limit, guild_id, response_format. Returns: result
discord_list_channelsARead-onlyIdempotent
List a server's channels and categories, optionally filtered by kind or name.
The usual way to find a channel_id before reading or posting. Threads are not
included — use discord_list_threads.
Returns: Markdown table (name, type, ID, category, topic) or JSON list of channel objects
with id, name, type, parent_id, position, topic.
Inputs: type, guild_id, name_contains, response_format. Returns: result
discord_list_guildsARead-onlyIdempotent
List every server (guild) the bot has been invited to.
A bot only sees servers where someone with Manage Server added it — it cannot browse
servers it isn't in. Use this to find a guild_id.
Returns: Markdown table of name and ID, or JSON list of {id, name, owner, permissions}
where `owner` means the bot's owner owns the server.
Inputs: response_format. Returns: result
discord_list_membersARead-onlyIdempotent
List server members in join order with cursor pagination.
Requires the Server Members privileged intent to be enabled for the bot in the
developer portal; otherwise Discord returns Missing Access.
Returns: Markdown table or JSON envelope {count, limit, has_more, next_after, items}.
Inputs: after, limit, guild_id, response_format. Returns: result
discord_list_pinsARead-onlyIdempotent
List the pinned messages in a channel (max 50).
Returns: Markdown messages or JSON list, same shape as discord_read_messages items.
Inputs: channel_id (required), response_format. Returns: result
discord_list_rolesARead-onlyIdempotent
List a server's roles from highest to lowest, with IDs, colors and flags.
Use to find role_id for discord_set_member_role. Permission bitfields are in the JSON output.
Returns: Markdown table (name, ID, color, hoisted, mentionable, managed) or JSON list.
Inputs: guild_id, response_format. Returns: result
discord_list_threadsARead-onlyIdempotent
List active (unarchived) threads in a server, optionally only under one channel.
Returns: Markdown table (name, ID, parent, messages, members) or JSON list.
Archived threads are not included.
Inputs: guild_id, channel_id, response_format. Returns: result
discord_pin_messageBIdempotent
Pin or unpin a message in its channel. Needs Manage Messages.
Returns: Confirmation.
Inputs: channel_id (required), message_id (required), action, reason. Returns: result
discord_reactAIdempotent
Add or remove the bot's own reaction on a message.
Returns: Confirmation.
Inputs: emoji (required), channel_id (required), message_id (required), action. Returns: result
discord_read_messagesARead-onlyIdempotent
Read recent messages from a channel or thread, newest first, with cursor pagination.
Needs the Message Content intent enabled for the bot or every message reads as empty.
Pass only one of before / after / around.
Returns: Markdown — each message as author, time, ID, text, attachments, reactions,
oldest at top; a footer gives the `before` cursor for the next page. JSON — envelope
{count, limit, has_more, next_before, items:[{id, channel_id, author{id, username,
display_name, bot}, content, timestamp, edited_timestamp, pinned, attachments?,
embeds?, reactions?, reply_to?, thread_id?}]}.
Inputs: channel_id (required), after, limit, around, +2 more. Returns: result
discord_search_membersARead-onlyIdempotent
Find server members whose username or nickname starts with a string.
The quickest way to turn a name into a user_id. Does not need the privileged
Server Members intent (unlike discord_list_members).
Returns: Markdown table (member, roles, joined) or JSON list of {user_id, username,
display_name, nick, bot, roles, joined_at, timed_out_until}.
Inputs: query (required), limit, guild_id, response_format. Returns: result
discord_search_messagesARead-onlyIdempotent
Find messages in a channel containing a phrase, optionally by one author.
Discord's search API is not available to bots, so this scans the most recent
`max_scan` messages page by page (100 per API call) and filters locally. For "what
did X say about Y last week" this is the tool; for older history raise max_scan.
Returns: Matching messages (Markdown or JSON, same shape as discord_read_messages) plus
how many messages were scanned and the oldest one reached.
Inputs: query (required), channel_id (required), limit, max_scan, +2 more. Returns: result
discord_send_dmA
Send a direct message from the bot to a user.
Fails if the user has DMs from server members/bots disabled. Confirm with the user
before sending — DMs feel more personal than channel posts.
Returns: Confirmation with the DM channel ID (reuse it with discord_read_messages to see replies).
Inputs: content (required), user_id (required). Returns: result
discord_send_messageA
Post a message to a channel, thread, or DM channel as the bot. Optionally as a reply.
Visible to everyone in the channel immediately — confirm wording with the user first.
Mentions do not ping unless allow_mentions is true.
Returns: Confirmation with the new message ID and a jump link.
Inputs: content (required), channel_id (required), reply_to, allow_mentions, +1 more. Returns: result
discord_set_member_roleAIdempotent
Give a role to a member, or take it away.
Needs Manage Roles, and the bot's own top role must sit above the role being assigned.
Returns: Confirmation.
Inputs: role_id (required), user_id (required), action, reason, +1 more. Returns: result
discord_timeout_memberAIdempotent
Time out a member (no posting, reacting or voice) for up to 28 days, or lift a timeout with minutes=0.
Needs Moderate Members. Confirm with the user before applying.
Returns: Confirmation with the time the timeout ends.
Inputs: minutes (required), user_id (required), reason, guild_id. Returns: result
discord_unban_memberAIdempotent
Lift a ban so the user can rejoin. Needs Ban Members.
Returns: Confirmation.
Inputs: user_id (required), reason, guild_id. Returns: result
discord_whoamiARead-onlyIdempotent
Identify the bot account this server is running as.
Use first to confirm the token works, and to learn the bot's own user ID (needed to
tell the bot's messages apart from other people's).
Returns: `Name (@username, ID) [bot]` plus the bot's creation date.
Errors: `Error: Invalid bot token…` if DISCORD_BOT_TOKEN is wrong or missing.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 35 tools
Each tool targets a distinct resource plus action (list/get/create/edit/delete on channels, roles, members, messages), and descriptions explicitly disambiguate the closest pairs like discord_delete_message vs discord_bulk_delete_messages and discord_search_members vs discord_list_members. The channel/thread overlap is handled by clear notes (e.g. discord_get_channel covers threads, discord_send_message accepts a thread ID).
Every tool follows a strict discord_verb_noun pattern (discord_list_channels, discord_create_role, discord_ban_member) with the same namespace prefix. No camelCase or naming drift anywhere in the set.
35 tools is heavy and at the upper end of what an agent can reliably select from, even though Discord is a genuinely broad domain. Most tools earn their place, but some (pins, reactions, bulk delete) could be consolidated.
Coverage is strong across messages, channels, threads, roles, members, moderation, and the audit log, including lifecycle operations like edit/delete and unban. Minor gaps remain (invites, emoji/sticker/webhook management, guild settings), but core workflows have no dead ends.
Maintenance
Related MCP Connectors
Discord MCP server for ChatGPT, Claude and any AI agent: list servers and channels, read channel messages, search messages, send message, reply to message, send DM, read mentions and assign role in your own Discord account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Discord yourself; Cotlet does not store your password and you need no Discord API key. About the official Discord API: Yes, Discord has an official API for bots and OAuth2 apps, but it acts as a bot that a server manager adds, not as you, and Discord has no official MCP server for it (checked 5 Nov 2026). The MCP server on Discord's docs site only searches documentation. Setup and FAQ: https://cotlet.dev/integrations/discord-api-mcp-server
- Discortics - Discord BotDeprecatedcom.discortics
Set up and manage your Discord server from MCP: channels, roles, verification, tickets and security.
Control your Discord community: send/read messages, manage channels and forums, and handle webhook…
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server that provides native Discord tools for Claude Code, enabling bidirectional communication with remote agents or humans via the Discord REST API. It allows users to send messages, read channel history, and manage reactions directly from their local environment.63MIT
- AlicenseAqualityDmaintenanceAn MCP server providing 26 tools for Discord API interactions, enabling message management, moderation, channel operations, and server inspection through Claude Code, Paperclip agents, or other MCP-compatible clients.26MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to control a logged-in Discord account through 70+ tools: browsing guilds and channels, sending and reacting to messages, moderating members, managing channels, roles, emojis, and webhooks, plus searching and analyzing captured message history stored in SQLite. Authenticates using tokens already cached by the local Discord client, requiring no bot account or manual token setup.141 npmMIT
- AlicenseAqualityCmaintenanceWraps the REST API of a self-hosted Discord Agent Proxy so MCP clients like Claude and Cursor can drive a Discord account through natural language. Exposes tools for listing servers, channels, and members, and for sending, reading, editing, searching, reacting to, pinning, and deleting messages, plus direct messages.1533 PyPIMIT