# discord-mcp

A local MCP (Model Context Protocol) server for Discord, written in TypeScript. It lets MCP clients like Cursor and Claude Code read and send Discord messages through a bot account.

## Tools

| Tool | Description |
| --- | --- |
| `list_servers` | List servers the bot is a member of |
| `list_channels` | List channels in a server (with IDs and types) |
| `read_messages` | Read recent messages from a channel, with paging via `before` |
| `send_message` | Send a message to a channel, optionally as a reply |
| `send_dm` | Send a direct message to a user by ID |
| `add_reaction` | React to a message with an emoji |
| `search_members` | Search server members by name prefix |
| `get_server_info` | Get server name, description, member count, owner |

## Setup

### 1. Create a Discord bot

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and click **New Application**.
2. Under **Bot**, click **Reset Token** and copy the token — this is your `DISCORD_TOKEN`.
3. Still under **Bot**, enable the **Privileged Gateway Intents** you want:
   - **Message Content Intent** — required to read message text.
   - **Server Members Intent** — required for `search_members`.

   (The server still works without these, but message content will be empty and member search unavailable.)
4. Invite the bot to your server: under **OAuth2 → URL Generator**, select the `bot` scope, then permissions **View Channels**, **Send Messages**, **Read Message History**, **Add Reactions**. Open the generated URL and pick your server.

### 2. Build

```bash
npm install
npm run build
```

### 3. Register with your MCP client

**Cursor** — add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

```json
{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["/absolute/path/to/discord-mcp/dist/index.js"],
      "env": {
        "DISCORD_TOKEN": "your-bot-token"
      }
    }
  }
}
```

**Claude Code**:

```bash
claude mcp add discord -e DISCORD_TOKEN=your-bot-token -- node /absolute/path/to/discord-mcp/dist/index.js
```

## Notes

- The bot connects to Discord lazily on the first tool call, so the server starts even before a token is configured.
- Messages are capped at Discord's 2000-character limit.
- `DISCORD_BOT_TOKEN` is accepted as an alternative to `DISCORD_TOKEN`.

## Why a bot token instead of email/password?

Automating a regular user account (a "self-bot") violates Discord's Terms of Service and commonly results in permanent account bans. Bot tokens are the supported way to build integrations and take about two minutes to set up.