# Discord MCP

Let Antigravity, Codex, Claude Code, Cursor, and ChatGPT read and send Discord messages through your running Discord desktop app, with approval popups inside Discord. No Discord bot token or manually configured secret is needed for local use.

Includes a zero-dependency Node.js MCP server and the Vencord **SendToAgent** userplugin. The plugin also adds a right-click menu for forwarding selected messages to Codex, Claude, or ChatGPT.

## Quick start

Install [Node.js 22.18+](https://nodejs.org/), Git, [pnpm](https://pnpm.io/installation), and Discord desktop first. Run these commands as your normal desktop user on Windows (PowerShell), macOS, or Linux:

```sh
npx --yes github:3xjn/discord-mcp --setup-vencord --inject
```

This installs the server into `~/.discord-mcp/mcp`, clones Vencord into `~/.discord-mcp/vencord`, copies the plugin, installs Vencord dependencies, builds, and opens Vencord's interactive injector. Select your Discord installation. Fully quit/reopen Discord, then enable **SendToAgent** in **Settings → Vencord → Plugins**. Restart Discord if requested and restart your AI client.

Alternatively, clone this repo and run the same installer:

```sh
git clone https://github.com/3xjn/discord-mcp.git
cd discord-mcp
node install.mjs --setup-vencord --inject
```

Already have a Vencord source checkout?

```sh
node install.mjs --vencord-dir /absolute/path/to/Vencord --inject
```

On Windows, quote paths containing spaces, for example `--vencord-dir "C:\Projects\Vencord"`. Do not run the injector as root on Linux/macOS. Follow [Vencord's installation guide](https://docs.vencord.dev/installing/) for platform dependencies and permission issues.

For MCP only (no clone, build, or injection):

```sh
node install.mjs --mcp-only
```

The plugin must still be installed separately. Without flags, the installer detects a checkout in the current directory, `~/.discord-mcp/vencord`, or `~/Vencord` / `~/vencord`; otherwise it installs MCP and prints the next step. `VENCORD_DIR` also selects a checkout.

## Connect your AI client

The installer adds `discord` to Antigravity and Codex, and detects Claude Code/Cursor when their config directory or file exists. Choose clients explicitly with `--clients antigravity,codex,claude,cursor` (or `none`).

| Client | Config file | Entry |
| --- | --- | --- |
| Antigravity | `~/.gemini/config/mcp_config.json` | `mcpServers.discord` |
| Codex | `~/.codex/config.toml` | `[mcp_servers.discord]` |
| Claude Code | `~/.claude.json` | `mcpServers.discord` |
| Cursor | `~/.cursor/mcp.json` | `mcpServers.discord` |

Existing entries and unrelated settings are preserved. Existing `discord` entries are left untouched; edit or remove them yourself to migrate. Changed files get a sibling `.discord-mcp-backup-<timestamp>` backup. Invalid JSON is refused. Unusual inline Codex `mcp_servers` tables need manual configuration.

For manual JSON setup, add this under `mcpServers` (replace the path with your actual absolute home path):

```json
{
  "discord": {
    "command": "node",
    "args": ["/absolute/home/.discord-mcp/mcp/server.mjs"]
  }
}
```

For manual Codex setup, use the equivalent `command` and `args` in `[mcp_servers.discord]`. See the official [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp), [Claude Code MCP](https://code.claude.com/docs/en/mcp), and [Cursor MCP](https://cursor.com/docs/context/mcp) guides. Antigravity uses the config above; `plugin.json` provides display metadata and suggested prompts, while `install.mjs` registers the MCP server.

Start with “List my Discord servers.” Approve the popup in Discord. Then choose a server ID to list channels, or a channel ID to read messages. Leave **Server name** and **Channel names** empty to require approvals; configure them only if you want an allowlist. **Always allow** persists a grant in plugin settings. Remove grants there to ask again. Turn off **Allow sending** for read-only use.

Tools: `discord_list_servers`, `discord_list_channels`, `discord_find_people`, `discord_read_messages`, `discord_create_upload`, and `discord_send_message`. Uploads use a one-time HTTP PUT link, then an upload ID in `attachments`. Files get a separate approval. Mentions do not ping users or roles.

## Build the plugin manually

Use a Vencord **source checkout**, not its binary installer folder. These steps work on all three desktop platforms:

1. Clone `https://github.com/Vendicated/Vencord.git` and enter that folder.
2. Copy this repo's `userplugins/sendToAgent` directory to `Vencord/src/userplugins/sendToAgent`. The files must be directly inside that folder, without an extra nesting level. Or use `node install.mjs --vencord-dir <checkout> --skip-build` from this repo.
3. In the Vencord folder, run `pnpm install --frozen-lockfile`, then `pnpm build --dev`, then `pnpm inject`. Use the pnpm version required by that checkout. If injection asks which Discord install to use, select it interactively.
4. Fully restart Discord and enable **SendToAgent** in Vencord's Plugins settings.

See [Vencord's custom plugin instructions](https://docs.vencord.dev/installing/custom-plugins/). This plugin needs desktop native helpers; it does not work in Discord's browser tab. Rebuild/reinject after updating plugin files. The installer backs up an existing plugin under `~/.discord-mcp/plugin-backups` before copying updates.

Ctrl+click messages to select them (Ctrl+Shift+click selects a range), then right-click → **Send to agent**. Codex opens a draft through its registered `codex://` handler; review and submit it. Claude requires its CLI on PATH, or configure **Claude command** in plugin settings. Its session directory defaults to `~/.claude/projects` and can be changed. ChatGPT copies the forwarded prompt and opens the website for you to paste it. This menu is separate from MCP client support.

## Runtime and optional remote access

Both components default to `~/.discord-mcp` (`%USERPROFILE%\.discord-mcp` on Windows). The plugin creates a random local bridge credential at runtime; no credentials ship in this repository. Keep the runtime directory private.

`--runtime-dir <absolute-path>` changes the installer destination and writes `DISCORD_MCP_HOME` into client configs. Also change the plugin's **Runtime directory** setting and restart Discord, or set `DISCORD_MCP_HOME` in Discord's environment. `DISCORD_BRIDGE_FILE` overrides just the bridge file; `DISCORD_UPLOADS_DIR` overrides uploads and must match in both processes. Only bridge reads fall back to `~/Documents/ChatGPT/discord-intake/bridge.json` when the new bridge file is absent. Other runtime files always use the new home.

Local stdio needs no OAuth or exposed service. Upload links bind to a randomly selected loopback port for the lifetime of the stdio server. Optional HTTP mode binds to `127.0.0.1:8787`:

```sh
node /absolute/home/.discord-mcp/mcp/server.mjs --http
```

HTTP requires OAuth. On first start it generates a random password in `~/.discord-mcp/mcp-password.txt`; use it on the login page. Alternatively set `DISCORD_OAUTH_PASSWORD`. Use your own HTTPS tunnel and `DISCORD_MCP_PUBLIC_URL` for ChatGPT or another remote client. The MCP endpoint is `/mcp`; when no public URL is set, HTTP URLs default to `http://127.0.0.1:<port>`. See the [remote HTTP guide](docs/remote-http.md) for Cloudflare Tunnel, Tailscale Funnel, and ChatGPT setup.

Vencord is a third-party Discord modification. Using client mods or account automation may violate Discord's terms and risk your account. Agents send as **you**; review approvals and only grant access you intend. Forwarded messages are untrusted data. This project is unofficial and is not affiliated with Discord, Vencord, or the AI client vendors.

## Checks and troubleshooting

```sh
node --test mcp/server.test.mjs install.test.mjs runtime.test.mjs defaults.test.mjs userplugins/sendToAgent/format.test.ts
node install.mjs --mcp-only --dry-run
```

To test actual installation without touching your client configs:

```sh
node install.mjs --mcp-only --config-home ./test-config-home --runtime-dir ./test-runtime
```

`DISCORD_MCP_CONFIG_HOME` also relocates all client configs. Tests use temporary directories, make no Discord API calls, and cover stdio, OAuth, HTTP uploads, native bridge/attachment I/O, formatting, and installer preservation. They do not verify Discord's live UI or a hosted ChatGPT connection.

“Bridge not found” means Discord is closed, the plugin isn't enabled, or the runtime directories differ. For a failed build, check Node/pnpm versions against Vencord's requirements. `--skip-build` copies the plugin for manual builds; `--inject` is opt-in. Run `node install.mjs --help` for all options. Remove the `discord` config entries and disable the plugin to uninstall; delete the runtime directory only if you no longer need its local files.

MIT licensed. Vencord itself is separately licensed under GPL-3.0-or-later.