Discord Setup

MCP server for automating Discord server setup on macOS using AppleScript/JXA

1# Discord Setup

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Last checked: 2026-10-28

Stars: 30
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Discord Setup?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Discord Setup need an API key?

No required environment variable is listed on this record.

What transport does Discord Setup use?

Discord Setup runs locally over stdio.

When was Discord Setup last checked?

Last checked 2026-10-28. MCP server for automating Discord server setup on macOS using AppleScript/JXA

From the publisher

Documentation

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

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

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

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

Discord Setup

cj-vana30starsClaim this server

MCP server for automating Discord server setup on macOS using AppleScript/JXA

Communication

Install Run on PlugMCPClaim this server

GitHub

Run on PlugMCP

1# Discord Setup

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Last checked: 2026-10-28

Stars: 30
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Discord Setup?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Discord Setup need an API key?

No required environment variable is listed on this record.

What transport does Discord Setup use?

Discord Setup runs locally over stdio.

When was Discord Setup last checked?

Last checked 2026-10-28. MCP server for automating Discord server setup on macOS using AppleScript/JXA

From the publisher

Documentation

Discord Server Setup MCP

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

Create an application at https://discord.com/developers/applications
Add a bot user and copy the bot token
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.)
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.
Invite the bot to your Discord server(s) using the generated URL

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

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`

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