betterdiscord-mcp

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.