## 📖 Description
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server for the Discord API [(JDA)](https://jda.wiki/),
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](https://www.docker.com/products/docker-desktop/).
#### 1) Create local runtime env
```bash
cat > .env <
DISCORD_GUILD_ID=
EOF
```
#### 2) Start one shared MCP server container
```bash
docker compose up -d --build
```
#### 3) Verify
```bash
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
```bash
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](https://www.baeldung.com/install-maven-on-windows-linux-mac).
```bash
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:
```bash
DISCORD_TOKEN= \
DISCORD_GUILD_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):
```json
{
"mcpServers": {
"discord-mcp": {
"url": "http://localhost:8085/mcp"
}
}
}
```
Legacy mode (stdio, starts a new process/container per client session):
```json
{
"mcpServers": {
"discord-mcp": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"DISCORD_TOKEN=",
"-e",
"DISCORD_GUILD_ID=",
"saseq/discord-mcp:latest"
]
}
}
}
```
⌨️ Claude Code Connection
Recommended (HTTP singleton mode):
```bash
claude mcp add discord-mcp --transport http http://localhost:8085/mcp
```
Legacy mode (stdio, starts a new process/container per client session):
```bash
claude mcp add discord-mcp -- docker run --rm -i -e DISCORD_TOKEN= -e DISCORD_GUILD_ID= saseq/discord-mcp:latest
```
🤖 Codex CLI Connection
```bash
codex mcp add discord-mcp --url http://localhost:8085/mcp
codex mcp list
```
🦞 OpenClaw Connection
Run this command:
```bash
openclaw mcp set discord-mcp '{"url":"http://localhost:8085/mcp","transport":"streamable-http"}'
openclaw mcp list
```
OR
Pasting the following configuration into your OpenClaw `~/.openclaw/config.json` file:
```json
{
"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](https://docs.cursor.com/context/model-context-protocol) for more info.
```json
{
"mcpServers": {
"discord-mcp": {
"url": "http://localhost:8085/mcp"
}
}
}
```
🖥 Claude Desktop Connection
STDIO local config (Default, legacy):
> Past the following configuration into your Claude Desktop `claude_desktop_config.json` file.
```json
{
"mcpServers": {
"discord-mcp": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"DISCORD_TOKEN=",
"-e",
"DISCORD_GUILD_ID=",
"saseq/discord-mcp:latest"
]
}
}
}
```
Remote MCP Connector:
1. Open Claude Desktop and go to `Settings` -> `Connectors`.
2. Add a custom connector and set MCP URL to your server endpoint (for example `https:///mcp`).
3. Save and reconnect.
> Claude Desktop remote connectors are managed via Connectors UI (not `claude_desktop_config.json`).
> `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](https://github.com/SaseQ/discord-mcp/wiki).
