Discord MCP Server

Discord MCP Server

A streamlined Model Context Protocol server for Discord with smart target resolution. No more hallucinated IDs!

Features

• 🎯 Smart Target Resolution: Use channel names, usernames, or IDs - no need to memorize snowflakes
• 🧠 LLM-Friendly: Reduces hallucination by accepting human-readable names
• 💬 Automatic Mention Processing: Converts @username to proper Discord <@id> format automatically
• 📦 Streamlined API: Only 7 essential tools, no redundancy
• 💾 Smart Caching: Automatically caches name→ID mappings
• 🔀 Ambiguity Handling: Detects when channel names collide and guides to use ServerName/channel format

Tools

1. send_message - Send to channels or DMs (accepts names or IDs)
2. edit_message - Edit or delete messages (empty content = delete)
3. read_messages - Read channel history + channel info
4. list_servers - List all accessible servers
5. list_channels - List channels in a server
6. search_messages - Search for messages in a channel
7. add_reaction - React to messages with emoji

Setup

1. Create a Discord Bot

1. Go to Discord Developer Portal
2. Click "New Application" and give it a name
3. Go to "Bot" section and click "Add Bot"
4. Enable these Privileged Gateway Intents:
   • Message Content Intent
   • Server Members Intent
   • Presence Intent (optional)
5. Click "Reset Token" and copy your bot token
6. Go to "OAuth2" → "URL Generator"
   • Select scopes: bot
   • Select permissions: Send Messages, Read Message History, Add Reactions, Manage Messages
7. Use the generated URL to invite the bot to your server

2. Install Dependencies

pip install -r requirements.txt

3. Set Environment Variable

export DISCORD_TOKEN="your_bot_token_here"

Or on Windows:

set DISCORD_TOKEN=your_bot_token_here

4. Run the Server

python path/to/discord-mcp

Usage Examples

With Claude Desktop (config)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "discord": {
      "command": "python",
      "args": ["/path/to/discord-mcp"],
      "env": {
        "DISCORD_TOKEN": "your_bot_token_here"
      }
    }
  }
}

Example Prompts for Claude

Send a message:

Send "Hello everyone!" to the general channel
Send "Meeting in 5 mins" to Work Server/announcements

Read messages:

Read the last 20 messages from announcements
Read messages from Gaming Server/general

Search:

Search for messages containing "meeting" in the team-chat channel
Search for "bug report" in Dev Team/bugs

Edit/Delete:

Edit message 123456789 to say "Updated: Meeting at 3pm"
Delete message 987654321

Smart Target Resolution

The server automatically handles both names and IDs:

Handling Ambiguous Channel Names

Since most Discord servers have channels with common names like "general" or "announcements", the server handles ambiguity intelligently:

If a channel name is unique: Just use the name

Send "Hello!" to announcements

If a channel name appears in multiple servers: The server will tell you which servers have that channel and ask you to specify:

Error: Multiple channels named 'general' found:
  • My Gaming Server → #general
  • Work Team → #general
  • Friend Group → #general

Please specify format: 'ServerName/channel' or use channel ID

Use the ServerName/channel format:

Send "Hello team!" to Work Team/general
Read the last 10 messages from My Gaming Server/general

This completely eliminates the need for the AI to remember or hallucinate long channel IDs!

Automatic User Mention Processing

Discord bots can only mention users using the <@user_id> format, but LLMs naturally want to use @username. The server automatically handles bidirectional conversion:

When SENDING messages (AI → Discord):

AI writes: "Hey @john, can you check this?"
Discord receives: "Hey <@789012345678901234>, can you check this?"

When READING messages (Discord → AI):

Discord has: "Meeting with <@789012345678901234> at 3pm"
AI sees: "Meeting with @john at 3pm"

Sending - Handles:

• @username → Looks up user and converts to <@id>
• @123456789 → Recognizes as ID and formats to <@123456789>
• 123456789 → Detects raw IDs and converts to <@123456789> if valid user
• Non-existent users → Left as