📋 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 📦 Installation
• ⚙️ Configuration
• 🔧 Setup Guide
• 🛠️ Available Tools
• 🔐 Authentication
• 📊 Monitoring
• 🧪 Testing
• 📚 API Reference
• 🛡️ Security
• 🤝 Contributing
• 📄 License

✨ Features

🎯 Core Capabilities

• 🔗 Discord Integration: Full Discord API support with 5 powerful tools
• 🔐 Enterprise Security: Multi-tenant authentication with API key management
• ⚡ Rate Limiting: Configurable rate limits (30/min, 500/hour, 5000/day)
• 📊 Real-time Monitoring: Built-in MCP Inspector dashboard
• 🔍 Comprehensive Logging: Audit trails and security event tracking
• 🧪 Testing Ready: Jest framework with 80%+ coverage threshold

🛠️ Discord Tools

🏗️ Architecture Highlights

• 🔄 MCP Protocol: Full Model Context Protocol compliance
• 🏢 Multi-tenancy: Isolated client management per API key
• 🛡️ Security First: Token hashing, no persistent storage
• 📈 Scalable: Automatic client cleanup and resource management

# Clone the repository
git clone https://github.com/lokeshpanthangi/Discord-MCP.git
cd Discord-MCP

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Start the server
npm start

# Open MCP Inspector (optional)
# Visit http://localhost:3001

📦 Installation

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0
• Discord Bot Token (Create one here)
• Discord Server with bot permissions

Step-by-Step Installation

1. Clone the Repository

   git clone https://github.com/lokeshpanthangi/Discord-MCP.git
   cd Discord-MCP
   

2. Install Dependencies

   npm install
   

3. Environment Setup

   cp .env.example .env
   

4. Configure Environment Variables (see Configuration)

5. Start the Server

   npm start
   

⚙️ Configuration

Environment Variables

Create a .env file in the root directory:

# Required: Discord Bot Configuration
DISCORD_BOT_TOKEN=your_discord_bot_token_here

# Required: MCP Server Authentication
MCP_API_KEY=your_secure_api_key_here

# Optional: Server Configuration
MCP_SERVER_NAME=discord-mcp-server
NODE_ENV=production

# Optional: Monitoring
MCP_INSPECTOR_PORT=3001

# Optional: Logging
LOG_LEVEL=info

Discord Bot Setup

1. Create Discord Application

   • Visit Discord Developer Portal
   • Click "New Application" and give it a name
   • Navigate to "Bot" section
   • Click "Add Bot"

2. Configure Bot Permissions

   ✅ Send Messages
   ✅ Read Message History
   ✅ View Channels
   ✅ Manage Messages (for moderation)
   ✅ Read Messages/View Channels
   

3. Get Bot Token

   • In Bot section, click "Copy" under Token
   • Add to your .env file as DISCORD_BOT_TOKEN

4. Invite Bot to Server

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

🔧 Setup Guide

For Claude Desktop Integration

1. Configure Claude Desktop

   Add to your claude_desktop_config.json:

   {
     "mcpServers": {
       "discord-mcp": {
         "command": "node",
         "args": ["server.js"],
         "cwd": "/path/to/Discord-MCP",
         "env": {
           "MCP_INSPECTOR_PORT": "3001"
         }
       }
     }
   }
   

2. Restart Claude Desktop

3. Verify Connection

   • Open Claude Desktop
   • Look for Discord tools in the interface
   • Test with a simple command

For Development

1. Install Development Dependencies

   npm install
   

2. Run in Development Mode

   npm run dev
   

3. Run Tests

   npm test
   npm run test:coverage
   

4. Code Quality

   npm run lint
   npm run format
   npm run validate
   

1. 📋 get_channel_info

Purpose: Retrieve comprehensive information about Discord channels

// Usage Example
{
  "channelId": "1234567890123456789"
}

// Response
{
  "id": "1234567890123456789",
  "name": "general",
  "type": "Text",
  "topic": "Welcome to our server!",
  "memberCount": 150,
  "createdAt": "2023-01-01T00:00:00.000Z"
}

2. 📨 get_messages

Purpose: Fetch messages from channels with filtering options

// Usage Example
{
  "channelId": "1234567890123456789",
  "limit": 10,
  "before": "1234567890123456789"
}

// Response
{
  "messages": [
    {
      "id": "1234567890123456789",
      "content": "Hello world!",
      "author": "username#1234",
      "timestamp": "2023-01-01T00:00:00.000Z"
    }
  ]
}

3. 🔍 search_messages

Purpose: Advanced message search with multiple filters

// Usage Example
{
  "channelId": "1234567890123456789",
  "query": "important announcement",
  "authorId": "9876543210987654321",
  "limit": 5
}

4. 📤 send_message

Purpose: Send messages to channels (supports both ID and name)

// By Channel ID
{
  "channelId": "1234567890123456789",
  "content": "Hello from MCP!"
}

// By Channel Name
{
  "channelName": "general",
  "content": "Hello from MCP!"
}

5. 🛡️ moderate_content

Purpose: Delete messages and moderate content

// Usage Example
{
  "channelId": "1234567890123456789",
  "messageId": "1234567890123456789",
  "reason": "Inappropriate content"
}

🔐 Authentication

API Key Management

• Environment-based: Store API keys in .env file
• Multi-tenant: Each API key gets isolated Discord client
• Secure: Keys are hashed for client identification
• No Persistence: Tokens never stored permanently

Security Features

• ✅ Token Hashing: Bot tokens hashed for security
• ✅ Client Isolation: Separate Discord clients per tenant
• ✅ Automatic Cleanup: Unused clients cleaned up
• ✅ Audit Logging: All authentication attempts logged
• ✅ Rate Limiting: Configurable request limits

📊 Monitoring

MCP Inspector Dashboard

Access real-time monitoring at http://localhost:3001

Features:

• 📊 Real-time Metrics: Request counts, response times
• 🔍 Request Logging: Detailed request/response inspection
• 📈 Performance Monitoring: Tool execution statistics
• 🚨 Error Tracking: Failed requests and error analysis
• 👥 Multi-tenant View: Per-client usage statistics

Logging System

logs/
├── audit.log      # Authentication and authorization events
├── error.log      # Application errors and exceptions
└── security.log   # Security-related events and violations

🧪 Testing

Test Coverage

• Target: 80%+ code coverage
• Framework: Jest with comprehensive test suites
• Types: Unit tests, integration tests, security tests

Running Tests

# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

# Integration tests
npm run test:integration

# Multi-tenancy tests
npm run test:multi

Test Structure

__tests__/
├── tools/
│   ├── get_channel_info.test.js
│   ├── get_messages.test.js
│   ├── search_messages.test.js
│   ├── send_message.test.js
│   └── moderate_content.test.js
├── middleware/
│   └── auth.test.js
└── utils/
    ├── rate-limiter.test.js
    └── audit-logger.test.js

📚 API Reference

Server Configuration

Rate Limiting

Error Codes

🛡️ Security

Best Practices

• 🔐 Environment Variables: Never commit secrets to repository
• 🔑 API Key Rotation: Regularly rotate API keys
• 📝 Audit Logging: Monitor all authentication attempts
• 🚫 Rate Limiting: Prevent abuse with configurable limits
• 🔒 Token Security: Bot tokens are hashed, never stored

Security Headers

// Implemented security measures
- API Key validation
- Request rate limiting
- Audit trail logging
- Client isolation
- Automatic cleanup

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the Repository

   git fork https://github.com/lokeshpanthangi/Discord-MCP.git
   

2. Create Feature Branch

   git checkout -b feature/amazing-feature
   

3. Make Changes

   • Follow existing code style
   • Add tests for new features
   • Update documentation

4. Run Quality Checks

   npm run validate
   

5. Commit Changes

   git commit -m "feat: add amazing feature"
   

6. Push and Create PR

   git push origin feature/amazing-feature
   

Development Guidelines

• ✅ Code Style: Use Prettier and ESLint
• ✅ Testing: Maintain 80%+ coverage
• ✅ Documentation: Update README for new features
• ✅ Security: Follow security best practices
• ✅ Performance: Consider rate limiting and resource usage

📄 License

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

• Send Messages: Send messages to Discord channels
• Get Messages: Retrieve recent messages from channels
• Get Channel Info: Fetch channel details and metadata
• Search Messages: Search for messages within channels
• Moderate Content: Perform moderation actions (delete messages, kick/ban users)
• Multi-Tenant Support: Support multiple Discord bots with isolated clients
• Claude Desktop Integration: Ready-to-use with Claude Desktop application
• Environment Variable Support: Flexible token configuration

🚀 Quick Start

Prerequisites

• Node.js 16+ installed
• Discord bot token (Create one here)
• Claude Desktop (for desktop integration)

Installation

1. Clone the repository

   git clone <repository-url>
   cd Discord-MCP
   

2. Install dependencies

   npm install
   

3. Set up environment variables

   # Create .env file
   echo "DISCORD_BOT_TOKEN=your_bot_token_here" > .env
   

4. Test the server

   node test-claude-desktop.js
   

🖥️ Claude Desktop Integration

Step 1: Configure Claude Desktop

Create or edit your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude-desktop/claude_desktop_config.json

Step 2: Add MCP Server Configuration

{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["path/to/your/Discord-MCP/server.js"],
      "env": {
        "DISCORD_BOT_TOKEN": "your_discord_bot_token_here",
        "NODE_ENV": "production"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Restart Claude Desktop to load the new MCP server configuration.

Step 4: Start Using Discord Commands

User: "Send a message 'Hello World!' to Discord channel 1234567890123456789"
Claude: I'll send that message to Discord for you!

🛠️ Available Tools

1. Send Message

{
  "name": "send_message",
  "arguments": {
    "channelId": "1234567890123456789",
    "content": "Hello from Claude!"
  }
}

2. Get Messages

{
  "name": "get_messages",
  "arguments": {
    "channelId": "1234567890123456789",
    "limit": 10
  }
}

3. Get Channel Info

{
  "name": "get_channel_info",
  "arguments": {
    "channelId": "1234567890123456789"
  }
}

4. Search Messages

{
  "name": "search_messages",
  "arguments": {
    "channelId": "1234567890123456789",
    "query": "important announcement",
    "limit": 50
  }
}

5. Moderate Content

{
  "name": "moderate_content",
  "arguments": {
    "action": "delete_message",
    "channelId": "1234567890123456789",
    "messageId": "9876543210987654321",
    "guildId": "1111111111111111111",
    "reason": "Spam content"
  }
}

🔐 Multi-Tenancy Support

The server supports multiple Discord bots simultaneously:

Option 1: Environment Variable (Recommended for Claude Desktop)

DISCORD_BOT_TOKEN=your_default_token

Option 2: Per-Request Token

{
  "name": "send_message",
  "arguments": {
    "discordBotToken": "specific_bot_token",
    "channelId": "1234567890123456789",
    "content": "Hello!"
  }
}

📁 Project Structure

Discord-MCP/
├── server.js                     # Main MCP server
├── tools/
│   ├── send_message.js           # Send messages tool
│   ├── get_messages.js           # Get messages tool
│   ├── get_channel_info.js       # Channel info tool
│   ├── search_messages.js        # Search messages tool
│   └── moderate_content.js       # Moderation tool
├── test-multi-tenant.js          # Multi-tenancy test
├── test-claude-desktop.js        # Claude Desktop test
├── CLAUDE_DESKTOP_SETUP.md       # Detailed setup guide
├── MULTI_TENANT_SETUP.md         # Multi-tenancy guide
├── claude_desktop_config.example.json # Example config
└── package.json

🧪 Testing

Test Multi-Tenancy

node test-multi-tenant.js

Test Claude Desktop Integration

node test-claude-desktop.js

🔧 Configuration Options

Environment Variables

• DISCORD_BOT_TOKEN: Default Discord bot token
• NODE_ENV: Environment mode (development or production)
• LOG_LEVEL: Logging level (debug, info, warn, error)

Bot Permissions Required

Your Discord bot needs these permissions:

• Send Messages
• Read Message History
• View Channels
• Manage Messages (for moderation)
• Kick Members (for moderation)
• Ban Members (for moderation)

🛡️ Security Features

• Token Hashing: Bot tokens are hashed for client identification
• No Token Persistence: Tokens are never stored permanently
• Client Isolation: Each bot token gets its own Discord client
• Automatic Cleanup: Unused clients are cleaned up automatically
• Input Validation: All inputs are validated before processing

📚 Documentation

• Claude Desktop Setup Guide
• Multi-Tenant Setup Guide

🤝 Usage Examples

Natural Language Commands with Claude

✅ "Send 'Meeting in 5 minutes' to the general channel"
✅ "Get the last 10 messages from announcements"
✅ "Search for 'project update' in dev-team channel"
✅ "Get information about channel ID 1234567890"
✅ "Delete spam message ID 9876543210"

Programmatic Usage

const { MCPServer } = require('./server');

const server = new MCPServer();
server.start();

🚨 Troubleshooting

Common Issues

1. "Invalid token" error

   • Verify your Discord bot token is correct
   • Check bot permissions in Discord server
   • Ensure bot is added to target servers

2. "Channel not found" error

   • Verify channel ID is correct
   • Check bot has access to the channel
   • Ensure channel exists and bot is in the server

3. "Permission denied" error

   • Check bot permissions in Discord
   • Verify bot role hierarchy
   • Ensure required intents are enabled

Debug Mode

Enable debug logging:

LOG_LEVEL=debug node server.js

📄 License

MIT License - see LICENSE file for details.

🤖 About MCP

This server implements the Model Context Protocol (MCP), allowing AI assistants to interact with Discord through a standardized interface.

Ready to integrate Discord with Claude? Follow the Claude Desktop Setup Guide to get started! 🚀