README.md
An MCP server that exposes Discord admin operations as tools.
Discord MCP Server
An MCP server that exposes Discord admin operations as tools. Built with TypeScript + Bun, using direct Discord REST API v10 calls (no discord.js dependency).
Features
- 33 tools for Discord server administration
- Channel management, role management, member moderation, server configuration
- Composite tools for common multi-step workflows (category setup, channel lockdown, bulk role assignment)
- Built-in rate limiting with per-route bucket tracking and automatic retry
- Audit log reasons for all write operations via
X-Audit-Log-Reasonheader
Prerequisites
- Bun v1.0+
- A Discord bot token with appropriate permissions
Discord Bot Setup
- Go to https://discord.com/developers/applications
- Create a new application
- Go to the Bot tab, create a bot, and copy the token
- Enable required intents: Server Members Intent (needed for member listing)
- Go to OAuth2 > URL Generator
- Select scopes:
bot - Select permissions: Administrator (or granular permissions: Manage Channels, Manage Roles, Kick Members, Ban Members, Manage Guild, Moderate Members)
- Copy the generated invite URL and add the bot to your server
- Copy the Guild ID (right-click the server name in Discord > Copy Server ID -- requires Developer Mode enabled in Discord settings)
Installation
git clone <repo-url>
cd discord-mcp
bun install
Configuration
cp .env.example .env
# Edit .env with your bot token and optional guild ID
Environment variables:
| Variable | Required | Description |
|---|---|---|
DISCORD_BOT_TOKEN |
Yes | Your Discord bot token |
DISCORD_GUILD_ID |
No | Default guild ID. If set, tools will use this as the default and the guild_id parameter becomes optional. |
Usage with Claude Code
Add the following to .claude/mcp.json:
{
"mcpServers": {
"discord": {
"command": "bun",
"args": ["run", "/absolute/path/to/discord-mcp/src/index.ts"],
"env": {
"DISCORD_BOT_TOKEN": "your-token-here",
"DISCORD_GUILD_ID": "your-guild-id"
}
}
}
}
Usage with Claude Desktop
Add the following to claude_desktop_config.json:
{
"mcpServers": {
"discord": {
"command": "bun",
"args": ["run", "/absolute/path/to/discord-mcp/src/index.ts"],
"env": {
"DISCORD_BOT_TOKEN": "your-token-here",
"DISCORD_GUILD_ID": "your-guild-id"
}
}
}
}
Testing with MCP Inspector
bunx @modelcontextprotocol/inspector -- bun run src/index.ts
Tool Reference
Server Info (3 tools)
| Tool | Description |
|---|---|
get_guild |
Get detailed server information including member counts, features, and boost status |
get_guild_preview |
Get server preview with emojis, stickers, and approximate counts |
modify_guild |
Update server settings (name, description, verification level, icon, banner, system channel) |
Channels (7 tools)
| Tool | Description |
|---|---|
list_channels |
List all channels in a guild, grouped by category |
get_channel |
Get detailed information about a specific channel |
create_channel |
Create a new channel (text, voice, category, announcement, stage, forum, media) |
modify_channel |
Modify a channel's settings (name, topic, position, parent, NSFW) |
delete_channel |
Permanently delete a channel |
set_channel_permissions |
Set permission overwrites for a role or member on a channel |
delete_channel_permissions |
Remove a permission overwrite for a role or member on a channel |
Roles (8 tools)
| Tool | Description |
|---|---|
list_roles |
List all roles in a guild, sorted by position |
get_role |
Get detailed information about a specific role |
create_role |
Create a new role with optional name, color, hoist, mentionable, and permissions |
modify_role |
Modify an existing role's properties |
delete_role |
Permanently delete a role |
reorder_roles |
Reorder roles by specifying new positions |
add_role_to_member |
Add a role to a guild member |
remove_role_from_member |
Remove a role from a guild member |
Members and Moderation (10 tools)
| Tool | Description |
|---|---|
list_members |
List guild members with pagination (up to 1000 per request) |
search_members |
Search for members by username or nickname prefix |
get_member |
Get detailed info about a member (roles, join date, timeout status) |
modify_member |
Modify a member's nickname, roles, or voice mute/deafen status |
kick_member |
Remove a member from the guild (they can rejoin with an invite) |
ban_member |
Ban a user from the guild, optionally deleting recent messages (up to 7 days) |
unban_member |
Remove a ban, allowing the user to rejoin |
list_bans |
List all banned users with reasons |
get_ban |
Get ban information for a specific user |
timeout_member |
Temporarily prevent a member from in |
Tools (5)
get_guildGet detailed server information including member counts, features, and boost statuscreate_channelCreate a new channel (text, voice, category, announcement, stage, forum, media)add_role_to_memberAdd a role to a guild memberkick_memberRemove a member from the guildban_memberBan a user from the guild, optionally deleting recent messagesEnvironment Variables
DISCORD_BOT_TOKENrequiredYour Discord bot tokenDISCORD_GUILD_IDDefault guild ID for tool operationsConfiguration
claude_desktop_config.json
{"mcpServers": {"discord": {"command": "bun", "args": ["run", "/absolute/path/to/discord-mcp/src/index.ts"], "env": {"DISCORD_BOT_TOKEN": "your-token-here", "DISCORD_GUILD_ID": "your-guild-id"}}}}Try it
→List all channels in the server and group them by category.
→Ban the user with the username 'troublemaker' and delete their messages from the last 7 days.
→Create a new text channel named 'announcements' and set the appropriate permissions.
→Add the 'Moderator' role to the user with ID 123456789.
→Get the current server statistics including member count and boost status.