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: bot and applications.commands
- Select 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)

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):

Press Win + R, type sysdm.cpl, press Enter
Go to Advanced tab → Environment Variables
Under "User variables", click New
Variable name: DISCORD_BOT_TOKEN
Variable value: your-bot-token-here
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

List servers the bot has access to
Select a server to work with
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

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github		.github
docs		docs
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
MIGRATION_COMPLETE.md		MIGRATION_COMPLETE.md
README.md		README.md
SECURITY.md		SECURITY.md
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

cj-vana/discord-setup-mcp

Folders and files

Latest commit

History

Repository files navigation

Discord Server Setup MCP

Features

Pre-built Templates

Prerequisites

System Requirements

Discord Bot Setup

Installation

Quick Install (One-Liner)

Manual Install

Configuration

Set Bot Token

Option A: Environment Variable

Option B: Configuration File

Claude Desktop Configuration (Recommended)

Claude Code Configuration

Usage

Basic Workflow

Example Commands

Tool Reference

Guild Management

list_guilds

select_guild

get_guild_info

Channel Management

create_category

create_channel

edit_channel

delete_channel

Role Management

create_role

edit_role

delete_role

reorder_roles

Server Settings

update_server_settings

set_verification_level

set_content_filter

set_default_notifications

Templates

list_templates

preview_template

apply_template

Permission Overwrites

Permission Overwrite Format

Example: Make a Category Private

Available Permissions

General Permissions

Text Channel Permissions

Voice Channel Permissions

Examples

Create a Complete Team Server Structure

Set Up Private Channels

Configure Role Hierarchy

Troubleshooting

Bot Not Connecting

Can't Manage Roles/Channels

Permission Errors

Guild Not Found

Debug Logging

Security

Architecture

Contributing

License

Acknowledgments

About

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

`list_guilds`

`select_guild`

`get_guild_info`

`create_category`

`create_channel`

`edit_channel`

`delete_channel`

`create_role`

`edit_role`

`delete_role`

`reorder_roles`

`update_server_settings`

`set_verification_level`

`set_content_filter`

`set_default_notifications`

`list_templates`

`preview_template`

`apply_template`

Packages