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

1. Create an application at https://discord.com/developers/applications
2. Add a bot user and copy the bot token
3. Enable ALL Privileged Gateway Intents in bot settings (Bot → Privileged Gateway Intents):
   • Presence Intent
   • Server Members Intent
   • Message Content Intent
4. Generate an OAuth2 invite URL:
   • Go to OAuth2 → URL Generator
   • Select scopes: bot and applications.commands
   • Select Administrator permission (required for full server management)
5. 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)

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

create_role

Create a role with permissions.

| 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 | Array of permission names | | position | number | No | Position in role hierarchy |

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 |

reorder_roles

Reorder roles in the hierarchy.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | rolePositions | array | Yes | Array of {roleId, position} objects | | 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

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