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 (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

Related MCP server: Discord Agent MCP

Pre-built Templates

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.

get_guild_info

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

Channel Management

create_category

Create a channel category with optional permission overwrites.

create_channel

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

edit_channel

Modify an existing channel's settings and permissions.

delete_channel

Delete a channel (cannot be undone).

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.

edit_role

Modify an existing role.

delete_role

Delete a role (cannot be undone).

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.

reorder_roles

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

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.

apply_template

Apply a template to a server.

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"]
}

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

Text Channel Permissions

Voice Channel Permissions

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