1. Create a Discord bot

Follow the Bot Setup Guide to create a bot in the Discord Developer Portal and get your token.

2. Add to your MCP config

Add the following discord entry to your client's config file:

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@quadslab.io/discord-mcp"],
      "env": {
        "DISCORD_TOKEN": "your-bot-token",
        "DISCORD_GUILD_ID": "your-server-id"
      }
    }
  }
}

| Client | Config file location | |--------|---------------------| | Claude Code | .mcp.json in your project root | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) | | Cursor | ~/.cursor/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json |

3. Connect

• Claude Code: Type /mcp to connect
• Claude Desktop: Restart the app
• Cursor / Windsurf: Reload the window

git clone https://github.com/HardHeadHackerHead/discord-mcp.git
cd discord-mcp
npm install
cp .env.example .env
# Edit .env with your DISCORD_TOKEN and DISCORD_GUILD_ID
npm run build
npm start

Guild (2 tools)

| Tool | Description | |------|-------------| | list_guilds | List all servers the bot is a member of | | get_guild_info | Detailed server info — member count, channels, roles, features, boost tier |

Roles (11 tools)

| Tool | Description | |------|-------------| | list_roles | List all roles sorted by position with colors and member counts | | create_role | Create a new role with name, color, hoist, and mentionable options | | delete_role | Delete a role (with managed role protection) | | modify_role | Change a role's name, color, hoist, mentionable, or position | | get_role_permissions | View all permissions granted to a role | | modify_role_permissions | Grant or revoke specific permissions on a role | | set_role_icon | Set a Unicode emoji or image as the role icon (requires boost level 2+) | | assign_role | Add a role to a member | | remove_role | Remove a role from a member | | get_role_members | List all members who have a specific role | | clone_role | Duplicate a role with all its permissions and settings |

Channels (20 tools)

| Tool | Description | |------|-------------| | list_channels | List all channels organized by category | | create_text_channel | Create a new text channel, optionally in a category | | create_voice_channel | Create a new voice channel with bitrate and user limit | | create_category | Create a new channel category | | create_forum_channel | Create a new forum channel with optional tags and default settings | | delete_channel | Delete any channel type | | modify_channel | Change name, topic, category, NSFW, position, user limit | | set_channel_permissions | Set permission overwrites for a role or user on a channel | | view_channel_permissions | View all permission overwrites on a channel | | lock_channel | Deny SendMessages for @everyone (quick lock) | | unlock_channel | Remove SendMessages deny for @everyone | | set_slowmode | Set rate limit (0–21600 seconds) on a text channel | | clone_channel | Duplicate a channel with all permissions and settings | | reorder_channels | Reorder channels by specifying new positions | | set_voice_region | Set the RTC region for a voice channel | | follow_announcement_channel | Follow an announcement channel to cross-post into another channel | | create_stage_channel | Create a new stage channel | | get_channel_invites | List all invites for a specific channel | | set_channel_topic | Set or clear a channel's topic/description | | get_voice_members | List all members currently in a voice or stage channel |

Members (15 tools)

| Tool | Description | |------|-------------| | list_members | List members with optional role and search filters | | get_member | Detailed member info — roles, join date, account age, permissions | | kick_member | Kick a member from the server | | ban_member | Ban a member with optional message deletion (0–7 days) | | unban_member | Remove a ban by username or user ID | | timeout_member | Apply a timeout (10m, 1h, 1d, 1w) or remove one | | prune_members | Remove inactive members (supports dry run and role filtering) | | bulk_assign_role | Assign a role to multiple members at once | | bulk_remove_role | Remove a role from multiple members at once | | set_nickname | Change a member's nickname or reset it | | move_to_voice | Move a member to a different voice channel | | disconnect_from_voice | Disconnect a member from their voice channel | | get_member_permissions | Get a member's effective permissions in a specific channel | | search_members | Search members by username, nickname, or role with advanced filters | | bulk_timeout_members | Apply a timeout to multiple members at once |

Messages (14 tools)

| Tool | Description | |------|-------------| | get_messages | Fetch recent messages from a text or voice channel | | get_message | Fetch a single message by ID with full details | | send_message | Send a text message, optionally as a reply | | send_embed | Send a rich embed with title, fields, images, and footer | | edit_message | Edit a message previously sent by the bot | | delete_message | Delete a single message by ID | | bulk_delete_messages | Delete 2–100 messages at once (< 14 days old), optionally filtered by user | | crosspost_message | Publish a message in an announcement channel to all following channels | | pin_message | Pin a message | | unpin_message | Unpin a message | | list_pinned_messages | Get all pinned messages in a channel | | add_reaction | Add a reaction from the bot to a message | | remove_reaction | Remove the bot's reaction from a message | | search_messages | Search messages in a channel by content, author, or date range |

Reactions (1 tool)

| Tool | Description | |------|-------------| | get_reactions | Get all reactions on a message with full reactor details — account creation date, server join date, roles, avatar, boost status. Optionally filter by emoji. |

Server Admin (16 tools)

| Tool | Description | |------|-------------| | edit_server | Modify server name, description, verification level, notification defaults | | list_invites | List all active invite links with usage stats and expiration | | create_invite | Generate a new invite with configurable max age, uses, and temporary flag | | delete_invite | Revoke an invite by code | | get_audit_log | Fetch audit log entries, optionally filtered by action type or user | | list_bans | View all banned users with reasons | | get_welcome_screen | Get the server welcome screen configuration | | set_welcome_screen | Configure the welcome screen with description and featured channels | | get_widget | Get the server widget settings | | set_widget | Configure the server widget (enable/disable, set channel) | | get_vanity_url | Get the server vanity URL (requires VANITY_URL feature) | | list_integrations | List all integrations (bots, apps) connected to the server | | delete_integration | Remove an integration from the server | | get_server_preview | Get the server's public preview information | | set_server_icon | Set or remove the server icon from a URL | | set_server_banner | Set or remove the server banner image (requires boost level 2+) |

Threads (10 tools)

| Tool | Description | |------|-------------| | list_threads | List active threads, optionally filtered to a channel | | create_thread | Start a thread from a message or as a standalone public thread | | archive_thread | Archive a thread | | unarchive_thread | Unarchive a thread | | delete_thread | Delete a thread | | lock_thread | Lock a thread (prevent new messages without archiving) | | unlock_thread | Unlock a thread | | get_thread_members | List all members of a thread | | add_thread_member | Add a member to a thread | | remove_thread_member | Remove a member from a thread |

Forums (5 tools)

| Tool | Description | |------|-------------| | create_forum_post | Create a new post (thread) in a forum channel with optional tags | | list_forum_tags | List all available tags on a forum channel | | create_forum_tag | Add a new tag to a forum channel (max 20 per channel) | | edit_forum_tag | Edit an existing forum tag's name, emoji, or moderated status | | delete_forum_tag | Remove a tag from a forum channel |

Emojis & Stickers (7 tools)

| Tool | Description | |------|-------------| | list_emojis | List all custom emojis with names, IDs, animated status, and URLs | | create_emoji | Upload a new custom emoji from a URL | | delete_emoji | Remove a custom emoji by name or ID | | rename_emoji | Rename a custom emoji | | list_stickers | List all custom stickers with descriptions and format info | | create_sticker | Upload a new custom sticker from a URL | | delete_sticker | Remove a custom sticker by name or ID |

Webhooks (4 tools)

| Tool | Description | |------|-------------| | list_webhooks | List all webhooks, optionally filtered to a channel | | create_webhook | Create a webhook on a channel with name and optional avatar | | delete_webhook | Delete a webhook by ID | | send_webhook_message | Send a message via webhook with optional name/avatar override |

Scheduled Events (5 tools)

| Tool | Description | |------|-------------| | list_events | List all scheduled events with times, status, type, and attendee count | | create_event | Create a voice, stage, or external event with start/end times | | edit_event | Modify an event's name, description, times, or status | | delete_event | Delete a scheduled event | | get_event_users | List users who have expressed interest in an event |

Stage Instances (3 tools)

| Tool | Description | |------|-------------| | list_stage_instances | List all active stage instances with topic and channel info | | start_stage | Start a new stage instance on a stage channel with a topic | | end_stage | End an active stage instance |

Auto-Moderation (4 tools)

| Tool | Description | |------|-------------| | list_automod_rules | List all automod rules with triggers, actions, and exemptions | | create_automod_rule | Create a rule — keyword filter, spam detection, keyword presets, or mention spam | | edit_automod_rule | Modify a rule's keywords, actions, exemptions, or enabled state | | delete_automod_rule | Delete an automod rule |

Polls (3 tools)

| Tool | Description | |------|-------------| | create_poll | Create a poll in a channel with multiple choice options and duration | | get_poll_results | Get the current results and vote counts for a poll | | end_poll | End a poll early and finalize the results |

Direct Messages (2 tools)

| Tool | Description | |------|-------------| | send_dm | Send a direct message to a server member | | send_dm_embed | Send a rich embed as a direct message to a server member |

Bot Presence (2 tools)

| Tool | Description | |------|-------------| | set_bot_presence | Set the bot's status and activity (playing, watching, listening, etc.) | | get_bot_info | Get the bot's current user info, status, and connection details |

Server Templates (4 tools)

| Tool | Description | |------|-------------| | list_templates | List all templates for the server | | create_template | Create a new server template from the current server configuration | | delete_template | Delete a server template by code | | sync_template | Sync a server template with the current server state |

Application Commands (4 tools)

| Tool | Description | |------|-------------| | list_commands | List all registered application (slash) commands | | create_command | Register a new slash command with name, description, and options | | edit_command | Modify an existing slash command | | delete_command | Remove a registered slash command |

Onboarding (2 tools)

| Tool | Description | |------|-------------| | get_onboarding | Get the server's onboarding configuration and prompts | | edit_onboarding | Edit the server onboarding settings, prompts, and default channels |

"DISCORD_TOKEN is not set"

The MCP server can't find your bot token. Either:

• Run npx @quadslab.io/discord-mcp init to set up automatically
• Or check that your .mcp.json / MCP client config has the DISCORD_TOKEN in the env block

"Request with opcode 8 was rate limited"

Discord rate-limited the gateway connection (usually from member caching on large servers). The server retries automatically — if you're still seeing this, wait 30 seconds and try again. This is a Discord-side limit, not a bug.

"Role @everyone not found"

Fixed in v1.2.2+. Update to the latest version:

npx @quadslab.io/discord-mcp@latest init

"Missing Access" or "Missing Permissions"

The bot's role doesn't have the required permissions. Either:

• Re-invite the bot using the URL from npx @quadslab.io/discord-mcp init (it includes all permissions)
• Or go to Server Settings > Roles and grant the missing permissions to the bot's role
• Run npx @quadslab.io/discord-mcp check to see exactly which permissions are missing

Bot can't manage a specific role

Discord enforces role hierarchy — the bot can only manage roles below its own highest role. Move the bot's role higher in Server Settings > Roles.

Bot can't read messages

Enable Message Content Intent in the Discord Developer Portal > Bot tab.

"Used disallowed intents"

Enable Server Members Intent and Message Content Intent in the Discord Developer Portal > Bot tab. Both are required.

Tools work but are slow

The first tool call after startup may be slow due to caching. Subsequent calls use the cached data and should be instant. If all calls are slow, check your network connection to Discord.

.mcp.json was created in the wrong directory

If you ran init from Desktop or Downloads, update to v1.2.3+ which auto-detects this and writes to ~/.claude.json (global config) instead. Or move the .mcp.json file to your project root.