Betterdiscord

An MCP server that lets an AI agent (like Claude) read data from Discord servers through your own account. It pairs with a BetterDiscord plugin, so the Python side never handles your token — data is read straight from the already-authenticated Discord client.

Claude ──stdio──> Python MCP ──WebSocket──> BetterDiscord plugin ──> Discord

⚠️ Disclaimer — read this first

This is a self-bot tool. Automating a personal Discord account and modifying the client (BetterDiscord) violate the Discord Terms of Service and can get your account banned.

• Use it only on your own account and at your own risk.
• The authors take no responsibility for banned accounts or any other consequences.
• Reading already-loaded client data is quieter than a raw HTTP self-bot, but the risk is not zero. Make requests infrequently and in small batches.
• Do not use it to collect, redistribute, or publish other people's private data. Respect the privacy of the servers you are in.

If you are not comfortable with these terms, use an official Discord bot via the Developer Portal instead.

Requirements

• Python 3.10+
• uv (package/runtime manager)
• BetterDiscord installed
• An MCP-capable client (Claude Desktop or Claude Code)

Install

1. Python server (via uv):

git clone https://github.com/encryrose/betterdiscord-mcp.git
cd betterdiscord-mcp
uv sync

2. BetterDiscord plugin:

• Copy plugin/DiscordMcpBridge.plugin.js into your BD plugins folder:
  • Windows: %AppData%\BetterDiscord\plugins\
  • macOS: ~/Library/Application Support/BetterDiscord/plugins/
  • Linux: ~/.config/BetterDiscord/plugins/
• In Discord: Settings → Plugins → enable DiscordMcpBridge.
• Make sure BRIDGE_PORT at the top of the plugin matches your .env (default 8787).

3. Register the MCP server with your client:

Claude Code (CLI):

claude mcp add discord -- uv --directory /path/to/betterdiscord-mcp run discord-mcp

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "discord": {
      "command": "uv",
      "args": ["--directory", "/path/to/betterdiscord-mcp", "run", "discord-mcp"]
    }
  }
}

Replace /path/to/betterdiscord-mcp with the absolute path where you cloned the repo. If uv is not on your client's PATH, use the full path to the uv executable in command.

How it works

1. On start, the MCP server opens a WebSocket bridge on 127.0.0.1:8787.
2. The plugin inside Discord connects to the bridge (you'll see a "bridge connected" toast).
3. The agent calls tools; the plugin reads Discord's internal Flux stores and returns the data.

No token is ever sent to the Python side — the plugin runs inside your already-authenticated client.

Tools

Tool	Purpose
bridge_status	Check whether the plugin is connected
ping	Lightweight health check: plugin version + resolved-module map
diagnostics	Show which internal Discord modules resolved (debugging)
list_guilds	List servers the client can see
list_channels	List a server's text channels
get_messages	Read a channel's history (paginate with before; filter by author_id / after; humanize resolves mentions)
search_messages	Native Discord search across a server
search_local	Offline full-text search (SQLite FTS5) over exports/*.json
get_message_by_link	Fetch a single message from a Discord message link
get_reactions	List users who reacted to a message with a given emoji
list_dms	List the account's direct and group DMs
list_threads	List threads or forum posts (loads uncached forum posts; includes first_message)
list_threads_paginated	Paginated threads/forum posts (offset/limit, returns {threads, hasMore, total})
read_thread	Read a thread / forum post's messages in chronological order
get_pins	List a channel's or thread's pinned messages
get_channel_info	Metadata for a channel or thread
get_guild_info	Guild metadata: roles, channels, member count, features, boost tier
resolve_id	Classify any snowflake as guild/channel/thread/user/message
list_members	Members currently known to the client (resolve_role_names adds role names)
get_roles	List a guild's roles (id, name, color, position, permissions)
get_user_info	Look up a user by id
export_channel	Dump a channel's history to exports/*.json
export_attachments	Download a channel's attachments to exports/ with a manifest
download_attachment	Download a single Discord CDN attachment to exports/
channel_stats	Offline analytics from a channel export (per-user, timeline, reply graph)

Typical flow

Start with bridge_status. If connected: list_guilds → list_channels → get_messages / search_messages / export_channel.

Troubleshooting

• "Plugin not connected" — Is Discord running? Is the plugin enabled? Do the ports match in .env and the plugin?
• "Module not found" / "is not a function" — Discord updated and the Webpack selectors in _resolveModules() drifted. Run diagnostics to see what resolved, then fix the module filters.
• Empty history — Scroll the channel manually once so the client loads messages, then retry.

Development

Install the project together with its dev tooling (pytest, pytest-asyncio, ruff):

uv sync --group dev

Run the test suite:

uv run pytest

Lint the code:

uv run ruff check .

The tests live in tests/ and exercise the WebSocket bridge (discord_mcp.bridge.Bridge) directly: they start the server on an unusual port, connect a fake plugin with the websockets client, and assert that a JSON-RPC round-trip returns the expected result. No real Discord client is needed.

Registering with Claude Code

Once installed, register the server with Claude Code:

claude mcp add discord -- uv --directory /path/to/betterdiscord-mcp run discord-mcp

Replace /path/to/betterdiscord-mcp with the absolute path to your clone.

Continuous integration

GitHub Actions (.github/workflows/ci.yml) runs on every push and pull request with two jobs:

• python — installs uv, runs uv sync --group dev, then uv run ruff check . and uv run pytest -q.
• plugin-syntax — validates the BetterDiscord plugin with node --check plugin/DiscordMcpBridge.plugin.js.

Screenshots

TODO: add a short GIF of the agent reading a channel.

License

MIT — see LICENSE. Provided as-is, with no warranty. Using this software is your responsibility.