Discord Server Setup

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 (edits merge overwrites by target so you don't accidentally expose a private channel)
• Role Management: Create, edit, delete, list, and reorder roles with semantic hierarchy placement (top/above/below, or a top-first ordered list) so important roles land where you mean
• 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

1. Create an application at https://discord.com/developers/applications
2. Add a bot user and copy the bot token
3. Privileged Gateway Intents are NOT required. The server only uses the default (non-privileged) Guilds intent, so you can leave all Privileged Gateway Intents off. (Requesting privileged intents that aren't enabled would actually make login fail.)
4. Generate an OAuth2 invite URL:
   • Go to OAuth2 → URL Generator
   • Select scopes: bot and applications.commands
   • Select the permissions the bot needs — Manage Roles, Manage Channels, and Manage Server cover the current tools; Administrator is the simplest catch-all for full server management.
5. Invite the bot to your Discord server(s) using the generated URL

Important: The bot can only create/move/assign roles below its own highest role in the hierarchy. Make sure the bot's role sits high enough in Server Settings → Roles for the roles you want it to manage.

Installation

Quick Install (One-Liner)

curl -fsSL https://raw.githubusercontent.com/cj-vana/discord-setup-mcp/main/install.sh | bash

This installs to ~/.discord-setup-mcp by default. Set DISCORD_MCP_DIR to customize:

DISCORD_MCP_DIR=/custom/path curl -fsSL https://raw.githubusercontent.com/cj-vana/discord-setup-mcp/main/install.sh | bash

Manual Install

# Clone the repository
git clone https://github.com/cj-vana/discord-setup-mcp.git
cd discord-setup-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Set Bot Token

Option A: Environment Variable

macOS/Linux (temporary - current session only):

export DISCORD_BOT_TOKEN="your-bot-token-here"

macOS/Linux (permanent - add to shell profile):

# For zsh (default on macOS)
echo 'export DISCORD_BOT_TOKEN="your-bot-token-here"' >> ~/.zshrc
source ~/.zshrc

# For bash
echo 'export DISCORD_BOT_TOKEN="your-bot-token-here"' >> ~/.bashrc
source ~/.bashrc

Windows Command Prompt (temporary):

set DISCORD_BOT_TOKEN=your-bot-token-here

Windows PowerShell (temporary):

$env:DISCORD_BOT_TOKEN = "your-bot-token-here"

Windows (permanent - System Environment Variables):

1. Press Win + R, type sysdm.cpl, press Enter
2. Go to Advanced tab → Environment Variables
3. Under "User variables", click New
4. Variable name: DISCORD_BOT_TOKEN
5. Variable value: your-bot-token-here
6. Click OK and restart your terminal

Option B: Configuration File

Create ~/.discord-mcp/config.json:

# Create the directory
mkdir -p ~/.discord-mcp

# Create the config file (replace with your actual token)
cat > ~/.discord-mcp/config.json << 'EOF'
{
  "discordToken": "your-bot-token-here",
  "defaultGuildId": "optional-default-server-id"
}
EOF

# Secure the file (recommended)
chmod 600 ~/.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

{
  "mcpServers": {
    "discord-setup": {
      "command": "node",
      "args": ["/path/to/discord-setup-mcp/dist/index.js"],
      "env": {
        "DISCORD_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

Replace /path/to/discord-setup-mcp with the actual path where you cloned the repository.

Claude Code Configuration

# Add the MCP server
claude mcp add discord-setup-mcp node /path/to/discord-setup-mcp/dist/index.js

# Set the token (if not using config file or system env var)
claude mcp add discord-setup-mcp node /path/to/discord-setup-mcp/dist/index.js -e DISCORD_BOT_TOKEN=your-bot-token-here

Set the token in your environment or use the config file method.

Usage

Basic Workflow

1. List servers the bot has access to
2. Select a server to work with
3. Create channels, roles, or apply templates

Example Commands

List Discord servers
Select the server named "My Server"
Create a text channel called "general-chat"
Create a role called "Moderator" with MANAGE_MESSAGES permission
Make the "admin-chat" category private, only visible to the Admin role
Apply the gaming template to this server

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
guildId	string	Yes	Guild ID or name to select

get_guild_info

Get detailed server information including channels, roles, and settings.

Parameter	Type	Required	Description
guildId	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
name	string	Yes	Category name (1-100 characters)
guildId	string	No	Guild ID or name
position	number	No	Position in channel list
permissionOverwrites	array	No	Permission overwrites for roles/users

create_channel

Create a channel (text, voice, announcement, stage, forum).

Parameter	Type	Required	Description
name	string	Yes	Channel name (1-100 characters)
type	string	No	Channel type: text, voice, announcement, stage, forum (default: text)
guildId	string	No	Guild ID or name
categoryId	string	No	Parent category ID
topic	string	No	Channel topic (text channels, max 1024 chars)
nsfw	boolean	No	Age-restricted channel (default: false)
slowmode	number	No	Slowmode in seconds (0-21600)
bitrate	number	No	Voice channel bitrate (8000-384000)
userLimit	number	No	Voice channel user limit (0-99, 0=unlimited)
position	number	No	Position in channel list
permissionOverwrites	array	No	Permission overwrites for roles/users

edit_channel

Modify an existing channel's settings and permissions.

Parameter	Type	Required	Description
channelId	string	Yes	Channel ID to edit
guildId	string	No	Guild ID or name
name	string	No	New channel name
topic	string	No	New channel topic
nsfw	boolean	No	Age-restricted setting
slowmode	number	No	Slowmode in seconds
bitrate	number	No	Voice channel bitrate
userLimit	number	No	Voice channel user limit
position	number	No	New position
categoryId	string	No	Move to category (null to remove)
permissionOverwrites	array	No	Replace permission overwrites

delete_channel

Delete a channel (cannot be undone).

Parameter	Type	Required	Description
channelId	string	Yes	Channel ID to delete
guildId	string	No	Guild ID or name

Role Management

Discord role positions are inverted. A higher position number is higher in the hierarchy and more powerful; @everyone is position 0 at the bottom; and a brand-new role defaults to the bottom. Use placement / orderedRoleIds below and let the server compute the raw numbers — you rarely need to reason about positions directly. The bot can only place roles below its own highest role.

create_role

Create a role with permissions and optional placement in the hierarchy.

Parameter	Type	Required	Description
name	string	Yes	Role name (1-100 characters)
guildId	string	No	Guild ID or name
color	string/number	No	Hex color (#FF0000) or integer
hoist	boolean	No	Display separately in member list
mentionable	boolean	No	Allow anyone to mention this role
permissions	array	No	Permission names (SCREAMING_SNAKE_CASE); unknown names are rejected, not silently dropped
placement	string	No	top / bottom / above / below — where to rank the role (preferred over position)
referenceRoleId	string	No	Role to place above/below (required when placement is above/below)
position	number	No	Raw Discord position (advanced; overrides placement)

edit_role

Modify an existing role.

Parameter	Type	Required	Description
roleId	string	Yes	Role ID to edit
guildId	string	No	Guild ID or name
name	string	No	New role name
color	string/number	No	New color
hoist	boolean	No	Display separately setting
mentionable	boolean	No	Mentionable setting
permissions	array	No	Replace all permissions
position	number	No	New position in hierarchy

delete_role

Delete a role (cannot be undone).

Parameter	Type	Required	Description
roleId	string	Yes	Role ID to delete
guildId	string	No	Guild ID or name

list_roles

List roles sorted highest-to-lowest (as they appear in Discord's UI), with each role's position and whether the bot can manage it, plus botHighestRolePosition. Call this before reordering or placing roles.

Parameter	Type	Required	Description
guildId	string	No	Guild ID or name

reorder_roles

Reorder roles in the hierarchy. Provide exactly one of the inputs below.

Parameter	Type	Required	Description
orderedRoleIds	array	No	Role IDs from most important (index 0 = top) to least. Positions computed for you. Preferred.
rolePositions	array	No	Advanced: explicit {roleId, position} objects with raw Discord positions
guildId	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
templateId	string	Yes	Template ID to preview

apply_template

Apply a template to a server.

Parameter	Type	Required	Description
templateId	string	Yes	Template ID to apply
guildId	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 @everyone VIEW_CHANNEL)
• Grant specific roles access
• Restrict certain actions for specific users/roles

Permission Overwrite Format

{
  "id": "role-or-user-id",
  "type": "role",
  "allow": ["VIEW_CHANNEL", "SEND_MESSAGES"],
  "deny": ["MANAGE_MESSAGES"]
}

Field	Type	Description
id	string	Role ID or User ID
type	string	role or member
allow	array	Permissions to explicitly allow
deny	array	Permissions to explicitly deny

Example: Make a Category Private

{
  "channelId": "category-id",
  "permissionOverwrites": [
    {
      "id": "everyone-role-id",
      "type": "role",
      "deny": ["VIEW_CHANNEL"]
    },
    {
      "id": "admin-role-id",
      "type": "role",
      "allow": ["VIEW_CHANNEL", "SEND_MESSAGES", "MANAGE_MESSAGES"]
    }
  ]
}

Available Permissions

Use these permission names in role permissions and permission overwrites:

General Permissions

Permission	Description
ADMINISTRATOR	Full server access (bypasses all permissions)
VIEW_CHANNEL	View channels and read messages
MANAGE_CHANNELS	Create, edit, delete channels
MANAGE_ROLES	Create, edit, delete roles below bot's role
MANAGE_GUILD	Change server settings
VIEW_AUDIT_LOG	View server audit log
VIEW_GUILD_INSIGHTS	View server insights
MANAGE_WEBHOOKS	Create, edit, delete webhooks
MANAGE_GUILD_EXPRESSIONS	Manage emojis and stickers
CREATE_INSTANT_INVITE	Create invite links
CHANGE_NICKNAME	Change own nickname
MANAGE_NICKNAMES	Change other members' nicknames
KICK_MEMBERS	Kick members from server
BAN_MEMBERS	Ban members from server
MODERATE_MEMBERS	Timeout members
MANAGE_EVENTS	Create and manage events

Text Channel Permissions

Permission	Description
SEND_MESSAGES	Send messages in text channels
SEND_TTS_MESSAGES	Send text-to-speech messages
MANAGE_MESSAGES	Delete messages, pin messages
EMBED_LINKS	Embed links in messages
ATTACH_FILES	Upload files
READ_MESSAGE_HISTORY	Read past messages
MENTION_EVERYONE	Use @everyone and @here
USE_EXTERNAL_EMOJIS	Use emojis from other servers
USE_EXTERNAL_STICKERS	Use stickers from other servers
ADD_REACTIONS	Add reactions to messages
MANAGE_THREADS	Manage and delete threads
CREATE_PUBLIC_THREADS	Create public threads
CREATE_PRIVATE_THREADS	Create private threads
SEND_MESSAGES_IN_THREADS	Send messages in threads
USE_APPLICATION_COMMANDS	Use slash commands

Voice Channel Permissions

Permission	Description
CONNECT	Connect to voice channels
SPEAK	Speak in voice channels
STREAM	Screen share and video
USE_VAD	Use voice activity detection
PRIORITY_SPEAKER	Be heard over others
MUTE_MEMBERS	Mute other members
DEAFEN_MEMBERS	Deafen other members
MOVE_MEMBERS	Move members between channels
REQUEST_TO_SPEAK	Request to speak in stage channels
USE_EMBEDDED_ACTIVITIES	Use activities
USE_SOUNDBOARD	Use soundboard
USE_EXTERNAL_SOUNDS	Use external sounds
SEND_VOICE_MESSAGES	Send voice messages

Examples

Create a Complete Team Server Structure

1. Select my Discord server
2. Create these roles with permissions:
   - "Admin" with ADMINISTRATOR
   - "Moderator" with MANAGE_MESSAGES, KICK_MEMBERS, MUTE_MEMBERS
   - "Member" with VIEW_CHANNEL, SEND_MESSAGES, CONNECT, SPEAK

3. Create these categories, all private to @everyone but visible to Member role:
   - "General" with channels: welcome, rules, announcements
   - "Discussion" with channels: general-chat, off-topic, help
   - "Voice" with voice channels: General Voice, Gaming, AFK

4. Make the "Admin" category only visible to Admin role

Set Up Private Channels

Make the "staff-chat" channel private:
- Deny VIEW_CHANNEL to @everyone
- Allow VIEW_CHANNEL, SEND_MESSAGES, MANAGE_MESSAGES to Moderator role
- Allow VIEW_CHANNEL, SEND_MESSAGES, ADMINISTRATOR to Admin role

Configure Role Hierarchy

Reorder roles so Admin is highest, then Moderator, then Member, then @everyone

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 (bot and applications.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

Verbose per-call tracing is off by default. Set DISCORD_MCP_DEBUG=1 (or true) in the server's environment to emit debug output to stderr 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