Discord MCP Server

Discord for language models, through one tool that runs code

The model discovers the live discord.js API, writes its own helpers, and keeps them across calls and restarts, instead of picking from a fixed menu of verbs.

Quick start · The run tool · Secrets · Other MCP servers · Configuration · Security

▶ Watch the teaser with sound

Why one code tool

A fixed catalog of typed tools is the wrong interface for Discord. Every bot, permission set and library version supports a different slice of the API, and different models are good with different tools. So this server doesn't hand-pick verbs. It exposes a single tool, run, gives the code a live discord.js client, and lets each deployment's model build the tooling it needs.

// call 1: the model writes a helper...
async function channelByName(guildId, name) {
  const guild = await client.guilds.fetch(guildId);
  return (await guild.channels.fetch()).find((c) => c.name === name);
}

// call 2 (or next week, after a restart): ...and reuses it
const general = await channelByName("123456789012345678", "general");
await general.send(vars.announcement);

Highlights

• One tool, the whole API. client is a real discord.js Client. describe(x) shows live state and every method's signature and doc, so the model can find its way.

• It remembers. Functions, classes and constants the model defines are saved and reloaded on restart. Side effects never are.

• Tokens stay out of reach. An ssh-agent-style agent holds the tokens, so the server and the model only ever see agent:<id>.

• Other MCP servers become functions. mcp.github.get_issue(...) inside the same code, not a growing list of tools.

• Hardened networking. Optional proxy for all Discord traffic, https-only upstreams with known_hosts pinning, per-identity latency, and tokens kept out of logs and traces.

Related MCP server: discord-mcp

How it works

flowchart LR
    M["Model<br>(any MCP client)"] -- "run(code)" --> S
    subgraph S["discord-mcp server"]
        direction TB
        N["Persistent JS namespace<br>client · describe · ops · kept helpers"]
        U["mcp.server.tool()"]
    end
    N -- "agent:id placeholder<br>(Unix socket)" --> A["discord-mcp agent<br>holds the decrypted tokens"]
    A -- "real token<br>REST + gateway" --> D[("Discord")]
    U --> O["Other MCP servers<br>https or stdio"]

Quick start

Prerequisites: Node.js 22.15+, npm, and a Discord bot token.

git clone https://github.com/drvova/discord-mcp.git
cd discord-mcp
npm install            # also builds dist/

1. Store the token, encrypted, like an SSH key. You're prompted (hidden) for the token and a passphrase.

node dist/bootstrap.js identity add default-bot

2. Start the agent in its own terminal, like ssh-agent. It asks for the passphrase and prints the socket to use.

node dist/bootstrap.js agent
# DISCORD_MCP_AGENT_SOCK=/run/user/1000/discord-mcp/agent.sock; export DISCORD_MCP_AGENT_SOCK;

3. Point your MCP client at the server, with only the agent socket in its environment:

{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["/absolute/path/to/discord-mcp/dist/bootstrap.js"],
      "env": { "DISCORD_MCP_AGENT_SOCK": "/run/user/1000/discord-mcp/agent.sock" }
    }
  }
}

Then ask the model to call run with empty code: it gets the manual and takes it from there.

Skip the agent and give the server the token directly:

DISCORD_TOKEN=your_bot_token node dist/bootstrap.js

This works, but the token then lives in the server process, where code in the run tool can read it (for example through the client's auth config). The server warns about this at startup. Secret environment variables are removed from process.env once read, in both modes.

The run tool

run is the only tool the server advertises.

The code runs in one long-lived namespace with top-level await. The result is whatever it printed plus the value of its last expression.

What's in the namespace

Examples

Each block is the code of one run call.

// What can this bot do right now?
describe(client)

// Search what discord.js exports
(await symbols("TextChannel#send")).items.map((s) => s.name)

// Check a call before making it
await ops.preflight({
  packageAlias: "discordjs",
  symbol: "TextChannel#send",
  kind: "function",
  target: "channel",
  context: { channelId: "123456789012345678" },
})

// Switch to another identity the agent holds
await bind("ops-bot");
client.user.tag

Helpers survive restarts

After each successful call, every top-level definition (a function or class declaration, or a const bound to a literal, function or class) is saved as its own file and loaded back when the server starts. Each one loads in isolation, so a broken file is reported by kept() and never stops the server. Statements that do work (calls, let, const x = await …) are never saved or replayed.

Definitions live in DISCORD_MCP_KEPT_DIR (default ~/.config/discord-mcp/kept). In a container, mount it as a volume.

Secrets: the SSH model

Discord tokens are handled the way SSH handles private keys.

• REST. The server's discord.js client logs in as agent:default-bot and sends its REST requests to the agent over the Unix socket. The agent swaps the placeholder Authorization header for the real token and forwards the request to https://discord.com/api, always to that base, whatever path the client sends.

• Gateway. The gateway URL Discord returns is replaced with an agent address. The agent relays the WebSocket and swaps the token inside the IDENTIFY and RESUME frames. It only connects to gateway URLs Discord itself returned, which clients see as opaque handles, and only on wss://*.discord.gg.

• The result. Code in run can use Discord (client, ops.*, its own helpers) but can't read a token. It isn't in client.token, the auth config, process.env, the encrypted file, or the agent's API. connect() is disabled with the agent, so tokens never pass through the model.

• Adding identities. identity add encrypts into the file and, when DISCORD_MCP_AGENT_SOCK is set, also loads the identity into the running agent, like ssh-add; then bind("id").

• Input. Tokens and passphrases come from a hidden prompt, a mode 600 file (--token-file, DISCORD_MCP_PASSPHRASE_FILE) or stdin, never from command-line arguments (visible in ps). --token-env DISCORD_TOKEN migrates an existing variable.

• Unattended agents (containers, services): set DISCORD_MCP_PASSPHRASE_FILE to a mode 600 file. For a Docker secret, give it mode: 0400.

• Proxy. With DISCORD_MCP_PROXY set, the agent sends REST and the gateway through it.

Other MCP servers as functions

Other MCP servers aren't re-advertised as tools. Their tools become async functions in the namespace (the "code mode" pattern), so the model composes several calls in one run, filters results in code, and prints only what it needs:

// GitHub issues mentioned in the last 50 messages of a channel
const channel = await client.channels.fetch("123456789012345678");
const refs = [...(await channel.messages.fetch({ limit: 50 })).values()]
  .flatMap((m) => [...m.content.matchAll(/#(\d+)/g)].map((x) => Number(x[1])));
for (const n of new Set(refs)) {
  const issue = await mcp.github.get_issue({ owner: "acme", repo: "app", issue_number: n });
  print(`#${n} ${issue.state} ${issue.title}`);
}

• Results: a call resolves to the tool's structured content, or its text (parsed when it's JSON). A tool error is thrown.

• Discovery: tool names become identifiers (get-issue → get_issue). describe(mcp.github) lists each tool's signature, generated from its input schema.

• Configuration: servers in DISCORD_MCP_UPSTREAMS (inline JSON or a file, in the usual mcpServers shape) connect at startup. ${VAR} is read from the environment, so secrets stay out of the file:

  {
    "mcpServers": {
      "github": { "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" } },
      "files": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] }
    }
  }

• Transports: url servers use streamable HTTP with SSE fallback (force one with "type": "http" or "sse"). command servers use stdio. An unreachable server shows up in mcpServers() and doesn't stop startup.

• At runtime: mcpConnect(name, config) adds a server until the next restart. Helpers that wrap mcp.* calls are saved like any other definition.

Network

Configuration

Environment variables, all optional. A .env file in the working directory is loaded too.

HTTP mode

With MCP_HTTP_PORT set, the server speaks MCP over HTTP and SSE:

A typed client is generated from the route types:

import { createHttpClient } from "./src/http-client.js";

const client = createHttpClient("http://localhost:1455");
const health = await (await client.health.$get()).json();

Security

• Sandbox the server. run executes code with the server's full authority. Give the container, VM or jail only the network, filesystem and identities you intend the model to use.

• Use the agent. It keeps tokens out of the server process. In direct mode, run code can read them.

• Least privilege on Discord. Give bots only the permissions they need, and rotate tokens.

• Audit. Every run call is written to the audit log; set DISCORD_MCP_AUDIT_LOG_PATH in production.

• Know what the policy covers. DISCORD_MCP_BLOCK_HIGH_RISK, dryRun and allowWrite apply to ops.* only. Code that uses client directly is bounded by the sandbox and the bot's Discord permissions.

Development

The toolchain is Rstack: Rslib builds, Rstest tests, Rslint lints and type-checks.

The animated banner and the teaser trailer are authored with Clayzo in assets/banner, its own small project; the trailer's soundtrack is synthesised by a Python script there, and its player page lives in site.

The default branch is new-architecture-main.

License

MIT