fukayatti/discord-mcp-server

Discord MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Discord integration capabilities. This server enables MCP clients like Claude Desktop to interact with Discord servers through a rich set of tools for message management, server administration, and user interaction.

🚀 Features

📊 Server Management

• Get detailed server information and statistics
• List server members with roles and permissions
• Access server configuration and metadata

💬 Message Operations

• Send Messages: Post messages to any accessible channel
• Read Messages: Retrieve message history with reactions and pagination support
• Bulk Message Reading: Automatically fetch large amounts of messages with unlimited support
• Message Pagination: Navigate through message history using before/after/around parameters
• Message Moderation: Delete inappropriate content and manage users
• Reaction Management: Add, remove, and manage message reactions

🗂️ Channel Management

• Create Channels: Set up new text channels with categories and topics
• Delete Channels: Remove unwanted channels safely
• Category Operations: List and manage channels within categories
• Bulk Channel Reading: Read messages from all channels in a category

👥 User & Role Management

• Role Assignment: Add and remove roles from users
• User Information: Get detailed user profiles and statistics
• Member Management: List and manage server members

🛡️ Moderation Tools

• Message Deletion: Remove inappropriate content with audit trails
• User Timeouts: Temporarily restrict user participation
• Audit Logging: Track moderation actions with detailed reasons

📋 Prerequisites

• Node.js 18.0.0 or higher
• Discord Bot Token with appropriate permissions
• MCP-compatible client (e.g., Claude Desktop)

🔧 Installation

Install via npm (Recommended)

You can install the server directly from npm:

npm install -g @fukayatti0/discord-mcp-server

Or use it with pnpx (no global install required):

pnpx @fukayatti0/discord-mcp-server

Manual Installation

1. Clone the repository:

git clone https://github.com/fukayatti/discord-mcp-server.git
cd discord-mcp-server

2. Install dependencies:

npm install
# or
pnpm install

3. Set up your Discord bot:

• Visit the Discord Developer Portal
• Create a new application and bot
• Copy the bot token
• Enable required privileged intents:
  • MESSAGE CONTENT INTENT
  • PRESENCE INTENT
  • SERVER MEMBERS INTENT
• Generate an invite URL and add the bot to your server

⚙️ Configuration

Claude Desktop Setup

Edit your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Using pnpx (Recommended)

If you installed via npm or want to use without global install, configure as follows:

{
  "mcpServers": {
    "discord": {
      "command": "pnpx",
      "args": ["@fukayatti0/discord-mcp-server"],
      "env": {
        "DISCORD_TOKEN": "your_discord_token_here"
      }
    }
  }
}

Using local source

{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["/path/to/discord-mcp-server/src/server.js"],
      "env": {
        "DISCORD_TOKEN": "your_bot_token_here"
      }
    }
  }
}

For global installation

{
  "mcpServers": {
    "discord": {
      "command": "discord-mcp-server",
      "env": {
        "DISCORD_TOKEN": "your_bot_token_here"
      }
    }
  }
}

🎯 Usage Examples

Basic Message Operations

"Send a welcome message to the #general channel"
"Read the last 20 messages from #announcements"
"Read all messages from #general channel (unlimited)"
"Get messages before message ID 1234567890 for pagination"
"Fetch 500 messages from #discussion using bulk reading"
"Add a 👍 reaction to message ID 1234567890"

Server Management

"Get information about this Discord server"
"List all members in the server with their roles"
"Show me all channels in the 'Gaming' category"

Channel Management

"Create a new channel called 'project-discussion' in the Development category"
"Delete the #old-channel with reason 'No longer needed'"
"Read messages from all channels in the Support category"

User & Role Management

"Add the 'Moderator' role to user ID 987654321"
"Remove the 'Member' role from user ID 123456789"
"Get detailed information about user ID 555666777"

Moderation

"Delete message ID 1111222233 for spam and timeout the user for 10 minutes"
"Moderate message ID 4444555566 with reason 'Inappropriate content'"

🛠️ Available Tools

📖 Advanced Message Reading Features

Pagination Support

The read_messages tool now supports pagination parameters:

• before: Get messages sent before a specific message ID
• after: Get messages sent after a specific message ID
• around: Get messages around a specific message ID

Unlimited Message Reading

The read_messages_bulk tool enables reading large amounts of messages:

• total_limit: Specify the total number of messages to fetch (automatically paginated)
• unlimited: true: Fetch all available messages in a channel/thread
• total_limit: -1: Alternative way to enable unlimited reading

Thread Support

All message reading tools now support Discord threads:

• Use thread ID as the channel parameter
• Read messages from both regular channels and threads seamlessly

No Artificial Limits

All previous artificial limits have been removed:

• read_messages: No longer limited to 100 messages per request
• read_category_channels: No longer limited to 50 messages per channel
• Only Discord API's internal limits apply (100 messages per API call, automatically handled)

🔒 Required Bot Permissions

Ensure your Discord bot has these permissions:

• Send Messages
• Read Message History
• Add Reactions
• Manage Messages (for moderation)
• Manage Channels (for channel management)
• Manage Roles (for role management)
• Moderate Members (for timeouts)
• View Channels

🚀 Development

Running Locally

# Install dependencies
npm install

# Start the server
npm start

# Development mode with auto-reload
npm run dev

Environment Variables

• DISCORD_TOKEN - Your Discord bot token (required)

Project Structure

discord-mcp-server/
├── src/
│   └── server.js       # Main MCP server implementation
├── package.json        # Project configuration
├── README.md           # Documentation
└── .gitignore          # Git ignore rules

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 License

This project is licensed under the MIT License. See the file for details.

🐛 Troubleshooting

Common Issues

Bot not responding:

• Verify the DISCORD_TOKEN is correct
• Check that the bot has necessary permissions
• Ensure privileged intents are enabled in Discord Developer Portal

Channel/Server not found:

• Use channel/server IDs instead of names for precision
• Ensure the bot has access to the specified channels
• Check that the bot is a member of the target server

Permission errors:

• Review bot permissions in Discord server settings
• Ensure the bot's role is positioned correctly in the role hierarchy
• Verify specific permissions for channels and categories

🔗 Links

• Repository: https://github.com/fukayatti/discord-mcp-server
• npm package: @fukayatti0/discord-mcp-server
• Author: fukayatti
• MCP Documentation: Model Context Protocol
• Discord.js: https://discord.js.org/

Made with ❤️ by fukayatti