# Discord MCP

Local, read-only Discord MCP server. It uses stdio and direct Discord REST API calls—there is no HTTP listener, Kubernetes deployment, Gateway connection, event cache, or write tool.

## Safety boundaries

- `DISCORD_ALLOWED_GUILDS` is required; the server fails to start without it.
- `DISCORD_ALLOWED_CHANNELS` is optional but recommended. When set, all channel and message reads outside it are rejected.
- Message tools always return message bodies. Enable **Message Content Intent** for the bot in Discord Developer Portal; without it, Discord returns empty content fields.
- The bot needs only `View Channel` and `Read Message History` for the initial tools. Do not grant Administrator, management, moderation, webhook, invite, or voice permissions.
- The bot token stays in your local MCP configuration or a local `.env` file; `.env` is ignored by Git.

## Tools

- `discord_list_guilds`
- `discord_list_channels`
- `discord_get_channel`
- `discord_list_messages`
- `discord_get_message`

All tools are read-only. Message reads support a bounded `limit` (1–100) and a `before` or `after` cursor. The service never downloads attachments and never returns attachment URLs.

## Setup

```bash
npm install
```

Copy `.env.example` to an ignored local `.env` file if you want a convenience template, then export it deliberately before running the development command:

```bash
set -a
. ./.env
set +a
npm run dev
```

Populate `DISCORD_BOT_TOKEN` and the numeric guild ID in that local file. Use Discord's Developer Mode to copy IDs. Add channel IDs to `DISCORD_ALLOWED_CHANNELS` before enabling the server for a shared guild.

Build and verify without contacting Discord:

```bash
npm run check
npm run build
```

## Codex configuration

Export the configuration variables in the same local environment that launches the Codex CLI. Do not put the token in this repository or `config.toml`.

Add this local MCP entry to `~/.codex/config.toml`, replacing the path with your clone path:

```toml
[mcp_servers.discord]
command = "node"
args = ["/absolute/path/to/discord-mcp/dist/index.js"]
cwd = "/absolute/path/to/discord-mcp"
env_vars = [
  "DISCORD_BOT_TOKEN",
  "DISCORD_ALLOWED_GUILDS",
  "DISCORD_ALLOWED_CHANNELS",
]
```

For example, in the shell you use to start Codex:

```bash
export DISCORD_BOT_TOKEN='...'
export DISCORD_ALLOWED_GUILDS='your-guild-id'
export DISCORD_ALLOWED_CHANNELS='your-test-channel-id'
codex
```

Build first, then restart Codex from that environment. If you use the ChatGPT desktop app rather than Codex CLI, configure the environment at the app-launch level or use the app's MCP-server form; a variable exported in an unrelated Terminal window will not be inherited by the already-running app.

## Development

```bash
npm run dev
npm test
npm run typecheck
```

`npm run dev` reads environment variables from the current shell. It deliberately does not load `.env` automatically so the token cannot be accidentally supplied through an unexpected execution path.