📖 Description

A Model Context Protocol (MCP) server for the Discord API (JDA),
allowing seamless integration of Discord Bot with MCP-compatible applications like Claude Desktop.

Enable your AI assistants to seamlessly interact with Discord. Manage channels, send messages, and retrieve server information effortlessly. Enhance your Discord experience with powerful automation capabilities.

🔬 Installation

► 🐳 Docker Installation (Recommended)

[!NOTE]
Docker installation is required. Full instructions can be found on docker.com.

1) Create local runtime env

cat > .env <<EOF
SPRING_PROFILES_ACTIVE=http
DISCORD_TOKEN=<YOUR_DISCORD_BOT_TOKEN>
DISCORD_GUILD_ID=<OPTIONAL_DEFAULT_SERVER_ID>
EOF

2) Start one shared MCP server container

docker compose up -d --build

3) Verify

docker ps --filter name=discord-mcp
curl -fsS http://localhost:8085/actuator/health

Default MCP endpoint URL (HTTP profile): http://localhost:8085/mcp

Health endpoint (Actuator): http://localhost:8085/actuator/health

🔧 Manual Installation

Clone the repository

git clone https://github.com/SaseQ/discord-mcp

Build the project

[!NOTE]
Maven installation is required to use the mvn command. Full instructions can be found here.

cd discord-mcp
mvn clean package # The jar file will be available in the /target directory

Configure AI client

Run the JAR as a long-running server:

DISCORD_TOKEN=<YOUR_DISCORD_BOT_TOKEN> \
DISCORD_GUILD_ID=<OPTIONAL_DEFAULT_SERVER_ID> \
SPRING_PROFILES_ACTIVE=http \
java -jar /absolute/path/to/discord-mcp-1.0.0.jar

Then configure your MCP client to connect over HTTP to:

http://localhost:8085/mcp

[!NOTE]
The DISCORD_GUILD_ID environment variable is optional. When provided, it sets a default Discord server ID so any tool that accepts a guildId parameter can omit it.

🔗 Connections

► 🗞️ Default config.json Connection

Recommended (HTTP singleton mode):

{
  "mcpServers": {
    "discord-mcp": {
      "url": "http://localhost:8085/mcp"
    }
  }
}

Legacy mode (stdio, starts a new process/container per client session):

{
  "mcpServers": {
    "discord-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DISCORD_TOKEN=<YOUR_DISCORD_BOT_TOKEN>",
        "-e",
        "DISCORD_GUILD_ID=<OPTIONAL_DEFAULT_SERVER_ID>",
        "saseq/discord-mcp:latest"
      ]
    }
  }
}

⌨️ Claude Code Connection

Recommended (HTTP singleton mode):

claude mcp add discord-mcp --transport http http://localhost:8085/mcp

Legacy mode (stdio, starts a new process/container per client session):

claude mcp add discord-mcp -- docker run --rm -i -e DISCORD_TOKEN=<YOUR_DISCORD_BOT_TOKEN> -e DISCORD_GUILD_ID=<OPTIONAL_DEFAULT_SERVER_ID> saseq/discord-mcp:latest

🤖 Codex CLI Connection

codex mcp add discord-mcp --url http://localhost:8085/mcp
codex mcp list

🦞 OpenClaw Connection

Run this command:

openclaw mcp set discord-mcp '{"url":"http://localhost:8085/mcp","transport":"streamable-http"}'
openclaw mcp list

Pasting the following configuration into your OpenClaw ~/.openclaw/config.json file:

{
  "mcp": {
    "servers": {
      "discord-mcp": {
        "url": "http://localhost:8085/mcp",
        "transport": "streamable-http"
      }
    }
  }
}

🖲 Cursor Connection

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.

{
  "mcpServers": {
    "discord-mcp": {
      "url": "http://localhost:8085/mcp"
    }
  }
}

🖥 Claude Desktop Connection

STDIO local config (Default, legacy):

[!NOTE]
Past the following configuration into your Claude Desktop claude_desktop_config.json file.

{
  "mcpServers": {
    "discord-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DISCORD_TOKEN=<YOUR_DISCORD_BOT_TOKEN>",
        "-e",
        "DISCORD_GUILD_ID=<OPTIONAL_DEFAULT_SERVER_ID>",
        "saseq/discord-mcp:latest"
      ]
    }
  }
}

Remote MCP Connector:

Open Claude Desktop and go to Settings -> Connectors.
Add a custom connector and set MCP URL to your server endpoint (for example https://<PUBLIC_HOST>/mcp).
Save and reconnect.

[!NOTE]
Claude Desktop remote connectors are managed via Connectors UI (not claude_desktop_config.json).

[!NOTE]
http://localhost:8085/mcp is reachable only from your machine. For Claude Desktop remote connectors, expose the endpoint with public HTTPS (for example tunnel/reverse proxy).

🛠️ Available Tools

Server Information

get_server_info: Get detailed discord server information

User Management

get_user_id_by_name: Get a Discord user's ID by username in a guild for ping usage <@id>
send_private_message: Send a private message to a specific user
edit_private_message: Edit a private message from a specific user
delete_private_message: Delete a private message from a specific user
read_private_messages: Read recent message history from a specific user

Message Management

send_message: Send a message to a specific channel
edit_message: Edit a message from a specific channel
delete_message: Delete a message from a specific channel
read_messages: Read recent message history from a specific channel
add_reaction: Add a reaction (emoji) to a specific message
remove_reaction: Remove a specified reaction (emoji) from a message

Channel Management

create_text_channel: Create a new text channel
edit_text_channel: Edit settings of a text channel (name, topic, nsfw, slowmode, category, position)
delete_channel: Delete a channel
find_channel: Find a channel type and ID using name and server ID
list_channels: List of all channels
get_channel_info: Get detailed information about a channel
move_channel: Move a channel to another category and/or change its position

Category Management

create_category: Create a new category for channels
delete_category: Delete a category
find_category: Find a category ID using name and server ID
list_channels_in_category: List of channels in a specific category

Webhook Management

create_webhook: Create a new webhook on a specific channel
delete_webhook: Delete a webhook
list_webhooks: List of webhooks on a specific channel
send_webhook_message: Send a message via webhook

Role Management

list_roles: Get a list of all roles on the server with their details
create_role: Create a new role on the server
edit_role: Modify an existing role's settings
delete_role: Permanently delete a role from the server
assign_role: Assign a role to a user
remove_role: Remove a role from a user

Moderation and User Management

kick_member: Kicks a member from the server
ban_member: Bans a user from the server
unban_member: Removes a ban from a user
timeout_member: Disables communication for a member for a specified duration
remove_timeout: Removes a timeout (unmute) from a member before it expires
set_nickname: Changes a member's nickname on the server
get_bans: Returns a list of banned users on the server with ban reasons

Voice & Stage Channel Management

create_voice_channel: Create a new voice channel in a guild
create_stage_channel: Create a new stage channel for audio events
edit_voice_channel: Edit settings of a voice or stage channel (name, bitrate, user limit, region)
move_member: Move a member to another voice channel
disconnect_member: Disconnect a member from their current voice channel
modify_voice_state: Server mute or deafen a member in voice channels

Scheduled Events Management

create_guild_scheduled_event: Schedule a new event on the server (voice, stage, or external)
edit_guild_scheduled_event: Modify event details or change its status (start, complete, cancel)
delete_guild_scheduled_event: Permanently delete a scheduled event
list_guild_scheduled_events: List all active and scheduled events on the server
get_guild_scheduled_event_users: Get list of users interested in a scheduled event

Channel Permission Overwrites

list_channel_permission_overwrites: List all permission overwrites for a channel with role/member breakdown
upsert_role_channel_permissions: Create or update permission overwrite for a role on a channel
upsert_member_channel_permissions: Create or update permission overwrite for a member on a channel
delete_channel_permission_overwrite: Delete a permission overwrite for a role or member from a channel

Invite Management

create_invite: Create a new invite link for a specific channel
list_invites: List all active invites on the server with their statistics
delete_invite: Delete (revoke) an invite so the link stops working
get_invite_details: Get details about a specific invite (works for any public invite)

Emoji Management

list_emojis: List all custom emojis on the server
get_emoji_details: Get detailed information about a specific custom emoji
create_emoji: Upload a new custom emoji to the server (base64 or image URL, max 256KB)
edit_emoji: Edit an existing emoji's name or role restrictions
delete_emoji: Permanently delete a custom emoji from the server

If DISCORD_GUILD_ID is set, the guildId parameter becomes optional for all tools above.

A more detailed examples can be found in the Wiki.