# discord-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
managing Discord servers. Connect it to an MCP client (Claude Code, Claude
Desktop, etc.) and the assistant can create and manage channels, categories,
roles, webhooks, messages, moderation, voice channels, scheduled events,
forums, emojis, invites, and permissions — 73 tools in all — by calling a bot.

Built in TypeScript with [discord.js](https://discord.js.org) v14 and the
official MCP SDK. Speaks MCP over **stdio**.

## Setup

### 1. Create the bot

1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) → **New Application**.
2. Open **Bot** → **Reset Token** → copy the token. This is your `DISCORD_TOKEN`.
3. Still under **Bot**, scroll to **Privileged Gateway Intents** and enable:
   - **Server Members Intent**
   - **Message Content Intent**

   (Both are required — the server requests these intents at startup and Discord
   will reject the connection if they aren't toggled on.)

### 2. Invite the bot to your server

1. **OAuth2 → URL Generator**.
2. Scopes: `bot` and `applications.commands`.
3. Bot Permissions: **Administrator** (simplest), or the granular set you need
   (Manage Channels, Manage Roles, Manage Webhooks, Kick/Ban Members, Moderate
   Members, Manage Events, Manage Emojis and Stickers, Send Messages, etc.).
4. Open the generated URL in a browser and add the bot to your server.

### 3. (Optional) Get your guild ID

Setting a default guild makes `guildId` optional on guild-scoped tools:

1. Discord → **User Settings → Advanced → Developer Mode** (on).
2. Right-click your server icon → **Copy Server ID**.
3. Use it as `DISCORD_GUILD_ID`.

### 4. Install and build

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

## Connecting to an MCP client

Add to your client's MCP config (e.g. `.mcp.json` for Claude Code):

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

## Environment variables

| Variable | Required | Description |
|---|---|---|
| `DISCORD_TOKEN` | yes | Bot token from the Developer Portal. |
| `DISCORD_GUILD_ID` | no | Default guild; makes `guildId` optional on guild-scoped tools. |

## Tools

### Server info
| Tool | Description |
|---|---|
| `get_server_info` | Retrieve server metadata (name, owner, member count, …). |

### Users & DMs
| Tool | Description |
|---|---|
| `get_user_id_by_name` | Look up a user ID by username for mentions. |
| `send_private_message` | Send a direct message to a user. |
| `edit_private_message` | Edit a DM the bot sent. |
| `delete_private_message` | Delete a DM the bot sent. |
| `read_private_messages` | Read DM history with attachments. |

### Messages
| Tool | Description |
|---|---|
| `send_message` | Post a message to a channel. |
| `edit_message` | Edit a channel message. |
| `delete_message` | Delete a channel message. |
| `read_messages` | Read channel history with attachments. |
| `add_reaction` | Add an emoji reaction to a message. |
| `remove_reaction` | Remove the bot's emoji reaction. |

### Channels
| Tool | Description |
|---|---|
| `create_text_channel` | Create a text channel. |
| `edit_text_channel` | Edit a text channel (name, topic, nsfw, slowmode, category, position). |
| `delete_channel` | Delete a channel. |
| `find_channel` | Find channels by name. |
| `list_channels` | List all channels. |
| `get_channel_info` | Get detailed channel info. |
| `move_channel` | Move a channel to a category / position. |

### Categories
| Tool | Description |
|---|---|
| `create_category` | Create a channel category. |
| `edit_category` | Rename / reorder a category. |
| `delete_category` | Delete a category. |
| `find_category` | Find a category by name. |
| `list_channels_in_category` | List channels in a category. |

### Webhooks
| Tool | Description |
|---|---|
| `create_webhook` | Create a webhook in a channel. |
| `delete_webhook` | Delete a webhook. |
| `list_webhooks` | List a channel's webhooks. |
| `send_webhook_message` | Post a message via a webhook. |

### Roles
| Tool | Description |
|---|---|
| `list_roles` | List all roles. |
| `create_role` | Create a role. |
| `edit_role` | Edit a role. |
| `delete_role` | Delete a role. |
| `assign_role` | Assign a role to a member. |
| `remove_role` | Remove a role from a member. |

### Moderation
| Tool | Description |
|---|---|
| `kick_member` | Kick a member. |
| `ban_member` | Ban a user. |
| `unban_member` | Unban a user. |
| `timeout_member` | Time out (mute) a member. |
| `remove_timeout` | Lift a timeout. |
| `set_nickname` | Set a member's nickname. |
| `get_bans` | List banned users. |

### Voice & stage
| Tool | Description |
|---|---|
| `create_voice_channel` | Create a voice channel. |
| `create_stage_channel` | Create a stage channel. |
| `edit_voice_channel` | Edit voice settings (name, bitrate, user limit, region). |
| `move_member` | Move a member between voice channels. |
| `disconnect_member` | Disconnect a member from voice. |
| `modify_voice_state` | Server mute / deafen a member. |

### Scheduled events
| Tool | Description |
|---|---|
| `create_guild_scheduled_event` | Schedule a server event. |
| `edit_guild_scheduled_event` | Edit an event or change its status. |
| `delete_guild_scheduled_event` | Cancel an event. |
| `list_guild_scheduled_events` | List events. |
| `get_guild_scheduled_event_users` | List event attendees. |

### Channel permissions
| Tool | Description |
|---|---|
| `list_channel_permission_overwrites` | List a channel's permission overwrites. |
| `upsert_role_channel_permissions` | Create / update a role's channel permissions. |
| `upsert_member_channel_permissions` | Create / update a member's channel permissions. |
| `delete_channel_permission_overwrite` | Remove a permission overwrite. |

### Invites
| Tool | Description |
|---|---|
| `create_invite` | Create an invite link. |
| `list_invites` | List active invites. |
| `delete_invite` | Revoke an invite. |
| `get_invite_details` | Inspect an invite by code. |

### Forums
| Tool | Description |
|---|---|
| `create_forum_channel` | Create a forum channel. |
| `edit_forum_channel` | Edit a forum channel. |
| `list_forum_channels` | List forum channels. |
| `get_forum_channel_info` | Get forum channel info. |
| `list_forum_tags` | List a forum's available tags. |
| `create_forum_post` | Start a forum post (thread). |
| `list_forum_posts` | List active forum posts. |
| `modify_forum_post` | Lock / archive / pin / tag a forum post. |

### Emojis
| Tool | Description |
|---|---|
| `list_emojis` | List custom emojis. |
| `get_emoji_details` | Inspect a custom emoji. |
| `create_emoji` | Create a custom emoji (URL or base64, ≤256KB). |
| `edit_emoji` | Rename / restrict an emoji. |
| `delete_emoji` | Delete an emoji. |

## Development

```bash
npm run typecheck   # tsc --noEmit
npm test            # vitest unit tests (mocked discord.js client)
npm run build       # compile to dist/
npm run dev         # run from source via tsx
```

Unit tests cover the pure layer (config, result formatting, error mapping,
guild resolution, the `defineTool` wrapper) and exercise a representative tool
in every module against a mocked discord.js client. Live end-to-end behavior
requires a real bot token + guild and is not run in CI — use the manual
smoke-test checklist below.

### Manual smoke test

With a real `DISCORD_TOKEN` and a test guild, connect the server to your MCP
client and confirm each reflects in the Discord UI:

1. `get_server_info` — returns your server's name and member count.
2. `create_category` → `create_text_channel` (with that `categoryId`).
3. `list_channels` — shows the new channel under the category.
4. `send_message` to the new channel.
5. `delete_channel` then `delete_category` — both disappear from the sidebar.

## Architecture

- `src/config.ts` — env loading.
- `src/client.ts` — discord.js Client (intents + partials) and login.
- `src/lib/` — `tool.ts` (`defineTool` wrapper that turns thrown errors into
  clean error results), `format.ts` (`ok`/`fail`), `errors.ts` (Discord error
  mapping), `guild.ts` (guild resolution), `context.ts` (shared tool context).
- `src/tools/*.ts` — one module per domain; each default-exports
  `(ctx) => Tool[]`. `index.ts` aggregates them into a flat registry.
- `src/server.ts` — builds the MCP server and registers every tool.
- `src/index.ts` — entrypoint: load config → log in → serve over stdio.

Adding a tool is one `defineTool({...})` object in the relevant domain module.

## License

MIT © Farid Naderi