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

{
  "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.