discord-mcp

Control your Discord server with AI. Connect this MCP server to Claude, Cursor, Copilot, or any MCP-compatible AI tool and manage your server through conversation — no Discord dashboard required.

What you can do

Once connected, just ask your AI assistant naturally:

• Set up a server from scratch — create channels, categories, and roles with a consistent layout and style
• Manage members — search members, assign roles, issue timeouts, kick or ban users, view ban lists
• Send and manage messages — post to channels, edit messages, pin important posts, add reactions, purge messages
• Moderate automatically — create and manage AutoMod rules to filter content
• Schedule events — create and manage scheduled events, stage instances, and announcements
• Organize channels — reorder channels and categories, set permissions per role, manage threads
• Customize your server — update server settings, manage emojis, stickers, and soundboard sounds
• Create invites and webhooks — generate invite links, set up webhooks for integrations
• Review activity — read audit logs to see who did what and when

Destructive actions (deleting channels, banning members, purging messages) always require explicit confirmation before anything happens.

Requirements

• Bun — the JavaScript runtime that runs this server
• A Discord bot token and application ID (create one here)

Setup

1. Install dependencies

bun install

2. Create your config file

cp .env.example .env

3. Fill in your Discord credentials

Open .env and set at minimum:

DISCORD_TOKEN=your_bot_token_here
DISCORD_APPLICATION_ID=your_app_id_here

Make sure your bot has been invited to your server with the necessary permissions.

4. Start the server

bun run start

The MCP server is now running at http://127.0.0.1:3456/mcp.

Connect to your AI tool

Claude Desktop

Open Claude Desktop settings → MCP → Add server:

• URL: http://127.0.0.1:3456/mcp
• Transport: Streamable HTTP

Restart Claude Desktop after saving.

Claude Code

claude mcp add --transport http discord-mcp http://127.0.0.1:3456/mcp

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "discord-mcp": {
      "url": "http://127.0.0.1:3456/mcp"
    }
  }
}

Restart Cursor, then verify tools are available in Agent chat.

VS Code (Copilot / Agent Mode)

Create .vscode/mcp.json in your project:

{
  "servers": {
    "discord-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3456/mcp"
    }
  }
}

Then run MCP: List Servers from the command palette to verify.

GitHub Copilot CLI

Edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "discord-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3456/mcp",
      "tools": ["*"]
    }
  }
}

Safety

A few built-in guardrails:

• Guild allowlist — set DISCORD_GUILD_ALLOWLIST to a comma-separated list of server IDs to restrict which servers the bot can touch
• Dry run mode — set DISCORD_DRY_RUN=true to preview what would happen without actually making any changes
• Confirmation required — delete and ban operations require confirm: true to execute

Optional: keep your bot online (Gateway mode)

By default the server uses Discord's REST API only — no persistent connection. If you want the bot to appear online and enable presence features, add this to your .env:

DISCORD_GATEWAY_ENABLED=true
DISCORD_GATEWAY_INTENTS=Guilds

Advanced configuration

All available environment variables:

Variable	Default	Description
DISCORD_TOKEN	required	Your bot token
DISCORD_APPLICATION_ID	required	Your application ID
DISCORD_BOT_ID	optional	Bot user ID
DISCORD_GUILD_ALLOWLIST	optional	Comma-separated list of allowed guild IDs
DISCORD_DRY_RUN	false	Block all mutations, return previews instead
DISCORD_GATEWAY_ENABLED	false	Enable live Gateway connection
DISCORD_GATEWAY_INTENTS	Guilds	Comma-separated intent names or numeric bitfield
MCP_HTTP_HOST	127.0.0.1	Host to bind to
MCP_HTTP_PORT	3456	Port to listen on
MCP_HTTP_PATH	/mcp	URL path for the MCP endpoint
MCP_SESSION_TTL_MS	3600000	How long an idle session lives (ms)
MCP_SESSION_CLEANUP_MS	300000	How often stale sessions are cleaned up (ms)

For developers

To run in dev mode with auto-reload:

bun --watch run src/index.ts

Type-check and build:

bun run check   # type-check only
bun run build   # compile to dist/
bun test src    # run tests

Health check:

curl http://127.0.0.1:3456/health

See ARCHITECTURE.md for how the codebase is structured and how to add new tools.

<details> <summary>Full tool list</summary>

Guild: discord_list_guilds, discord_get_guild_settings, discord_update_guild_settings, discord_get_guild_preview, discord_get_guild_inventory, discord_get_guild_widget_settings, discord_update_guild_widget_settings, discord_get_guild_vanity_url, discord_get_guild_prune_count, discord_begin_guild_prune, discord_list_guild_integrations, discord_get_guild_welcome_screen, discord_update_guild_welcome_screen, discord_list_guild_templates, discord_create_guild_template, discord_sync_guild_template, discord_update_guild_template, discord_delete_guild_template, discord_list_guild_voice_regions, discord_list_voice_regions

Channels: discord_create_channel, discord_update_channel, discord_delete_channel, discord_list_channel_permission_overwrites, discord_set_channel_permission_overwrite, discord_delete_channel_permission_overwrite, discord_modify_guild_channel_positions

Roles: discord_create_role, discord_update_role, discord_delete_role, discord_get_role_member_counts, discord_modify_guild_role_positions

Members: discord_list_members, discord_search_members, discord_fetch_member, discord_edit_member, discord_set_member_timeout, discord_kick_member, discord_ban_member, discord_bulk_ban_members, discord_unban_member, discord_fetch_guild_ban, discord_list_guild_bans, discord_add_member_role, discord_remove_member_role, discord_set_current_member_voice_state, discord_set_member_voice_state

Messages: discord_list_channel_messages, discord_list_pinned_messages, discord_fetch_message, discord_send_message, discord_edit_message, discord_crosspost_message, discord_pin_message, discord_unpin_message, discord_delete_message, discord_purge_messages, discord_add_reaction, discord_remove_own_reaction, discord_remove_user_reaction, discord_list_reaction_users, discord_clear_reactions, discord_clear_emoji_reactions, discord_end_poll, discord_list_poll_answer_voters

Threads: discord_create_thread, discord_update_thread, discord_join_thread, discord_leave_thread, discord_lock_thread, discord_unlock_thread, discord_remove_thread_member, discord_delete_thread, discord_list_active_threads

Webhooks: discord_list_guild_webhooks, discord_list_channel_webhooks, discord_create_webhook, discord_update_webhook, discord_delete_webhook, discord_execute_webhook_by_token, discord_fetch_webhook_message_by_token, discord_edit_webhook_message_by_token, discord_delete_webhook_message_by_token

Scheduled events: discord_list_scheduled_events, discord_fetch_scheduled_event, discord_create_scheduled_event, discord_update_scheduled_event, discord_delete_scheduled_event, discord_list_scheduled_event_users

Stage: discord_create_stage_instance, discord_fetch_stage_instance, discord_update_stage_instance, discord_delete_stage_instance

Invites: discord_list_guild_invites, discord_create_channel_invite, discord_delete_invite, discord_get_invite_target_users, discord_get_invite_target_user_job_status, discord_update_invite_target_users

AutoMod: discord_list_automod_rules, discord_create_automod_rule, discord_update_automod_rule, discord_delete_automod_rule

Emojis & stickers: discord_list_guild_emojis, discord_create_guild_emoji, discord_update_guild_emoji, discord_delete_guild_emoji, discord_list_guild_stickers, discord_create_guild_sticker, discord_update_guild_sticker, discord_delete_guild_sticker, discord_list_sticker_packs, discord_get_sticker_pack, discord_get_sticker, discord_list_application_emojis, discord_create_application_emoji, discord_update_application_emoji, discord_delete_application_emoji

Soundboard: discord_list_guild_soundboard_sounds, discord_create_guild_soundboard_sound, discord_update_guild_soundboard_sound, discord_delete_guild_soundboard_sound

Audit logs: discord_list_guild_audit_logs

Presence (gateway required): discord_get_presence_state, discord_set_presence

Gateway: discord_get_gateway_info

</details>