# Discord MCP Server 🚀

A comprehensive, production-grade **Model Context Protocol (MCP)** Server for Discord. Connects LLMs (Claude, Cursor, OpenCode, Windsurf, Cline) directly to Discord with **82 specialized tools**, **live server resources**, and **built-in prompts**.

---

## ⚡ What Can This MCP Server Do?

### 🔍 Deep User Intelligence & Forensics
- **`discord_inspect_user`**: Complete forensic dossier (account creation age, server join age, alt-account risk indicator, badges/public flags, nitro booster tier, permissions calculated across all roles, voice state, highest role, timeout status).
- **`discord_send_dm`**: Send direct messages (text & rich embeds) to any user by user ID or username.
- **`discord_get_dm_history`**: Read past DM conversations between the bot and any user.
- **`discord_get_user`**: Retrieve full user profiles (ID, tag, avatar URL, creation date, bot flag, banner).

### 🚨 Emergency Server Defense & Lockdowns
- **`discord_lockdown_channel`**: Instantly prevent `@everyone` from sending messages in a channel or entire category during raids or spam waves.
- **`discord_unlock_channel`**: Lift lockdown and restore channel permissions.
- **`discord_quarantine_member`**: Apply emergency 28-day timeout and strip all removable roles from compromised accounts.
- **`discord_bulk_slowmode`**: Update or reset slowmode cooldowns across multiple channels simultaneously.

### 🗳️ Native Discord Interactive Polls
- **`discord_create_poll`**: Post native Discord interactive polls (2 to 10 choices, custom durations: 1h, 24h, 3d, 1w, and multi-select).
- **`discord_get_poll_results`**: Live breakdown of vote tallies, percentages, and voters.
- **`discord_end_poll`**: Immediately finalize and lock a poll.

### 📊 Message Search, Transcripts & Analytics
- **`discord_search_messages`**: Search messages with keyword, author ID, and attachment filters.
- **`discord_export_transcript`**: Export clean Markdown or JSON transcript of recent messages (ideal for incident reports or summaries).
- **`discord_channel_analytics`**: Analyze message velocity, active participants, and top contributors.

### 💡 Forums & Discussions
- **`discord_create_forum_post`**: Create structured posts/threads in Forum channels with custom tags and starter content.
- **`discord_list_forum_tags`**: Query configured tags on Forum channels.

### 🎙️ Voice & Live Stage Controls
- **`discord_get_voice_states`**: List members in voice/stage channels (mute, deafen, streaming status).
- **`discord_move_voice_member`**: Move members between voice channels or disconnect them.
- **`discord_start_stage`** / **`discord_end_stage`**: Open and close live Stage Instances with topics.
- **`discord_set_speaker_status`**: Promote listeners to speakers or mute stage speakers.
- **`discord_server_mute_voice`** / **`discord_server_deafen_voice`**: Server mute/deafen voice members.

### 📨 Messages, Chat History & Reactions
- **`discord_send_message`**: Post formatted messages and rich embeds to text and announcement channels.
- **`discord_get_messages`**: Read channel message history, attachments, authors, and timestamps.
- **`discord_edit_message`** / **`discord_delete_message`**: Update or delete messages.
- **`discord_purge_messages`**: Bulk purge messages (with optional user filtering).
- **`discord_pin_message`** / **`discord_unpin_message`**: Pin or unpin important messages.
- **`discord_add_reaction`** / **`discord_remove_reaction`**: Add or remove emoji reactions (standard & custom).

### 🛡️ Moderation & Audit Logs
- **`discord_list_members`**: Search and list server members with their roles and status.
- **`discord_get_member`**: Full member details (roles, permissions, voice status, timeouts).
- **`discord_set_nickname`**: Change or reset member nicknames.
- **`discord_timeout_member`**: Timeout (mute) members for any duration up to 28 days.
- **`discord_kick_member`**: Kick users from the server.
- **`discord_ban_member`** / **`discord_unban_member`** / **`discord_list_bans`**: Manage server bans.
- **`discord_get_audit_logs`**: Inspect Discord server audit log entries (moderation actions, edits).

### 📁 Channel & Category Architecture
- **`discord_list_channels`**: List all categories, text, voice, announcement, forum, and stage channels.
- **`discord_get_channel`**: Detailed channel info with explicit permission overrides.
- **`discord_create_channel`** / **`discord_create_category`**: Create any channel type with custom bitrate, slowmode, and topics.
- **`discord_edit_channel`** / **`discord_delete_channel`**: Edit channel parameters or remove channels.
- **`discord_move_channel`**: Organize channels into categories or reposition them.
- **`discord_set_channel_permissions`**: Set granular allow/deny permission overrides for roles or members.
- **`discord_batch_create_structure`**: Deploy a complete multi-category server architecture in one single tool call.

### 🎭 Roles & Permissions
- **`discord_list_roles`**: Inspect role hierarchy, color hexes, hoists, and permissions.
- **`discord_create_role`** / **`discord_edit_role`** / **`discord_delete_role`**: Create and modify server roles.
- **`discord_assign_role`** / **`discord_remove_role`**: Manage member role assignments.

### 🧵 Threads & Conversations
- **`discord_create_thread`**: Start public or private threads in a channel or from a specific message.
- **`discord_list_threads`**: List active and archived threads with message/member counts.
- **`discord_edit_thread`**: Lock, archive, or rename threads.

### 🔗 Invites, Events & Onboarding
- **`discord_create_invite`** / **`discord_list_invites`** / **`discord_delete_invite`**: Create and manage server invite links.
- **`discord_list_scheduled_events`** / **`discord_create_scheduled_event`** / **`discord_delete_scheduled_event`**: Schedule events in voice, stage, or external locations.
- **`discord_get_onboarding`**: View server onboarding questions and default channels.
- **`discord_set_vanity_url`**: Set custom vanity invite code.

### 🎨 Custom Media (Emojis, Stickers, Soundboard)
- **`discord_list_emojis`** / **`discord_create_emoji`** / **`discord_delete_emoji`**: Manage custom server emojis.
- **`discord_list_stickers`** / **`discord_delete_sticker`**: Manage custom stickers.
- **`discord_list_soundboard_sounds`**: Inspect custom soundboard audio assets.

### 🤖 AutoMod & Webhooks
- **`discord_list_automod_rules`** / **`discord_create_automod_rule`** / **`discord_delete_automod_rule`**: Configure keyword filters, regex filters, and auto-timeout rules.
- **`discord_list_webhooks`** / **`discord_create_webhook`** / **`discord_delete_webhook`** / **`discord_send_webhook_message`**: Manage and trigger webhooks.

---

## 🛠️ MCP Resources & Prompts

### Resources
- `discord://guild/{guildId}/snapshot` — Real-time serialized snapshot of server categories, channels, and roles.
- `discord://guild/{guildId}/roles` — Detailed role hierarchy and bitfield permissions.
- `discord://channel/{channelId}/messages` — Recent message history from a text channel.

### Prompts
- `discord_audit_server` — Comprehensive security, role hierarchy, and structure audit.
- `discord_plan_reorganization` — Design and structure a server for gaming, developer, or company communities.
- `discord_send_announcement` — Compose and format an official server announcement with embeds.

---

## 🚀 Quick Setup Guide

### 1. Create Bot & Get Token
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications).
2. Click **New Application**, name it, and go to the **Bot** tab.
3. Click **Reset Token** and copy the token.
4. Scroll down to **Privileged Gateway Intents** and enable:
   - **Message Content Intent** (Required to read chat)
   - **Server Members Intent** (Required to search/list members)
5. Under **OAuth2 > URL Generator**, select `bot` scope with permissions (`Administrator` or channel/role/member permissions). Copy URL and invite the bot to your server.
6. **Crucial:** In your Discord server settings > **Roles**, drag the bot's role to the top of the role list so it can manage roles below it.

---

## 🔌 Connecting to MCP Clients

### Claude Desktop (`claude_desktop_config.json`)

On Windows: `%APPDATA%\Claude\claude_desktop_config.json`  
On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["C:/Users/walid/work/discord-mcp/bin/index.js"],
      "env": {
        "DISCORD_BOT_TOKEN": "YOUR_DISCORD_BOT_TOKEN_HERE",
        "DISCORD_GUILD_ID": "YOUR_TARGET_SERVER_ID_HERE"
      }
    }
  }
}
```

### Cursor / OpenCode / Windsurf (`mcp.json`)

```json
{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["C:/Users/walid/work/discord-mcp/bin/index.js"],
      "env": {
        "DISCORD_BOT_TOKEN": "YOUR_DISCORD_BOT_TOKEN_HERE",
        "DISCORD_GUILD_ID": "YOUR_TARGET_SERVER_ID_HERE"
      }
    }
  }
}
```

---

## 🧪 Testing

Run the included automated test suite:

```bash
npm test
```

---

## 📄 License
MIT