MCP-Discord

MCP-Discord

A Discord MCP (Model Context Protocol) server that enables AI assistants to interact with the Discord platform.

Overview

MCP-Discord provides the following Discord-related functionalities:

• Login to Discord bot
• List servers the bot is a member of
• Get server information
• List members and inspect member details
• List, create, edit, delete, assign, and remove roles
• Search messages in a server
• Read, edit, and delete channel messages
• Send messages to specified channels
• Retrieve forum channel lists
• Create, update, delete, and reply to forum posts
• List forum threads and manage forum tags
• Create, edit, and delete text, forum, voice channels, and categories
• Set and remove channel permission overrides
• Add/remove message reactions
• Create/edit/delete/use webhooks

Table of Contents

• Prerequisites
• Installation
• Configuration
• Tools Documentation
  • Basic Functions
  • Channel Management
  • Forum Functions
  • Messages and Reactions
  • Webhook Management
  • Role Management
  • Member Management
• Development
• License

Prerequisites

• Node.js (v18.0.0 or higher)

• npm (v7.0.0 or higher)

• A Discord bot with appropriate permissions

  • Bot token (obtainable from the Discord Developer Portal)
  • Message Content Intent enabled
  • Server Members Intent enabled
  • Presence Intent enabled

• Permissions required in your Discord server:

  Easiest Setup

  • Administrator (Recommended for quick setup and full functionality)

  Or, select only the required permissions:

  • Send Messages
  • Create Public Threads
  • Send Messages in Threads
  • Manage Messages
  • Manage Threads
  • Manage Channels
  • Manage Webhooks
  • Manage Roles
  • Add Reactions
  • View Channel

• Add your Discord bot to your server

  • To add your Discord bot to your server, use one of the following invite links (replace INSERT_CLIENT_ID_HERE with your bot's client ID):
    • Administrator (full access): https://discord.com/oauth2/authorize?client_id=INSERT_CLIENT_ID_HERE&scope=bot&permissions=8
    • Custom permissions (minimum required): https://discord.com/oauth2/authorize?client_id=INSERT_CLIENT_ID_HERE&scope=bot&permissions=52076489808

Note:
According to Discord's security model, a bot can only access information from servers it has been explicitly added to.
If you want to use this MCP server to access a specific Discord server, you must add the bot to that server first.
Use the invite link below to add the bot to your target server.

Installation

Installing via NPM

You can use it with the following command:

npx mcp-discord --config ${DISCORD_TOKEN}

For more details, you can check out the NPM Package.

Installing via Smithery

To install mcp-discord automatically via Smithery

Installing via Docker

You can run mcp-discord using Docker. The Docker images are automatically built and published to Docker Hub.

Docker Hub Repository: barryy625/mcp-discord

Docker uses the streamable HTTP server by default via build/app.js.

# Pull the latest image
docker pull barryy625/mcp-discord:latest

# Run HTTP server on port 8080
docker run -e DISCORD_TOKEN=your_discord_bot_token -p 8080:8080 barryy625/mcp-discord:latest

# Override the listening port if needed
docker run -e DISCORD_TOKEN=your_discord_bot_token -p 3000:3000 barryy625/mcp-discord:latest --transport http --port 3000

Available Tags:

• latest - Latest stable version from main branch
• v1.3.8, etc. - Specific version releases

Manual Installation

# Clone the repository
git clone https://github.com/barryyip0625/mcp-discord.git
cd mcp-discord

# Install dependencies
npm install

# Compile TypeScript
npm run build

Configuration

A Discord bot token is required for proper operation. The server supports two transport methods: stdio and streamable HTTP.

Transport Methods

1. stdio (Default)

   • Traditional stdio transport for basic usage
   • Suitable for simple integrations

2. streamable HTTP

   • HTTP-based transport for more advanced scenarios
   • Supports stateless operation
   • Configurable port number

Configuration Options

You can provide configuration in two ways:

1. Environment variables:

DISCORD_TOKEN=your_discord_bot_token

2. Using command line arguments:

# For stdio transport (default)
node build/index.js --config "your_discord_bot_token"

# For streamable HTTP transport
node build/app.js --transport http --port 3000 --config "your_discord_bot_token"

Usage with Claude/Cursor

1. Use Stdio Transport with Claude/Cursor

Use build/index.js when your MCP client expects a command-based stdio server.

Claude Desktop / Claude Code

{
    "mcpServers": {
        "discord": {
            "command": "node",
            "args": [
                "path/to/mcp-discord/build/index.js"
            ],
            "env": {
                "DISCORD_TOKEN": "your_discord_bot_token"
            }
        }
    }
}

Cursor

{
    "mcpServers": {
        "discord": {
            "command": "node",
            "args": [
                "path/to/mcp-discord/build/index.js"
            ],
            "env": {
                "DISCORD_TOKEN": "your_discord_bot_token"
            }
        }
    }
}

This is the recommended setup for local command-based MCP clients.

2. Self-Host the Streamable HTTP Server

Use build/app.js when you want to run mcp-discord as an HTTP MCP server.

Run with Node.js

DISCORD_TOKEN=your_discord_bot_token node build/app.js --transport http --port 3000

On Windows PowerShell:

$env:DISCORD_TOKEN="your_discord_bot_token"
node build/app.js --transport http --port 3000

Run with Docker

docker run -e DISCORD_TOKEN=your_discord_bot_token -p 3000:3000 barryy625/mcp-discord:latest --transport http --port 3000

Once started, the MCP HTTP endpoint is:

http://localhost:3000/mcp

3. Connect to a Hosted HTTP MCP Server

If you already host mcp-discord elsewhere, point your MCP client at the server's /mcp endpoint instead of launching build/app.js as a command.

Example endpoint:

https://your-server.example.com/mcp

Important notes:

• build/app.js starts an HTTP server. It does not speak stdio.
• build/index.js is the correct entrypoint for command-based stdio MCP clients.
• For hosted HTTP usage, configure your MCP client to connect to the HTTP endpoint URL provided by your deployment.
• The exact HTTP-client configuration format depends on the MCP client you use.

Tools Documentation

Basic Functions

• discord_login: Login to Discord using the configured token
• discord_list_servers: List all Discord servers the bot is a member of
• discord_send: Send a message to a specified channel
• discord_get_server_info: Get Discord server information

Channel Management

• discord_create_text_channel: Create a text channel
• discord_create_forum_channel: Create a forum channel
• discord_create_voice_channel: Create a voice channel
• discord_edit_channel: Edit a channel name, topic, parent category, or position
• discord_delete_channel: Delete a channel
• discord_create_category: Create a channel category
• discord_edit_category: Edit a channel category
• discord_delete_category: Delete a channel category
• discord_set_channel_permissions: Set permission overrides for a role or user on a channel/category
• discord_remove_channel_permissions: Remove permission overrides from a channel/category

Forum Functions

• discord_get_forum_channels: Get a list of forum channels
• discord_create_forum_post: Create a forum post (optionally pinned to the top of the channel)
• discord_get_forum_post: Get a forum post
• discord_list_forum_threads: List active and archived threads in a forum channel
• discord_reply_to_forum: Reply to a forum post
• discord_get_forum_tags: Get all available tags for a forum channel
• discord_set_forum_tags: Replace the available tags for a forum channel
• discord_update_forum_post: Update a forum post's title, tags, archived state, locked state, or pinned state
• discord_delete_forum_post: Delete a forum post

Messages and Reactions

• discord_search_messages: Search messages in a server
• discord_read_messages: Read channel messages (supports before, after, around params — accepts snowflake IDs or ISO 8601 dates like "2025-03-01T00:00:00Z")
• discord_edit_message: Edit a bot-authored message
• discord_add_reaction: Add a reaction to a message
• discord_add_multiple_reactions: Add multiple reactions to a message
• discord_remove_reaction: Remove a reaction from a message
• discord_delete_message: Delete a specific message from a channel
• discord_pin_message: Pin a message to its channel (max 50 pins per channel)
• discord_unpin_message: Remove a message from its channel's pinned messages
• discord_list_pinned_messages: List a channel's pinned messages, newest pin first

Webhook Management

• discord_create_webhook: Creates a new webhook for a Discord channel
• discord_send_webhook_message: Sends a message to a Discord channel using a webhook
• discord_edit_webhook: Edits an existing webhook for a Discord channel
• discord_delete_webhook: Deletes an existing webhook for a Discord channel

Role Management

• discord_list_roles: List all roles in a server
• discord_create_role: Create a role with color, hoist, mentionable, and permission options
• discord_edit_role: Edit an existing role
• discord_delete_role: Delete a role
• discord_assign_role: Assign a role to a member
• discord_remove_role: Remove a role from a member

Member Management

• discord_list_members: List members in a server with roles
• discord_get_member: Get detailed information about a specific member

Development

# Development mode
npm run dev

License

MIT License