Discord MCP Server

Production-ready Model Context Protocol (MCP) server for AI-assisted Discord management and automation. Provides 71 tools for comprehensive Discord API integration through the MCP protocol.

Features

• 71 Discord Tools: Complete API coverage for messaging, channels, threads, roles, members, moderation, emojis, stickers, scheduled events, auto-moderation, and application commands

• MCP Protocol Compliant: Full implementation of Model Context Protocol for AI assistant integration

• Persistent Connection: Robust Discord.js client with automatic reconnection

• Production Ready: TypeScript, comprehensive error handling, structured logging

• Flexible Deployment: Run locally, in Docker, or Kubernetes

• Multiple Transports: HTTP and stdio modes supported

• Claude Code Native: First-class integration with Anthropic's Claude Code CLI

Table of Contents

• Getting Started

• Discord Bot Setup

• Local Usage

• Claude Code Integration

• Docker Deployment

• Kubernetes Deployment

• Available Tools

• Configuration

• Development

• Troubleshooting

Getting Started

Prerequisites

• Node.js >= 20.0.0

• Discord Bot Token - See Discord Bot Setup

• npm or yarn for dependency management

Quick Clone and Run

The server will start on http://localhost:3000 by default.

Discord Bot Setup

Before using this MCP server, you need to create a Discord bot and invite it to your server.

1. Create a Discord Application

1. Go to Discord Developer Portal

2. Click "New Application" and give it a name

3. Navigate to the "Bot" section in the left sidebar

4. Click "Add Bot" and confirm

2. Get Your Bot Token

1. In the Bot section, click "Reset Token" to generate a new token

2. Copy this token - you'll need it for your .env file

3. ⚠️ Never share this token publicly - treat it like a password

3. Configure Bot Permissions

In the Bot section, enable these Privileged Gateway Intents:

• ✅ Presence Intent (optional - for member status)

• ✅ Server Members Intent (required - for member management)

• ✅ Message Content Intent (required - for reading messages)

4. Invite Bot to Your Server

1. Go to the OAuth2 > URL Generator section

2. Select scopes:

   • ✅ bot

   • ✅ applications.commands

3. Select bot permissions (or choose Administrator for full access):

   • Manage Channels

   • Manage Roles

   • Manage Messages

   • Read Messages/View Channels

   • Send Messages

   • Manage Threads

   • Moderate Members

4. Copy the generated URL and open it in your browser

5. Select your server and click Authorize

5. Configure Your Environment

Edit .env and add your token:

Local Usage

Running the Server Locally

The MCP server can run directly on your machine without Docker or Kubernetes.

The server will log its startup:

Testing the Server

Using with Any MCP Client

The server implements the standard MCP protocol and works with any MCP-compatible client:

Claude Code Integration

Setup with Claude Code CLI

1. Start the MCP server locally:

   npm start # Server runs at http://localhost:3000/mcp

2. Add the server to Claude Code:

   claude mcp add --transport http discord-agent http://localhost:3000/mcp

3. Verify the connection:

   claude mcp list # Should show: discord-agent: http://localhost:3000/mcp (HTTP)

4. Use in Claude Code:

   • Open Claude Code

   • Type /mcp to see available servers

   • All 71 Discord tools are now available with mcp__discord-agent__ prefix

Alternative: Project-Specific Configuration

Create .mcp.json in your project root:

Example Usage in Claude Code

Once configured, you can use Discord tools directly in Claude Code conversations:

Docker Deployment

Build and Run with Docker

Using Docker Compose

Create docker-compose.yml:

Run with:

Kubernetes Deployment

Prerequisites

• Kubernetes cluster (K3s, K3d, minikube, or cloud provider)

• kubectl configured

Deploy to Kubernetes

1. Build and load the image (for local clusters like K3d):

   docker build -t discord-mcp-server:latest . k3d image import discord-mcp-server:latest -c your-cluster-name

2. Create the secret with your bot token:

   cp k8s/secret.yaml.example k8s/secret.yaml # Edit k8s/secret.yaml and replace YOUR_DISCORD_BOT_TOKEN_HERE

3. Deploy to the cluster:

   kubectl apply -f k8s/namespace.yaml kubectl apply -f k8s/secret.yaml kubectl apply -f k8s/configmap.yaml kubectl apply -f k8s/deployment.yaml kubectl apply -f k8s/service.yaml

4. Verify the deployment:

   kubectl get pods -n discord-agent-mcp kubectl logs -n discord-agent-mcp -l app=discord-mcp-server -f

5. Access the server:

   # Port-forward to localhost kubectl port-forward -n discord-agent-mcp svc/discord-mcp-server 3000:3000 # Test the connection curl http://localhost:3000/health

Available Tools (71)

Messaging (10 tools)

• send_message - Send a text message to a channel

• send_rich_message - Send formatted embeds with images and styling

• send_message_with_file - Send a message with file attachments

• read_messages - Retrieve message history from a channel

• edit_message - Edit an existing message

• delete_message - Delete a specific message

• bulk_delete_messages - Delete multiple messages at once (up to 100)

• add_reaction - Add emoji reactions to messages

• pin_message - Pin important messages

• unpin_message - Unpin messages

Channel Management (10 tools)

• list_channels - List all channels in a server

• get_channel_details - Get detailed channel information

• create_text_channel - Create a new text channel

• create_voice_channel - Create a new voice channel

• create_category - Create a category to organize channels

• create_forum_channel - Create a forum channel for discussions

• create_stage_channel - Create a stage channel for events

• modify_channel - Update channel settings (name, topic, slowmode)

• delete_channel - Delete a channel

• set_channel_permissions - Configure channel-specific permissions

Thread Management (3 tools)

• find_threads - Search for threads in a forum by name

• create_thread - Create a new thread in a channel

• archive_thread - Archive and lock a thread

Server Management (6 tools)

• get_server_info - Get detailed server information

• modify_server - Update server name, description, settings

• get_audit_logs - Retrieve audit log entries

• list_webhooks - List all webhooks in the server

• create_webhook - Create a new webhook

• get_invites - List active invite links

• create_invite - Create a new invite link

Member Management (3 tools)

• get_member_info - Get detailed member information

• list_members - List all members with optional filters

• set_nickname - Change a member's server nickname

Role Management (6 tools)

• assign_role - Add a role to a member

• remove_role - Remove a role from a member

• create_role - Create a new role with permissions

• delete_role - Delete a role

• modify_role - Update role settings and permissions

• list_roles - List all roles in the server

• get_role_info - Get detailed role information

Moderation (5 tools)

• kick_member - Remove a member (they can rejoin)

• ban_member - Ban a member from the server

• unban_member - Remove a ban

• timeout_member - Temporarily mute a member

• remove_timeout - Remove a timeout from a member

• get_bans - List all banned users

Emoji Management (4 tools) 🆕

• list_guild_emojis - Get all custom emojis for a guild

• create_emoji - Upload a custom emoji from base64 or file path

• modify_emoji - Update emoji name or role restrictions

• delete_emoji - Delete a custom emoji

Sticker Management (4 tools) 🆕

• list_guild_stickers - Get all custom stickers for a guild

• create_sticker - Upload a custom sticker (PNG/APNG/Lottie)

• modify_sticker - Update sticker name, description, or tags

• delete_sticker - Delete a custom sticker

Scheduled Events (6 tools)

• list_scheduled_events - Get all scheduled events for a guild

• get_event_details - Get detailed information about a specific event

• create_scheduled_event - Create Stage, Voice, or External events

• modify_scheduled_event - Update event properties and status

• delete_scheduled_event - Delete or cancel an event

• get_event_users - Get list of users interested in an event

Auto-Moderation (5 tools) 🆕

• list_automod_rules - Get all auto-moderation rules for a guild

• get_automod_rule - Get detailed information about a specific rule

• create_automod_rule - Create keyword, spam, or mention filtering rules

• modify_automod_rule - Update rule settings, keywords, or actions

• delete_automod_rule - Delete an auto-moderation rule

Application Commands (6 tools) 🆕

• list_application_commands - List all slash commands (guild or global)

• get_application_command - Get detailed command information

• create_application_command - Create slash commands or context menus

• modify_application_command - Update command properties

• delete_application_command - Delete a slash command

• bulk_overwrite_commands - Sync all commands at once

Resources

• discord://guilds - List all guilds the bot is connected to

Note: Dynamic guild-specific resources (channels, roles, members) will be added in a future release when MCP SDK supports URI templates. Use the corresponding tools (list_channels, list_roles, list_members, etc.) to access guild-specific data.

Prompts (8 total) 🆕

• moderate-channel - Interactive channel moderation assistant

• create-announcement - Step-by-step announcement creation guide

• setup-server - Interactive wizard for organizing new server structure

• create-scheduled-event - Guided event creation with timing and type selection

• configure-automod-rule - Auto-moderation rule setup (Phase 3 preview)

• audit-permissions - Security audit and permission analysis

• setup-welcome-automation - Configure welcome messages and auto-roles

Configuration

Environment Variables

Create a .env file (use .env.example as a template):

Transport Modes

HTTP Mode (default):

• Server listens on HTTP port

• Suitable for remote connections

• Works with Claude Code HTTP transport

• Supports multiple concurrent clients

Stdio Mode:

• Communicates via stdin/stdout

• Suitable for local process integration

• Lower latency for local clients

• Single client only

Development

Project Structure

Building and Testing

Adding New Tools

1. Create or modify a tool file in src/tools/

2. Use the server.registerTool() method

3. Define input/output schemas with Zod

4. Implement the tool logic

5. Rebuild and restart the server

Example:

Troubleshooting

Discord Connection Issues

Bot not connecting:

• Verify your DISCORD_TOKEN in .env is correct

• Check the token hasn't been regenerated in Discord Developer Portal

• Ensure bot has proper intents enabled (Server Members, Message Content)

Bot connected but can't see channels:

• Check bot has "View Channels" permission

• Ensure bot role is positioned correctly in role hierarchy

• Verify bot has been added to your server

MCP Server Issues

Server won't start:

Tools not working:

Claude Code Integration Issues

Claude Code can't connect:

Tools not appearing:

• Restart Claude Code after adding the server

• Check server logs for connection attempts

• Verify no firewall blocking localhost:3000

Permission Errors

Bot can't perform actions:

• Verify bot has the required permission for the action

• Check bot's role position in server settings

• Ensure channel-specific permissions aren't blocking the bot

• Try giving bot "Administrator" permission temporarily for testing

Security

Best Practices

• Never commit - Always use .env.example as a template

• Rotate tokens regularly - Regenerate bot token periodically

• Use least privilege - Only grant necessary Discord permissions

• Secure your server - Use firewall rules if exposing HTTP port

• Monitor audit logs - Check Discord's audit log for bot actions

Token Security

Your Discord bot token should be treated like a password:

✅ Do:

• Store in .env file (gitignored)

• Use environment variables in production

• Regenerate if exposed

• Use Kubernetes secrets for cluster deployments

❌ Don't:

• Commit tokens to version control

• Share tokens publicly

• Embed tokens in code

• Expose tokens in logs

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes with clear commit messages

4. Test thoroughly with a development Discord server

5. Submit a pull request

Guidelines

• Security First: Never commit secrets or tokens

• TypeScript: Use strict typing and follow existing patterns

• Documentation: Update README and add JSDoc comments

• Testing: Test with a development server before submitting

• Code Style: Run npm run lint before committing

License

MIT License - See LICENSE file for details

Resources

• Model Context Protocol - MCP specification and documentation

• Discord Developer Portal - Create and manage Discord bots

• Discord.js Guide - Discord.js library documentation

• Claude Code - AI-powered development assistant

• MCP TypeScript SDK - Official MCP SDK

Support

• Issues: GitHub Issues

• Discord.js: Discord.js Discord Server

• MCP Protocol: MCP Specification

Built with ❤️ using TypeScript, Discord.js, and the Model Context Protocol