# discord-mcp

A feature-rich Discord MCP (Model Context Protocol) server for Claude Code and other MCP clients. Control Discord from your AI assistant — browse servers, send messages, moderate, manage channels/roles/emojis, analyze your message history, and more. **70+ tools.**

Runs on [Bun](https://bun.sh), stores captured messages in SQLite, and authenticates with the tokens already cached in your local Discord client — no bot account or manual token setup needed.

## ⚠️ Read this first

- This tool acts as **your Discord account** (user account, not a bot). Anything it does — sending, banning, editing servers — happens as you.
- Automating a user account technically violates [Discord's ToS](https://discord.com/terms). Use it on your own servers and at your own risk.
- Tokens are decrypted locally via Windows DPAPI and **never leave the MCP process** — they are never printed, logged, or passed to the AI.
- **Windows only** (token extraction uses Discord's LevelDB + DPAPI).

## Features

### 📥 Capture & accounts
| Tool | What it does |
|---|---|
| `start_capture` | Connect to the Gateway WebSocket and capture live messages (pass `account` to pick which cached account) |
| `stop_capture` | Disconnect the capture |
| `capture_status` | Connection state, message counts, uptime |
| `list_accounts` | List cached Discord accounts (id + username only — tokens never exposed) |

Switching accounts is just `start_capture({account: "username"})` while connected — it reconnects as that account.

### 🧭 Browsing
- `list_guilds`, `list_channels`, `list_dms`, `get_channel_info`
- `get_user_info`, `get_guild_info`, `get_guild_members`, `get_guild_roles`
- `get_invite_info` (look up an invite without joining)

### 💬 Messaging
- `send_message` (with reply support), `edit_message`, `delete_message`, `bulk_delete_messages`
- `react_to_message`, `remove_reaction`, `get_reactions`
- `typing_indicator`, `create_dm`, `fetch_channel_history`
- `crosspost_message`, `follow_announcement_channel`
- `pin_message`, `unpin_message`, `get_pinned_messages`

### 🛡️ Moderation
- `kick_member`, `ban_member`, `unban_member`, `list_bans`
- `timeout_member`, `set_nickname`, `move_member`
- `add_role_to_member` / `remove_role_from_member`
- `prune_members` (dry-run or execute), `get_audit_log`

### 📺 Channel admin
- `create_channel` (text / voice / category / announcement / stage / forum), `edit_channel`, `delete_channel`
- `reorder_channels`, `set_channel_permissions`, `delete_channel_permissions`
- `list_webhooks`, `create_webhook`, `delete_webhook`, `execute_webhook`

### 👑 Guild admin
- `create_role`, `edit_role`, `delete_role`, `reorder_roles`
- `create_guild_emoji`, `delete_guild_emoji`
- `create_channel_invite`, `list_guild_invites`, `delete_invite`
- `edit_guild_settings` (name, verification level, content filter, AFK, system channel)
- `list_scheduled_events`, `create_scheduled_event`, `delete_scheduled_event`, `get_voice_regions`

### 🔎 Search & query (captured messages)
- `query_messages` — filter by author, channel, guild, date, attachments
- `search_messages` — full-text search (SQLite FTS5)
- `get_active_conversations`, `get_mentions`, `get_unread_summary`

### 🧠 Self-analysis
- `analyze_personality` — vocabulary, emoji usage, punctuation, activity patterns
- `response_style_analysis` — timing, tone, opening/closing phrases, edit behavior
- `get_common_phrases` — your bigrams, trigrams, filler words, signature expressions
- `get_conversation_threads` — stimulus→response pairs with timing
- `track_user_activity`, `compare_users`

### 🎁 Extras
- `scan_giveaways`, `join_giveaway`, `auto_join_giveaways`
- `get_relationships`, `add_friend`, `remove_friend`, `block_user`
- `get_connections`, `get_nitro_status`, `export_favorite_gifs`
- `join_guild_invite`, `leave_guild`
- `set_status`, `set_bio`, `set_avatar`
- `clone_server_structure`, `export_server_structure`
- `export_dataset` (JSON/CSV), `get_capture_stats`

## Setup

### 1. Install Bun

Download from <https://bun.sh> or with PowerShell:

```powershell
powershell -c "irm bun.sh/install.ps1 | iex"
```

### 2. Clone & install

```powershell
git clone https://github.com/nesquickwe/discord-mcp.git
cd discord-mcp
bun install
bun add -d bun-types
```

### 3. Make sure Discord is logged in

The server reads tokens from your local Discord client's storage
(`%APPDATA%\discord\Local Storage\leveldb`). Just have the desktop app
installed and logged in to the account(s) you want to use.

### 4. Register with your AI tool

The included `setup_mcp.ps1` auto-detects and registers the server with every supported client:

```powershell
powershell -ExecutionPolicy Bypass -File setup_mcp.ps1
```

Supported: **Claude Code, OpenAI Codex, Trae, Google Antigravity, Windsurf/Devin, Cursor**.

To register with just one:

```powershell
powershell -ExecutionPolicy Bypass -File setup_mcp.ps1 claude
```

Prefer manual setup? Add this to the right config file for your client (paths use Claude Code's `%USERPROFILE%\.claude.json`):

```json
{
  "mcpServers": {
    "discord": {
      "command": "<path-to-bun>",
      "args": ["run", "<repo-path>\\src\\index.ts"]
    }
  }
}
```

| Client | Config location |
|---|---|
| Claude Code | `%USERPROFILE%\.claude.json` |
| Codex | `%USERPROFILE%\.codex\config.toml` |
| Trae | `%APPDATA%\Trae\User\globalStorage\trae.mcp\mcp_config.json` |
| Antigravity | `%USERPROFILE%\.antigravity\mcp.json` |
| Windsurf / Devin | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
| Cursor | `%USERPROFILE%\.cursor\mcp.json` |

Restart your AI tool and the `discord` MCP server appears with all tools.

Then restart Claude Code and the `discord` MCP server appears with all tools.

## Usage tips

- **Connect first.** Most API tools need an active session: `start_capture` (optionally with `account`).
- **Multiple accounts?** `list_accounts` shows what's cached, then `start_capture({account: "myaccount"})` to connect as a specific one.
- **Captured vs API data** — `query_messages`/`search_messages` only see messages that arrived while capture was running; `fetch_channel_history` pulls straight from the Discord API.
- Messages are stored in `data/messages.db` (SQLite) so analysis tools work across sessions.

## Project layout

```
src/
├── index.ts          # entry — registers all tool modules
├── token/            # DPAPI + LevelDB token extraction (multi-account)
├── gateway/          # Discord Gateway WebSocket client
├── storage/          # SQLite persistence (messages, channels, users)
├── analysis/         # personality / phrase / style / thread analysis
├── tools/            # tool modules (capture, messaging, moderation, ...)
└── util/             # Discord REST API helper, config, logger
```

## License

MIT — see [LICENSE](LICENSE).