better-discord-mcp

better-discord-mcp

An MCP server that lets an AI client (Claude Desktop / Claude Code) read and control Discord through a BetterDiscord plugin. It drives your logged-in Discord client, so it can read any channel you can see, send messages, and perform moderation (ban / kick / timeout / delete) wherever your account has permission.

Claude ──stdio──▶ MCP server ──WebSocket(127.0.0.1:6473)──▶ BD plugin ──▶ Discord

⚠️ Important: Terms of Service

This automates a user account, not a bot account. Automating a user account ("selfbotting") violates Discord's Terms of Service and can result in account termination, regardless of intent. Use only on your own or explicitly authorized servers, ideally with a test account. You accept the risk.

For ToS-compliant moderation, build a real Discord bot instead — but that cannot "see your client" the way this does.

Setup

1. Install the BetterDiscord plugin

• Copy plugin/DiscordMCP.plugin.js into your BetterDiscord plugins folder:
• Windows: %AppData%\BetterDiscord\plugins\
• Open Discord → Settings → Plugins → enable DiscordMCP.
• It will keep trying to connect to the bridge every 3s (toast shows status).

2. Install server deps

npm install

3. Register the MCP server with your client

Claude Code: `` claude mcp add discord -- node "/absolute/path/to/better-discord-mcp/server/index.js" ``

Claude Desktop (claude_desktop_config.json): ``json { "mcpServers": { "discord": { "command": "node", "args": ["/absolute/path/to/better-discord-mcp/server/index.js"] } } } ``

The server hosts the WebSocket bridge; the plugin connects to it. Start order doesn't matter — the plugin auto-reconnects. Use the discord_status tool to confirm the link is up.

Tools

Read / info | Tool | Purpose | |------|---------| | discord_status | Is the plugin connected? | | discord_get_context | Current guild / channel / user | | discord_get_guilds | List your servers | | discord_get_channels | Channels in a guild | | discord_get_messages | Recent messages in a channel | | discord_search_messages | Search a guild or channel | | discord_get_user | User / guild-member info | | discord_get_roles | List a guild's roles | | discord_get_dms | List open DM channels |

Messaging | Tool | Purpose | |------|---------| | discord_send_message | Send a message | | discord_edit_message | Edit your own message | | discord_add_reaction / discord_remove_reaction | React to a message | | discord_trigger_typing | Show typing indicator | | discord_open_dm | Open/fetch a DM with a user |

Moderation (🔒 gated — need confirm:true) | Tool | Purpose | |------|---------| | discord_delete_message 🔒 | Delete a message | | discord_purge_messages 🔒 | Bulk-delete recent messages (<14 days) | | discord_ban_user 🔒 | Ban (needs Ban Members) | | discord_kick_user 🔒 | Kick (needs Kick Members) | | discord_timeout_user 🔒 | Timeout / un-timeout a member | | discord_add_role | Add a role (Manage Roles) | | discord_remove_role 🔒 | Remove a role (Manage Roles) |

🔒 = destructive: the first call returns a confirmation preview and does nothing; re-call with confirm:true to execute. Disable with DISCORD_MCP_REQUIRE_CONFIRM=false.

Full surface (~100 tools)

This exposes essentially all of Discord's REST-driven features. Beyond the common tools above, there are named tools for: audit log, bans (list/get/unban), threads (create/edit/join/leave/members/archived lists), forum posts, channel permission overwrites, channel/role reordering, polls, replies & embeds, crossposting, scheduled events, AutoMod rules, stickers, integrations, webhooks (create/edit/execute), invites (resolve/join), friends/block/notes, status, prune, voice mute/deafen & status, welcome screen, vanity url, and more. See COVERAGE.md for the complete map and what is not reachable.

discord_request — raw escape hatch

For anything without a named tool (templates, onboarding, slash-command registration, brand-new endpoints), call any REST endpoint directly:

discord_request(method="post", path="/guilds/123/templates", body={ "name": "..." })

Non-GET raw calls are also gated by the confirmation rule.

What is NOT possible via this bridge

Voice audio (joining/streaming/listening), live event streaming, and the full online-member list are gateway/WebRTC, not REST — this bridge can't drive them. It can move/mute/deafen members and set voice channel status. Use polling (get_messages) instead of live message events.

Config

• DISCORD_MCP_PORT (default 6473) — must match this.port in the plugin.
• DISCORD_MCP_TIMEOUT (default 15000 ms) — per-request timeout.
• DISCORD_MCP_REQUIRE_CONFIRM (default true) — gate destructive tools.

How API calls are authenticated

Current Discord builds obfuscate the internal REST client (getAPIBaseURL) and the token module (getToken), so the plugin doesn't rely on them. Instead it sniffs your Authorization header from Discord's own outgoing requests (hooking XMLHttpRequest/fetch) and then calls https://discord.com/api/v9 directly with fetch. This is version-proof — it survives Discord updates.

One consequence: the token is only captured after Discord makes an authenticated request. Most live traffic goes over the gateway WebSocket, so right after enabling the plugin you may need to switch channels once to trigger a REST call. After that the token is cached for the session.

Troubleshooting

• not connected: Discord must be running with the plugin enabled. Check the

plugin toast / Discord devtools console (Ctrl+Shift+I) for errors.

• Auth token not captured yet: click into a different channel once (forces a

REST request the plugin can read the token from), then retry.

• Discord API 401/403: your account lacks permission for that action, or the

captured token is stale — toggle the plugin off/on and switch channels.

• Diagnostics: discord_request(path="__debug__") dumps module/token state

for debugging without touching devtools.