Ramsi-K/discord-mcp

Discord MCP Server

⚠️ ALPHA SOFTWARE - This project is in early alpha development. Features may be incomplete or buggy. Use at your own risk.

A Model Context Protocol (MCP) server that provides Discord integration tools for AI assistants like Claude.

Current Version: 0.0.1-alpha1 (Local Development)

Project Status

• 🔬 Phase: Local Development - Testing with MCP Inspector
• 📋 Next: Alpha Release - Publish to PyPI for Claude Desktop testing
• 🎯 Future: Beta & v1.0 - Feature-complete and stable

See for version planning.

Overview

This MCP server enables AI assistants to interact with Discord servers through tools for:

• ✅ Core Operations: List servers, channels, send messages
• ✅ Campaign System: Reaction-based opt-in campaigns with reminders
• 🚧 Future Features: Role management, member analytics, thread support, and more

Development Setup

Prerequisites

1. Python 3.10+ with uv package manager
2. Discord Bot: Create at Discord Developer Portal
3. Node.js (for MCP Inspector)

Installation

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

# Install with uv
uv pip install -e ".[dev]"

Configuration

Create a .env file:

DISCORD_TOKEN=your_discord_bot_token_here
MCP_DISCORD_DB_PATH=discord_mcp.db
LOG_LEVEL=INFO
DRY_RUN=false  # Set to true for testing without Discord API

Testing with MCP Inspector

The MCP Inspector lets you test tools locally before deploying.

1. Start the MCP Inspector

npx @modelcontextprotocol/inspector python -m discord_mcp

This will:

• Start your Discord MCP server
• Launch the MCP Inspector web UI
• Open in your browser (usually http://localhost:5173)

2. Test Available Tools

In the inspector, you can test:

• discord_list_servers - See all servers your bot is in
• discord_list_channels - List channels in a server
• discord_send_message - Send test messages
• discord_create_campaign - Create reaction campaigns
• And more...

3. Alternative: Direct Module Run

# Run server directly (for stdio transport)
python -m discord_mcp

# Run with development script
python dev.py server

# Run with inspector mode
python dev.py inspector

Claude Desktop Configuration (Alpha/Beta Only)

⚠️ Not ready yet - First test locally with inspector, then we'll publish to PyPI

Once published to PyPI, you can configure Claude Desktop:

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

{
  "mcpServers": {
    "discord": {
      "command": "python",
      "args": ["-m", "discord_mcp"],
      "env": {
        "DISCORD_TOKEN": "your_token_here",
        "MCP_DISCORD_DB_PATH": "C:\\path\\to\\discord_mcp.db",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Restart Claude Desktop to load the server.

Available Tools (v0.0.1-alpha)

Core Discord Tools

• discord_list_servers - List all Discord servers
• discord_list_channels - List channels with type filtering
• discord_get_channel_info - Get detailed channel information
• discord_bot_status - Check bot connection status
• discord_get_recent_messages - Retrieve recent messages
• discord_get_message - Get specific message by ID
• discord_send_message - Send messages with reply support

Campaign & Reminder Tools

• discord_create_campaign - Create reaction opt-in campaigns
• discord_tally_optins - Track campaign participants
• discord_list_optins - List opt-ins with pagination
• discord_build_reminder - Build reminder messages
• discord_send_reminder - Send reminders with rate limiting
• discord_run_due_reminders - Process scheduled reminders

See for detailed documentation.

Environment Variables

Development Commands

# Run tests
uv run pytest

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

# Build package
uv build

# Run MCP inspector
npx @modelcontextprotocol/inspector python -m discord_mcp

Project Structure

discord-mcp/
├── src/discord_mcp/          # Main package
│   ├── server.py             # MCP server entry point
│   ├── __main__.py           # Module runner (python -m discord_mcp)
│   ├── config.py             # Configuration
│   ├── discord_client/       # Discord bot implementation
│   ├── database/             # SQLite models & repos
│   ├── tools/                # MCP tool implementations
│   └── server_registry/      # Legacy entity registry
├── tests/                    # Test suite
├── specs/                    # Documentation
│   ├── implemented/          # Current features
│   ├── future/               # Planned features
│   └── ROADMAP.md            # Version roadmap
├── pyproject.toml            # Package configuration
└── README.md                 # This file

Known Issues & Limitations

• ⚠️ Alpha quality - Bugs expected
• ⚠️ Limited features - Only basic tools implemented
• ⚠️ No error recovery - Some edge cases not handled
• ⚠️ Database migrations - Manual schema updates may be needed

See GitHub Issues for known bugs.

Contributing

This is an alpha project - contributions welcome but expect things to change!

1. Test locally with MCP Inspector first
2. Check for planned features
3. Open an issue to discuss changes
4. Submit PR against develop branch

Release Stages

• Now (Local): Testing with MCP Inspector only
• Alpha (0.0.x): Published to PyPI, testing with Claude Desktop
• Beta (0.1.x): Feature-complete, polishing bugs
• Release (1.0.0): Stable, production-ready

License

MIT License - see file.

Support

• 📖 Documentation: directory
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions

Remember: This is alpha software. Always test in a non-production Discord server first!