Skip to main content
Glama
discord-mcp

discord-mcp

by lburnscissp

discord-mcp

tests Python 3.12+ MIT licence

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 default

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. discord_search_messages pages back through history and filters locally instead.

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

  1. Go to https://discord.com/developers/applications → New Application → give it a name (this becomes the bot's display name).

  2. Bot tab → Reset Token → copy it somewhere safe. Discord shows it once. If you lose it, reset again — resetting invalidates the old one.

  3. 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=1494917180630

Read 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=274878024896

Read only — view channels, read history, read the audit log:

https://discord.com/oauth2/authorize?client_id=CLIENT_ID&scope=bot&permissions=66688

Open 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 .env

Put 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-mcp

Claude 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

discord_whoami

Identify the bot. The cheapest check that your token works.

discord_list_guilds

Every server the bot is in. Where you find a guild_id.

discord_get_guild

Name, owner, member and online counts, creation date.

Channels and threads

Tool

discord_list_channels

Channels and categories, filterable by kind or name. Where you find a channel_id.

discord_get_channel

One channel or thread in detail.

discord_create_channel

New channel or category. Needs Manage Channels.

discord_edit_channel

Rename, retopic, move, set slowmode; archive or lock a thread.

discord_delete_channel

Destructive. Deletes the channel and all its messages.

discord_list_threads

Active (unarchived) threads.

discord_create_thread

From a message, or standalone.

Messages

Tool

discord_read_messages

Recent messages with cursor pagination.

discord_get_message

One message, with attachments, embeds and reactions.

discord_search_messages

Find a phrase in a channel's recent history, optionally by author.

discord_send_message

Post or reply. Mentions suppressed unless allow_mentions=true.

discord_edit_message

Edit a message the bot sent (Discord won't let bots edit others').

discord_delete_message

Destructive. One message.

discord_react

Add or remove the bot's reaction.

discord_list_pins

Pinned messages.

discord_pin_message

Pin or unpin.

discord_send_dm

Direct message a user.

Members

Tool

discord_search_members

Prefix search on username or nickname. Turns a name into an ID.

discord_list_members

Full member list. Needs the Server Members intent.

discord_get_member

Nickname, roles, join date, timeout status.

discord_set_member_role

Add or remove a role.

Roles

Tool

discord_list_roles

All roles, highest first, with IDs and permission bitfields.

discord_create_role

New role, with colour and permissions.

discord_edit_role

Change name, colour, flags or permissions.

discord_delete_role

Destructive. Removes it from every member.

Moderation

Tool

discord_timeout_member

Mute for up to 28 days. minutes=0 lifts it.

discord_kick_member

Destructive. Removes them; they can rejoin with an invite.

discord_ban_member

Destructive. Blocks rejoining; can delete their recent messages.

discord_unban_member

Lift a ban.

discord_list_bans

Who's banned, and the reason recorded.

discord_bulk_delete_messages

Destructive. 2–100 messages at once, under 14 days old.

discord_get_audit_log

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:

  1. the guild_id you pass, if you pass one;

  2. otherwise DISCORD_GUILD_ID from .env;

  3. 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

Error: Invalid bot token

Wrong or stale token. Reset it in the portal (Bot → Reset Token) and update .env. Note it's the bot token, not the client secret.

Error: DISCORD_BOT_TOKEN is not set

No .env, or the file is somewhere else. It must sit next to pyproject.toml. The server walks up from its own location to find it — the client's working directory doesn't matter.

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 (system: joined the server)

Not an error — those are Discord's own join/pin/boost notices, which never have text. Real messages appear alongside them.

Error: Missing access (50001)

The bot isn't in that server, or can't see that channel. Check channel-level permission overrides, not just the role.

Error: Missing permissions (50013)

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.

Error: Missing access on discord_list_members

Server Members Intent is off. Or use discord_search_members, which doesn't need it.

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 uv run discord-mcp -v by hand — it should sit there silently waiting for input on stdin.

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 stdio

Security

  • The token is the whole bot. Anyone holding it can do everything the bot can, in every server it's in. .env is 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.md

Every 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 tools
discord_ban_memberA
Destructive

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_messagesA
Destructive

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_channelA
Destructive

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_messageA
Destructive

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_roleA
Destructive

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_channelA
Idempotent

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_messageA
Idempotent

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_roleA
Idempotent

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_logA
Read-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_channelA
Read-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_guildB
Read-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_memberA
Read-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_messageA
Read-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_memberA
Destructive

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_bansA
Read-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_channelsA
Read-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_guildsA
Read-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_membersA
Read-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_pinsA
Read-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_rolesA
Read-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_threadsA
Read-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_messageB
Idempotent

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_reactA
Idempotent

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_messagesA
Read-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_membersA
Read-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_messagesA
Read-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_roleA
Idempotent

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_memberA
Idempotent

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_memberA
Idempotent

Lift a ban so the user can rejoin. Needs Ban Members.

Returns: Confirmation.

Inputs: user_id (required), reason, guild_id. Returns: result

discord_whoamiA
Read-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

    A3.9/5.0

    Scored across 35 tools

    Disambiguation5/5

    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).

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An 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.
      6
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      26
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Wraps 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.
      15
      33 PyPI
      MIT