discord-mcp

Read and act on Discord through your own running desktop client: channel messages, direct messages, group chats, threads, forum posts, and search.

How it works

Discord's desktop app is Electron. Started with --remote-debugging-port, its renderer is reachable over the Chrome DevTools Protocol. discord-mcp attaches to that renderer, observes the header set the client already sends on its own API calls, and issues requests from inside the same page.

Every request therefore comes from the real client process, on the real session, with the real fingerprint. There is no second client to detect, and the token is never read out of Discord's storage: it is only ever observed on a request the client was already making.

Related MCP server: discord-user-mcp

Read this before using it

This violates Discord's Terms of Service. Automating a user account is prohibited regardless of how the session was obtained, and section 11 separately prohibits modifying the client.

The practical risk sits in the same bracket as client mods such as Vencord, which Discord has publicly deprioritized and which have no confirmed bans as of 2026. That is a pattern of non-enforcement, not a promise. Risk concentrates in writing, not reading.

A bot token would be fully compliant, but a bot can never read your direct messages. That limitation is the entire reason this project exists.

Setup

npm install
npm run build

Discord holds a single-instance lock, so the debugging flag only takes effect at startup. Quit any running client first.

node dist/cli/main.js launch      # starts Discord on a random loopback port
node dist/cli/main.js doctor      # verifies attach, capture and a real read

doctor should print your account, guild count and direct message count.

The first attach reloads the renderer once, because an idle client makes no REST requests to observe headers from. The capture is then remembered per port for twelve hours in ~/.local/state/discord-mcp/headers.json, so later runs attach in about a second and leave your client alone.

Wiring it to an MCP client

{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["/path/to/discord-mcp/dist/cli/main.js", "serve"]
    }
  }
}

Tools

Eighteen tools are exposed by default: twelve read and six write.

Reading a forum works by listing a forum channel's threads. Each post comes back with the message that opened it and its applied tags, so a post is readable without a second call.

Destructive tools

Seven more operations exist and are not registered at all unless their category is enabled. They do not appear in the tool list, so no host and no model can reach them.

Enable only what you need:

{ "destructive": ["messages", "threads"] }

node dist/cli/main.js serve --config /path/to/policy.json

This is the load-bearing control. Host approval prompts are a second layer, because host behaviour varies and some hosts approve automatically. Each destructive tool resolves and returns what it acted on, so the result names the channel rather than only echoing a snowflake.

Security

An open DevTools port is a local authentication bypass: any process running as you can drive the session, two-factor included. discord-mcp binds to loopback only and picks a random high port rather than the default 9222. Do not leave the client running with the port open when you are not using it.

The header cache holds a live token. Reusing a capture means keeping it, so ~/.local/state/discord-mcp/headers.json contains your Authorization header until it expires. It is written owner-only, mode 0600, and so is the launch state beside it. Delete the file to force a fresh capture:

rm ~/.local/state/discord-mcp/headers.json

Run without a cache path if you would rather capture every time and never store the token, at the cost of a renderer reload on each attach.

Layout

src/attach/     CDP connection, target selection, launch, state
src/bridge/     header capture, request execution, rate limiting
src/api/        typed wrappers over Discord REST v9
src/normalize/  reduce Discord's wire format to what a reader needs
src/policy/     operation tiers and the destructive gate
src/tools/      MCP tool registration
src/cli/        launch, doctor, serve

Dependencies run downward only. normalize/ and policy/ are pure and depend on nothing, which is where most of the test suite lives.

npm test         # 152 tests, no Discord required
npm run typecheck

The design document, including the Spike 0 findings that shaped the bridge, is in docs/superpowers/specs/.