Provides tools for automating Discord server setup and management, including the creation and configuration of servers, channels, categories, and roles, as well as applying pre-built templates for gaming, community, business, and study groups.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Discord Server Setup MCPCreate a new server for me using the Gaming template"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Discord Server Setup MCP
An MCP (Model Context Protocol) server for automating Discord server setup using the Discord Bot API. This server enables AI assistants like Claude to manage servers, channels, roles, permissions, and apply templates through a Discord bot.
Features
Cross-Platform: Works on Windows, Linux, and macOS
No Discord App Required: Operates via Discord Bot API (headless)
Guild Management: Discover, select, and manage multiple Discord servers
Channel Management: Create, edit, and delete channels and categories with permission overwrites
Role Management: Create, edit, delete, and reorder roles with full permission control
Permission Overwrites: Make channels/categories private, grant specific role access
Server Settings: Configure verification levels, content filters, and notification settings
Pre-built Templates: Apply ready-to-use server templates for common use cases
Fast & Reliable: Direct API calls with proper error handling
Pre-built Templates
Template | Description | Roles | Categories | Channels |
Gaming | Comprehensive gaming community with competitive, streaming, and events sections | 10 | 11 | 40+ |
Community | General community server for discussions and social interaction | 6 | 6 | 20+ |
Business | Professional workspace for teams and organizations | 6 | 6 | 18+ |
Study Group | Academic collaboration space for study groups and classes | 5 | 5 | 15+ |
Prerequisites
System Requirements
Node.js 18.0.0 or higher
Discord Bot with appropriate permissions
Discord Bot Setup
Create an application at https://discord.com/developers/applications
Add a bot user and copy the bot token
Enable ALL Privileged Gateway Intents in bot settings (Bot → Privileged Gateway Intents):
Presence Intent
Server Members Intent
Message Content Intent
Generate an OAuth2 invite URL:
Go to OAuth2 → URL Generator
Select scopes:
botandapplications.commandsSelect Administrator permission (required for full server management)
Invite the bot to your Discord server(s) using the generated URL
Important: The bot requires Administrator permission to manage all server settings, roles, channels, and permissions without restrictions.
Installation
Quick Install (One-Liner)
This installs to ~/.discord-setup-mcp by default. Set DISCORD_MCP_DIR to customize:
Manual Install
Configuration
Set Bot Token
Option A: Environment Variable
macOS/Linux (temporary - current session only):
macOS/Linux (permanent - add to shell profile):
Windows Command Prompt (temporary):
Windows PowerShell (temporary):
Windows (permanent - System Environment Variables):
Press
Win + R, typesysdm.cpl, press EnterGo to Advanced tab → Environment Variables
Under "User variables", click New
Variable name:
DISCORD_BOT_TOKENVariable value:
your-bot-token-hereClick OK and restart your terminal
Option B: Configuration File
Create ~/.discord-mcp/config.json:
On Windows, create %USERPROFILE%\.discord-mcp\config.json with the same JSON content.
Claude Desktop Configuration (Recommended)
The easiest method is to set the token directly in your Claude Desktop config:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Replace /path/to/discord-setup-mcp with the actual path where you cloned the repository.
Claude Code Configuration
Set the token in your environment or use the config file method.
Usage
Basic Workflow
List servers the bot has access to
Select a server to work with
Create channels, roles, or apply templates
Example Commands
Tool Reference
Guild Management
list_guilds
List all servers the bot can access.
select_guild
Set the active server for subsequent operations.
Parameter | Type | Required | Description |
| string | Yes | Guild ID or name to select |
get_guild_info
Get detailed server information including channels, roles, and settings.
Parameter | Type | Required | Description |
| string | No | Guild ID or name (uses current if not specified) |
Channel Management
create_category
Create a channel category with optional permission overwrites.
Parameter | Type | Required | Description |
| string | Yes | Category name (1-100 characters) |
| string | No | Guild ID or name |
| number | No | Position in channel list |
| array | No | Permission overwrites for roles/users |
create_channel
Create a channel (text, voice, announcement, stage, forum).
Parameter | Type | Required | Description |
| string | Yes | Channel name (1-100 characters) |
| string | No | Channel type: |
| string | No | Guild ID or name |
| string | No | Parent category ID |
| string | No | Channel topic (text channels, max 1024 chars) |
| boolean | No | Age-restricted channel (default: false) |
| number | No | Slowmode in seconds (0-21600) |
| number | No | Voice channel bitrate (8000-384000) |
| number | No | Voice channel user limit (0-99, 0=unlimited) |
| number | No | Position in channel list |
| array | No | Permission overwrites for roles/users |
edit_channel
Modify an existing channel's settings and permissions.
Parameter | Type | Required | Description |
| string | Yes | Channel ID to edit |
| string | No | Guild ID or name |
| string | No | New channel name |
| string | No | New channel topic |
| boolean | No | Age-restricted setting |
| number | No | Slowmode in seconds |
| number | No | Voice channel bitrate |
| number | No | Voice channel user limit |
| number | No | New position |
| string | No | Move to category (null to remove) |
| array | No | Replace permission overwrites |
delete_channel
Delete a channel (cannot be undone).
Parameter | Type | Required | Description |
| string | Yes | Channel ID to delete |
| string | No | Guild ID or name |
Role Management
create_role
Create a role with permissions.
Parameter | Type | Required | Description |
| string | Yes | Role name (1-100 characters) |
| string | No | Guild ID or name |
| string/number | No | Hex color ( |
| boolean | No | Display separately in member list |
| boolean | No | Allow anyone to mention this role |
| array | No | Array of permission names |
| number | No | Position in role hierarchy |
edit_role
Modify an existing role.
Parameter | Type | Required | Description |
| string | Yes | Role ID to edit |
| string | No | Guild ID or name |
| string | No | New role name |
| string/number | No | New color |
| boolean | No | Display separately setting |
| boolean | No | Mentionable setting |
| array | No | Replace all permissions |
| number | No | New position in hierarchy |
delete_role
Delete a role (cannot be undone).
Parameter | Type | Required | Description |
| string | Yes | Role ID to delete |
| string | No | Guild ID or name |
reorder_roles
Reorder roles in the hierarchy.
Parameter | Type | Required | Description |
| array | Yes | Array of |
| string | No | Guild ID or name |
Server Settings
update_server_settings
Update multiple server settings at once.
set_verification_level
Set member verification level (0-4).
set_content_filter
Set explicit content filter level.
set_default_notifications
Set default notification setting for new members.
Templates
list_templates
List available pre-built templates.
preview_template
View template details before applying.
Parameter | Type | Required | Description |
| string | Yes | Template ID to preview |
apply_template
Apply a template to a server.
Parameter | Type | Required | Description |
| string | Yes | Template ID to apply |
| string | No | Guild ID or name |
Permission Overwrites
Permission overwrites allow you to customize access to channels and categories. Use them to:
Make channels private (deny
@everyoneVIEW_CHANNEL)Grant specific roles access
Restrict certain actions for specific users/roles
Permission Overwrite Format
Field | Type | Description |
| string | Role ID or User ID |
| string |
|
| array | Permissions to explicitly allow |
| array | Permissions to explicitly deny |
Example: Make a Category Private
Available Permissions
Use these permission names in role permissions and permission overwrites:
General Permissions
Permission | Description |
| Full server access (bypasses all permissions) |
| View channels and read messages |
| Create, edit, delete channels |
| Create, edit, delete roles below bot's role |
| Change server settings |
| View server audit log |
| View server insights |
| Create, edit, delete webhooks |
| Manage emojis and stickers |
| Create invite links |
| Change own nickname |
| Change other members' nicknames |
| Kick members from server |
| Ban members from server |
| Timeout members |
| Create and manage events |
Text Channel Permissions
Permission | Description |
| Send messages in text channels |
| Send text-to-speech messages |
| Delete messages, pin messages |
| Embed links in messages |
| Upload files |
| Read past messages |
| Use @everyone and @here |
| Use emojis from other servers |
| Use stickers from other servers |
| Add reactions to messages |
| Manage and delete threads |
| Create public threads |
| Create private threads |
| Send messages in threads |
| Use slash commands |
Voice Channel Permissions
Permission | Description |
| Connect to voice channels |
| Speak in voice channels |
| Screen share and video |
| Use voice activity detection |
| Be heard over others |
| Mute other members |
| Deafen other members |
| Move members between channels |
| Request to speak in stage channels |
| Use activities |
| Use soundboard |
| Use external sounds |
| Send voice messages |
Examples
Create a Complete Team Server Structure
Set Up Private Channels
Configure Role Hierarchy
Troubleshooting
Bot Not Connecting
Verify bot token is correct
Check that ALL Privileged Gateway Intents are enabled in Discord Developer Portal
Ensure the bot user is created (not just the application)
Can't Manage Roles/Channels
Ensure bot has Administrator permission
Bot's role must be higher than roles it manages (drag bot role up in server settings)
Verify the bot was invited with correct OAuth2 scopes (
botandapplications.commands)
Permission Errors
Grant the bot Administrator permission for unrestricted access
Bot can only manage roles below its highest role in the hierarchy
Drag the bot's role higher in Server Settings → Roles
Guild Not Found
Confirm bot is in the server
Try using guild ID instead of name
Enable Discord Developer Mode to copy IDs (User Settings → Advanced)
Debug Logging
Debug logs are written to /tmp/discord-mcp-debug.log for troubleshooting permission and API issues.
Security
Never share your bot token - treat it like a password
Use environment variables - don't commit tokens to version control
Regenerate tokens if compromised - reset in Discord Developer Portal
Limit server access - only add the bot to servers you trust
Restrict file permissions -
chmod 600 ~/.discord-mcp/config.json
Architecture
Runtime: Node.js 18+
Language: TypeScript
Discord API: discord.js v14
MCP SDK: @modelcontextprotocol/sdk
Validation: Zod
See CLAUDE.md for development documentation.
Contributing
Contributions are welcome! Please read CONTRIBUTING.md for guidelines.
License
MIT License - see LICENSE file for details.
Acknowledgments
Built with discord.js
Powered by Model Context Protocol
Created for use with Claude