# discord-mcp

An MCP server for managing Discord servers through any [MCP-compatible](https://modelcontextprotocol.io) AI client. Once connected, you just describe what you want:

> **You:** create a channel called `dev-chat` under the Engineering category

> **You:** make a role called Moderator that can kick and ban, then give it to @alex

> **You:** post "deploy is live 🚀" in #announcements

> **You:** make #staff-only private — hide it from @everyone but let the Staff role in

Your AI client talks to this server over [MCP](https://modelcontextprotocol.io), which translates requests into real Discord API calls via [discord.js](https://discord.js.org).

---

## What it can do

| Area | Tools |
| --- | --- |
| **Servers** | `list_servers`, `get_server_info` |
| **Channels** | `list_channels`, `create_channel`, `edit_channel`, `delete_channel` |
| **Messages** | `send_message`, `send_embed`, `read_messages`, `edit_message`, `delete_message` |
| **Roles** | `list_roles`, `create_role`, `delete_role`, `assign_role`, `remove_role` |
| **Members** | `list_members`, `get_member`, `kick_member`, `ban_member`, `timeout_member` |
| **Channel permissions** | `list_channel_permissions`, `set_channel_permission`, `remove_channel_permission` |
| **Threads** | `create_thread`, `list_threads`, `archive_thread`, `unarchive_thread` |
| **Invites** | `create_invite`, `list_invites`, `delete_invite` |
| **Scheduled events** | `create_event`, `list_events`, `delete_event` |
| **Webhooks** | `create_webhook`, `list_webhooks`, `delete_webhook`, `send_webhook_message` |
| **Emoji & stickers** | `list_emojis`, `create_emoji`, `delete_emoji`, `list_stickers` |

---

## Setup

### 1. Create the Discord bot

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) →
   **New Application**, give it a name, **Create**.
2. Open the **Bot** tab → **Reset Token** → **Copy**. This is your `DISCORD_TOKEN`.
3. *(Optional)* To **list members** or **read message text**, scroll to
   **Privileged Gateway Intents** and enable **Server Members Intent** and
   **Message Content Intent**. You'll also set `DISCORD_PRIVILEGED_INTENTS=true` later.
   Skip this if you only need to create channels/roles and send messages.

### 2. Invite the bot to your server

1. In the Developer Portal → **OAuth2** → **URL Generator**.
2. Under **Scopes**, check **`bot`**.
3. Under **Bot Permissions**, pick what you want it to do. For full management the simplest
   choice is **Administrator**.
4. Open the generated URL, choose your server, **Authorize**.
5. **Important — role hierarchy:** in **Server Settings → Roles**, drag the bot's role
   **above** the roles/members you want it to manage.

### 3. Install and build

Requires **Node.js 18+** (20+ recommended).

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

Then create your `.env` from the template and fill in the token:

### 4. Connect it to your MCP client

**Option A — project config (recommended).** This repo includes a [`.mcp.json`](./.mcp.json).
Run your MCP client *from this directory* and it picks it up automatically.

**Option B — global registration (Claude Code example).** Use an absolute path to make the
server available in any session:

```bash
claude mcp add discord -- node /absolute/path/to/discord-mcp/dist/index.js
```
---