Shawnsey/Discord-MCP

Discord MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Discord servers. This server provides full bidirectional communication capabilities including reading from channels, sending messages, managing direct messages, and performing moderation actions through a standardized MCP interface.

Features

Resources (Read Operations)

• Guild Listing (guilds://) - List accessible Discord servers with member counts and permissions
• Channel Listing (channels://{guild_id}) - List channels in a specific server with metadata
• Message Reading (messages://{channel_id}) - Read messages from channels with pagination support
• User Information (user://{user_id}) - Get detailed user profile information
• Health Check (health://status) - Server status and configuration information

Tools (Operations)

• List Guilds (list_guilds) - List all accessible Discord servers (read)
• List Channels (list_channels) - List channels in a specific server (read)
• Get Messages (get_messages) - Read recent messages from a channel (read)
• Get User Info (get_user_info) - Get user profile information (read)
• Send Message (send_message) - Send messages to Discord channels with reply support (write)
• Send Direct Message (send_dm) - Send private messages to users (write)
• Read Direct Messages (read_direct_messages) - Read DM conversations with specific users (read)
• Message Management - Delete (delete_message) and edit (edit_message) messages with permissions (write)
• User Moderation - Timeout (timeout_user), remove timeout (untimeout_user), kick (kick_user), and ban (ban_user) users with proper permission validation (moderation)
• Advanced Features - Support for embeds, attachments, reactions, and rich formatting

Quick Start

Prerequisites

• Python 3.8 or higher
• Discord Bot Token (see Discord Bot Setup)
• MCP-compatible client (Amazon Q CLI, Claude Desktop, etc.)

Installation

1. Clone the repository

   git clone <repository-url>
   cd Discord-MCP
   

2. Create virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Configure environment

   cp .env.example .env
   # Edit .env with your Discord bot token and settings
   

5. Run the server

   Option A: Local HTTP Server (SSE Mode)

   # Run as local HTTP server (like prompt-mcp)
   python discord_server.py --transport sse --port 8000
   
   # Or using module
   python -m discord_mcp --transport sse --port 8000
   
   # With custom host and debug logging
   python discord_server.py --transport sse --host 0.0.0.0 --port 8000 --log-level DEBUG
   

   Option B: MCP Client Integration (stdio Mode)

   # For MCP client integration
   python discord_server.py --transport stdio
   
   # Or using module
   python -m discord_mcp --transport stdio
   

Server Modes

The Discord MCP Server supports dual transport modes for maximum flexibility:

SSE Mode (Local HTTP Server)

Run the server as a local HTTP server that you can connect to directly:

# Start local server
python discord_server.py --transport sse --port 8000

# Server will be available at:
# http://localhost:8000/sse
# Health check: http://localhost:8000/health

Benefits of SSE Mode:

• ✅ Runs independently as a local service
• ✅ Can be accessed by multiple clients simultaneously
• ✅ Easier debugging and development
• ✅ Direct HTTP API access
• ✅ Built-in health check endpoint
• ✅ Real-time server monitoring

stdio Mode (MCP Client Integration)

Run the server for integration with MCP clients (Claude Desktop, Amazon Q, etc.):

# For MCP client integration
python discord_server.py --transport stdio

Benefits of stdio Mode:

• ✅ Standard MCP client integration
• ✅ Managed lifecycle by MCP client
• ✅ Automatic process management
• ✅ Secure subprocess communication
• ✅ Built-in error handling and recovery

Command Line Options

python discord_server.py --help

Options:
  --transport {stdio,sse}    Transport protocol (default: stdio)
  --host HOST               Host for SSE mode (default: 127.0.0.1)
  --port PORT               Port for SSE mode (default: 8000)
  --mount-path PATH         Mount path for SSE (default: /sse)
  --log-level LEVEL         Logging level: DEBUG, INFO, WARNING, ERROR (default: INFO)
  --log-format FORMAT       Log format: text or json (default: text)

Examples:
  # Run with stdio transport (for MCP clients)
  python discord_server.py --transport stdio
  
  # Run with SSE transport (local HTTP server)
  python discord_server.py --transport sse --host 0.0.0.0 --port 8000
  
  # Run with debug logging
  python discord_server.py --log-level DEBUG --transport sse

MCP Integration

Development and Testing

Test the server with MCP development tools:

# Test with MCP dev tools
mcp dev mcp_server.py

# Run integration tests
python test_mcp_integration.py

# Test local server functionality
python test_local_server.py

Amazon Q CLI Integration

For Amazon Q CLI integration, add to your MCP configuration:

{
  "mcpServers": {
    "discord-server": {
      "command": "/path/to/Discord-MCP/venv/bin/python",
      "args": ["-m", "discord_mcp.cli", "--transport", "stdio"],
      "env": {
        "DISCORD_BOT_TOKEN": "your_discord_bot_token_here",
        "DISCORD_APPLICATION_ID": "your_discord_application_id_here",
        "LOG_LEVEL": "INFO",
        "PYTHONPATH": "/path/to/Discord-MCP/src"
      }
    }
  }
}

Claude Desktop Integration

For Claude Desktop, add to your configuration file:

{
  "mcpServers": {
    "discord-server": {
      "command": "python",
      "args": ["/path/to/Discord-MCP/discord_server.py", "--transport", "stdio"],
      "env": {
        "DISCORD_BOT_TOKEN": "your_discord_bot_token_here",
        "DISCORD_APPLICATION_ID": "your_discord_application_id_here",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Discord Bot Setup

1. Create Discord Application

• Go to Discord Developer Portal
• Click "New Application" and give it a name
• Note the Application ID (you'll need this)

2. Create Bot User

• Go to the "Bot" section
• Click "Add Bot"
• Copy the Bot Token (keep this secure!)
• Enable necessary Privileged Gateway Intents if needed

3. Configure Bot Permissions

Required permissions for full functionality:

• View Channels - To see channels in servers
• Send Messages - To send messages via MCP tools
• Read Message History - To read messages via MCP resources
• Manage Messages - To delete/edit messages (optional)
• Moderate Members - To timeout and remove timeouts from users (moderation)
• Kick Members - To kick users from servers (moderation)
• Ban Members - To ban users from servers (moderation)
• Use Slash Commands - For future slash command support (optional)

4. Invite Bot to Server

• Go to "OAuth2" > "URL Generator"
• Select "bot" scope
• Select required permissions
• Use generated URL to invite bot to your Discord server

5. Get Bot Invite URL

Replace YOUR_CLIENT_ID with your Discord Application ID:

Basic permissions (read/write operations):

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=3072&scope=bot

Full permissions (including moderation):

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=1099511627776&scope=bot

Configuration

Environment Variables

Security Considerations

• 🔒 Token Security: Never commit your bot token to version control
• 🛡️ Guild Restrictions: Use ALLOWED_GUILDS to restrict server access
• ⚡ Rate Limiting: Configured to respect Discord API limits automatically
• 🔐 Permissions: Bot only accesses channels it has permissions for
• 📝 Audit Logging: All actions are logged for security monitoring
• 👮 Moderation Security: Moderation actions respect Discord's role hierarchy - bot cannot moderate users with higher roles
• 🛡️ Permission Validation: All moderation tools validate required Discord permissions before executing actions
• ⚠️ Moderation Limits: Timeouts are limited to Discord's maximum of 28 days, bans can delete messages up to 7 days old

Role Hierarchy and Moderation Limitations

Discord enforces a strict role hierarchy system that the bot must respect for all moderation actions:

Role Hierarchy Rules

• Bot Role Position: The bot's highest role must be positioned higher than the target user's highest role
• Permission Requirements: The bot must have the specific permission for each moderation action:
  • moderate_members for timeout/untimeout operations
  • kick_members for kick operations
  • ban_members for ban operations
• Owner Immunity: Server owners cannot be moderated by bots regardless of role hierarchy
• Bot Limitations: Bots cannot moderate other bots with equal or higher role positions

Moderation Constraints

• Timeout Duration: 1 minute minimum, 28 days maximum (Discord API limit)
• Ban Message Deletion: 0-7 days of message history can be deleted when banning
• Audit Log Integration: All moderation actions are automatically logged to Discord's audit log
• Error Handling: Clear error messages explain hierarchy violations and permission issues

Best Practices

• Position the bot's role appropriately in your server's role hierarchy
• Grant only necessary permissions to minimize security risks
• Use descriptive reasons for all moderation actions for audit trail clarity
• Test moderation commands in a controlled environment before production use

API Reference

Resources

Tools

Usage Examples

Using Tools (Operations)

# List all accessible Discord servers
guilds = await client.call_tool("list_guilds", {})

# List channels in a specific server
channels = await client.call_tool("list_channels", {
    "guild_id": "123456789012345678"
})

# Get recent messages from a channel
messages = await client.call_tool("get_messages", {
    "channel_id": "123456789012345678"
})

# Get user information
user_info = await client.call_tool("get_user_info", {
    "user_id": "987654321098765432"
})

Reading Messages (Resources)

# Through MCP client - get recent messages from a channel
messages = await client.read_resource("messages://123456789012345678")

# Get user information
user_info = await client.read_resource("user://987654321098765432")

# List servers the bot has access to
guilds = await client.read_resource("guilds://")

Sending Messages

# Send a message to a channel
result = await client.call_tool("send_message", {
    "channel_id": "123456789012345678",
    "content": "Hello from AI assistant! 👋"
})

# Reply to a specific message
result = await client.call_tool("send_message", {
    "channel_id": "123456789012345678",
    "content": "This is a reply!",
    "reply_to_message_id": "111111111111111111"
})

Direct Messages

# Send a direct message
result = await client.call_tool("send_dm", {
    "user_id": "123456789012345678",
    "content": "Private message from AI assistant"
})

# Read DM conversation
conversation = await client.call_tool("read_direct_messages", {
    "user_id": "123456789012345678",
    "limit": 10
})

Message Management

# Delete a message (requires permissions)
result = await client.call_tool("delete_message", {
    "channel_id": "123456789012345678",
    "message_id": "111111111111111111"
})

# Edit a message (bot's own messages only)
result = await client.call_tool("edit_message", {
    "channel_id": "123456789012345678",
    "message_id": "222222222222222222",
    "new_content": "Updated message content"
})

User Moderation

# Timeout a user for 30 minutes
result = await client.call_tool("timeout_user", {
    "guild_id": "123456789012345678",
    "user_id": "987654321098765432",
    "duration_minutes": 30,
    "reason": "Disruptive behavior in chat"
})

# Timeout a user with default duration (10 minutes)
result = await client.call_tool("timeout_user", {
    "guild_id": "123456789012345678",
    "user_id": "987654321098765432",
    "reason": "Spam messages"
})

# Remove timeout from a user
result = await client.call_tool("untimeout_user", {
    "guild_id": "123456789012345678",
    "user_id": "987654321098765432",
    "reason": "Timeout period served"
})

# Kick a user from the server
result = await client.call_tool("kick_user", {
    "guild_id": "123456789012345678",
    "user_id": "987654321098765432",
    "reason": "Violation of server rules"
})

# Ban a user from the server
result = await client.call_tool("ban_user", {
    "guild_id": "123456789012345678",
    "user_id": "987654321098765432",
    "reason": "Repeated rule violations",
    "delete_message_days": 1  # Delete messages from last 1 day
})

# Ban a user without deleting messages
result = await client.call_tool("ban_user", {
    "guild_id": "123456789012345678",
    "user_id": "987654321098765432",
    "reason": "Serious rule violation"
})

Development

Project Structure

Discord-MCP/
├── src/discord_mcp/          # Main package source
│   ├── __init__.py           # Package initialization and exports
│   ├── __main__.py           # Module entry point for `python -m discord_mcp`
│   ├── cli.py                # Command line interface with argument parsing
│   ├── config.py             # Configuration management using Pydantic Settings
│   ├── discord_client.py     # Discord API client wrapper
│   ├── resources.py          # MCP resources (read operations)
│   ├── server.py             # Main MCP server implementation with FastMCP
│   ├── tools.py              # MCP tools (write/action operations)
│   └── services/             # Service layer for business logic
│       ├── __init__.py       # Service exports (DiscordService, ContentFormatter, IDiscordService)
│       ├── interfaces.py     # Abstract service contracts (IDiscordService)
│       ├── discord_service.py # Centralized Discord operations service
│       ├── content_formatter.py # Content formatting and presentation logic
│       └── validation.py     # Validation utilities and mixins
├── tests/                    # Test suite
│   ├── services/             # Service layer tests
│   │   ├── test_discord_service.py    # DiscordService integration tests
│   │   ├── test_content_formatter.py  # ContentFormatter unit tests
│   │   ├── test_interfaces.py         # Interface compliance tests
│   │   └── test_validation.py         # Validation utility tests
│   ├── test_integration.py   # End-to-end integration tests
│   ├── test_tools.py         # MCP tools testing
│   ├── test_resources.py     # MCP resources testing
│   └── test_*.py             # Additional test modules
├── discord_server.py         # Standalone server entry point
├── mcp_server.py            # MCP dev compatible entry point
├── requirements.txt          # Dependencies
├── .env.example             # Environment template
└── README.md                # This file

Service Layer Architecture

The Discord MCP Server implements a clean service layer architecture with proper separation of concerns, eliminating code duplication and providing a maintainable foundation for Discord operations.

Architecture Components

• Business Logic: DiscordService handles Discord API interactions and business rules
• Presentation Logic: ContentFormatter handles all formatting and display concerns
• Validation Logic: ValidationMixin provides centralized validation utilities
• Interface Contracts: IDiscordService defines service operation contracts

Architecture Benefits

• 🔄 Code Reuse: Eliminated 85%+ of duplicated code between tools and resources
• 🧪 Testability: Clean service mocking for comprehensive unit testing
• 🛠️ Maintainability: Single source of truth for Discord operations and formatting
• 🚀 Extensibility: Easy addition of new Discord features through service methods
• 🎨 Separation of Concerns: Clear boundaries between business logic and presentation
• 🔒 Type Safety: Interface contracts ensure proper implementation

Service Layer Components

IDiscordService Interface (src/discord_mcp/services/interfaces.py)

class IDiscordService(ABC):
    """Abstract interface defining Discord operation contracts"""
    
    @abstractmethod
    async def get_guilds_formatted(self) -> str: ...
    
    @abstractmethod
    async def get_channels_formatted(self, guild_id: str) -> str: ...
    
    @abstractmethod
    async def get_messages_formatted(self, channel_id: str, limit: int = 50) -> str: ...
    
    # ... additional methods for user info, messaging, moderation, etc.

DiscordService Implementation (src/discord_mcp/services/discord_service.py)

class DiscordService(IDiscordService):
    """Centralized Discord operations with dependency injection"""
    
    def __init__(
        self,
        discord_client: DiscordClient,
        settings: Settings,
        logger: Logger,
        content_formatter: Optional[ContentFormatter] = None,
    ):
        self._discord_client = discord_client
        self._settings = settings
        self._logger = logger
        self._content_formatter = content_formatter or ContentFormatter(settings)
    
    async def get_guilds_formatted(self) -> str:
        # Business logic: fetch and filter guilds
        guilds = await self._discord_client.get_user_guilds()
        # Presentation logic: delegate to ContentFormatter
        return self._content_formatter.format_guild_info(guilds)

ContentFormatter Implementation (src/discord_mcp/services/content_formatter.py)

class ContentFormatter:
    """Handles all Discord content formatting operations"""
    
    def __init__(self, settings: Optional[Settings] = None):
        self._settings = settings
    
    def format_guild_info(self, guilds: list) -> str:
        """Format guild information into consistent markdown structure"""
        # Centralized formatting logic for guilds
    
    def format_channel_info(self, channels: list, guild_name: str) -> str:
        """Format channel information into consistent markdown structure"""
        # Centralized formatting logic for channels
    
    # ... additional formatting methods for messages, users, timestamps, etc.

Service Integration Pattern

# Tools and resources use the service through dependency injection
async def list_guilds() -> str:
    ctx = server.get_context()
    discord_service: IDiscordService = ctx.request_context.lifespan_context["discord_service"]
    return await discord_service.get_guilds_formatted()

Testing with Service Layer

The service layer enables clean, isolated testing:

# Service unit testing
@pytest.fixture
def mock_discord_service():
    return Mock(spec=IDiscordService)

async def test_list_guilds_tool(mock_discord_service):
    # Test tools in isolation by mocking the service
    mock_discord_service.get_guilds_formatted.return_value = "# Test Guilds\n..."
    # ... test implementation

# ContentFormatter unit testing
@pytest.fixture
def content_formatter():
    return ContentFormatter()

def test_format_guild_info(content_formatter):
    guilds = [{"id": "123", "name": "Test Guild"}]
    result = content_formatter.format_guild_info(guilds)
    assert "Test Guild" in result

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src/discord_mcp

# Run integration tests
python test_mcp_integration.py

# Test local server functionality
python test_local_server.py

Code Quality

# Format code
black src/ tests/
isort src/ tests/

# Type checking
mypy src/

# Linting
flake8 src/ tests/

Adding New Features

With the service layer architecture, adding new Discord features is streamlined:

1. Service Methods: Add new methods to IDiscordService interface and implement in DiscordService

   # Add to interfaces.py
   @abstractmethod
   async def new_discord_feature(self, param: str) -> str: ...
   
   # Implement in discord_service.py
   async def new_discord_feature(self, param: str) -> str:
       # Centralized implementation with error handling
   

2. Tools: Add to src/discord_mcp/tools.py using the service

   async def new_tool() -> str:
       ctx = server.get_context()
       discord_service = ctx.request_context.lifespan_context["discord_service"]
       return await discord_service.new_discord_feature(param)
   

3. Resources: Add to src/discord_mcp/resources.py using the service

4. Configuration: Update src/discord_mcp/config.py if needed

5. Tests: Add service unit tests and integration tests in tests/

Service Development Benefits

• Single Implementation: Write Discord logic once in the service
• Consistent Error Handling: Automatic error management and logging
• Easy Testing: Mock the service interface for isolated testing
• Type Safety: Interface contracts ensure proper implementation
• Moderation Support: Centralized permission validation and role hierarchy checking for all moderation operations

Service Layer Development Benefits

• Single Implementation: Write Discord logic once in the service
• Consistent Error Handling: Automatic error management and logging
• Easy Testing: Mock the service interface for isolated testing
• Type Safety: Interface contracts ensure proper implementation
• Centralized Formatting: ContentFormatter provides consistent output formatting
• Moderation Support: Centralized permission validation and role hierarchy checking for all moderation operations

Troubleshooting

Common Issues

1. Bot Token Issues

Symptoms: Authentication errors, "Invalid Bot Token" Solutions:

• Verify token format (should be ~70 characters)
• Check token in Discord Developer Portal
• Ensure token starts with correct prefix
• Regenerate token if compromised

2. Permission Issues

Symptoms: "Missing Permissions", "Forbidden" errors Solutions:

• Check bot permissions in Discord server settings
• Verify bot has required permissions for the action
• Re-invite bot with correct permissions
• Check channel-specific permission overrides

5. Moderation Issues

Symptoms: "Role hierarchy violation", "Cannot moderate this user" Solutions:

• Ensure bot's role is positioned higher than target user's highest role
• Verify bot has required moderation permissions (moderate_members, kick_members, ban_members)
• Check that target user is not the server owner
• Confirm timeout duration is within 1 minute to 28 days range
• Verify ban message deletion days is within 0-7 range

3. MCP Integration Issues

Symptoms: "Still loading", connection timeouts Solutions:

• Verify environment variables are set correctly
• Check MCP configuration file syntax
• Test server startup manually
• Review logs for specific error messages

4. Rate Limiting

Symptoms: Slow responses, "Rate Limited" errors Solutions:

• Reduce request frequency
• Adjust RATE_LIMIT_REQUESTS_PER_SECOND setting
• Implement request batching
• Monitor Discord API rate limits

Debug Mode

Enable comprehensive debugging:

# Set debug environment
export LOG_LEVEL=DEBUG
export LOG_FORMAT=json

# Run with debug output
python discord_server.py --transport sse --log-level DEBUG 2>&1 | tee debug.log

Health Monitoring

Check server health:

# For SSE mode
curl http://localhost:8000/health

# Check MCP resources
python -c "
import asyncio
from mcp.client.session import ClientSession
# ... health check code
"

Performance

Benchmarks

• Message Reading: ~100ms average response time
• Message Sending: ~200ms average response time
• Rate Limiting: 5 requests/second (configurable)
• Memory Usage: ~50MB baseline
• Concurrent Connections: Supports multiple MCP clients

Optimization Tips

• Use pagination for large message sets
• Implement caching for frequently accessed data
• Monitor rate limits to avoid API blocks
• Use appropriate log levels in production

Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with proper documentation
4. Add tests for new functionality
5. Run the test suite (pytest tests/)
6. Check code quality (black, isort, mypy)
7. Submit a pull request

Development Setup

# Clone your fork
git clone https://github.com/your-username/Discord-MCP.git
cd Discord-MCP

# Set up development environment
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt  # If available

# Run tests
pytest tests/

License

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

Support & Resources

• 📚 Documentation: MCP Specification
• 🔧 Discord API: Discord Developer Documentation
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Examples: See for detailed usage examples
• 🔍 Troubleshooting: See for common issues

Changelog

v0.4.0 (Latest)

• ✅ ContentFormatter Extraction: Completed major refactoring to separate formatting logic from business logic
• ✅ Code Duplication Elimination: Reduced duplicate code by 85%+ through centralized formatting
• ✅ Enhanced Architecture: Implemented clean separation of concerns between DiscordService and ContentFormatter
• ✅ Improved Testability: Added comprehensive unit tests for ContentFormatter with 95%+ coverage
• ✅ Backward Compatibility: Maintained 100% API compatibility during refactoring
• ✅ Error Handling: Added robust error handling for malformed data and edge cases
• ✅ Documentation Updates: Updated project structure and architecture documentation

v0.3.0

• ✅ Added comprehensive user moderation tools (timeout_user, untimeout_user, kick_user, ban_user)
• ✅ Implemented role hierarchy validation for all moderation actions
• ✅ Added permission validation for moderation operations
• ✅ Enhanced service layer architecture for better code organization
• ✅ Added comprehensive moderation documentation and examples
• ✅ Integrated audit logging for all moderation actions

v0.2.0

• ✅ Added read_direct_messages tool for bidirectional DM support
• ✅ Implemented dual transport support (stdio + SSE)
• ✅ Added comprehensive command line interface
• ✅ Enhanced error handling and logging
• ✅ Added health check endpoint
• ✅ Improved documentation and examples
• ✅ Added comprehensive test suite

v0.1.0 (Initial Release)

• ✅ Basic MCP server implementation
• ✅ Discord API integration
• ✅ Channel and message operations
• ✅ Direct message support
• ✅ Amazon Q CLI integration

Built with ❤️ for the Discord community