<div align="center">

# 🤖 Discord MCP Server

**Give Claude full access to Discord.**  
Read messages, send messages, manage threads, react, search history, send DMs — all through natural conversation.

[![Made by Claude for Claude](https://img.shields.io/badge/Made%20by%20Claude-for%20Claude-5865F2?style=for-the-badge&logo=anthropic&logoColor=white)](https://anthropic.com)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-compatible-blueviolet?style=for-the-badge)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)

</div>

---

## What is this?

**Discord MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io) server that bridges Claude and Discord. Once connected, you can talk to Claude in plain English and it will interact with your Discord account — no scripting, no dashboards, no manual API calls.

> Uses a Discord **user token** — no bot registration needed.

---

## Demo

```
You: "What are the last 15 messages in #general?"
You: "Send a message to #announcements: deployment done ✅"
You: "Search #support for messages about 'login error'"
You: "DM user 123456789 and say hey, got a minute?"
You: "Create a thread called 'Release notes' from that last message"
You: "What are my recent mentions across all servers?"
You: "React to message 987654321 with 👍"
```

---

## Tools

| Tool | Description |
|---|---|
| `get_bot_info` | Connected account info (username, ping, server count) |
| `list_guilds` | All Discord servers you're in |
| `get_guild_info` | Server details: members, boosts, verification level, etc. |
| `list_channels` | All channels in a server, sorted by position |
| `get_channel_info` | Info about a specific channel |
| `get_messages` | Fetch recent messages (up to 100), with pagination |
| `send_message` | Send a message, with optional reply |
| `send_embed` | Send a rich embed (title, description, fields, color, footer) |
| `edit_message` | Edit one of your own messages |
| `delete_message` | Delete a message |
| `pin_message` | Pin or unpin a message |
| `add_reaction` | React with a Unicode or custom emoji |
| `create_thread` | Start a thread from a message or create a standalone one |
| `list_members` | List server members with roles (up to 1 000) |
| `get_user_info` | Full profile of a user in a server |
| `search_messages` | Keyword search across recent channel history |
| `get_pinned_messages` | All pinned messages in a channel |
| `get_dm_channels` | List your open DM conversations |
| `send_dm` | Send a direct message to any user by ID |
| `get_mentions` | Recent messages that mention you across all servers |

---

## Requirements

- [Node.js](https://nodejs.org) 18+
- Your Discord user token

---

## Setup

### 1. Get your Discord User Token

1. Open Discord in your **browser** at [discord.com/app](https://discord.com/app)
2. Press `F12` → **Network** tab
3. Send any message or switch a channel
4. Find any request to `discord.com/api`, click it, look at **Request Headers**
5. Copy the value of the `Authorization` header — that's your token

Or paste this in the browser **Console**:
```js
(webpackChunkdiscord_app.push([[''],{},e=>{m=[];for(let c in e.c)m.push(e.c[c])}]),m)
  .find(m=>m?.exports?.default?.getToken!==void 0).exports.default.getToken()
```

> ⚠️ **Your user token = your password.** Never share it, commit it to git, or put it in public config files.

---

### 2. Install

```bash
git clone https://github.com/vovafes/discord-mcp-server.git
cd discord-mcp-server
npm install
npm run build
```

---

### 3. Connect to Claude Desktop

Edit your Claude Desktop config:

- **macOS** → `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows** → `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["/absolute/path/to/discord-mcp-server/dist/index.js"],
      "env": {
        "DISCORD_USER_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}
```

Restart Claude Desktop — the Discord tools will appear automatically.

---

### 4. Connect to Claude Code CLI

```bash
claude mcp add discord \
  --env DISCORD_USER_TOKEN=YOUR_TOKEN_HERE \
  -- node /absolute/path/to/discord-mcp-server/dist/index.js
```

---

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `DISCORD_USER_TOKEN` | ✅ | — | Your Discord user token |
| `REQUEST_DELAY_MS` | ❌ | `5000` | Delay between REST calls in ms. Lower = faster, higher = safer. |

---

## Rate-Limit Protection

Discord enforces strict limits on user tokens. Three layers of protection are built in:

### Global throttle
Every REST call passes through a shared gate that enforces a minimum gap of `REQUEST_DELAY_MS` (default **5 seconds**) between consecutive requests.

### Exponential back-off
On a `429 Too Many Requests` response, the server automatically retries:

```
attempt 1 → wait 2s
attempt 2 → wait 4s
attempt 3 → wait 8s
attempt 4 → wait 16s  (then give up)
```

### Hard scan caps
Bulk tools that touch many channels are capped to prevent runaway API storms:

| Tool | Limit |
|---|---|
| `search_messages` | Max **500 messages** (5 batches × 100) |
| `get_mentions` | Max **20 channels** scanned across all servers |

**To tune the throttle:**
```json
"env": {
  "DISCORD_USER_TOKEN": "...",
  "REQUEST_DELAY_MS": "2000"
}
```

---

## Architecture

```
╔══════════════════╗
║  Claude / MCP    ║
║     Client       ║
╚════════╤═════════╝
         │ stdio (JSON-RPC)
╔════════▼═════════╗
║  discord-mcp     ║  ← this server
║  (Node.js)       ║
╚════════╤═════════╝
         │ discord.js (WebSocket + REST)
╔════════▼═════════╗
║  Discord API     ║
╚══════════════════╝
```

The server speaks MCP over `stdio` — no open ports, no HTTP server. The MCP host (Claude Desktop, Claude Code, etc.) spawns it as a subprocess.

---

## Development

```bash
# Dev mode — no build step needed
DISCORD_USER_TOKEN=your_token npm run dev

# Build
npm run build

# Run built output
DISCORD_USER_TOKEN=your_token npm start
```

---

<div align="center">

**Made by Claude for Claude** 🤖

*Built with [discord.js](https://discord.js.org) · [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)*

</div>