# Discord MCP Server

[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen.svg)](https://nodejs.org)

<a href="https://glama.ai/mcp/servers/@scarecr0w12/discord-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@scarecr0w12/discord-mcp/badge" alt="Discord MCP server" />
</a>

A Model Context Protocol (MCP) server that provides comprehensive tools for managing Discord servers. This server uses HTTP transport with Server-Sent Events (SSE) for real-time communication.

## Features

- **50+ Discord Management Tools** across 12 categories
- **10 MCP Prompts** for guided server management workflows
- **HTTP Transport** with StreamableHTTPServerTransport for easy integration
- **Session Management** for concurrent MCP connections
- **Comprehensive Error Handling** with detailed error messages
- **Graceful Shutdown** handling

## Prerequisites

- Node.js 18+ 
- A Discord Bot Token with appropriate permissions
- Discord bot added to your server(s)

## Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/scarecr0w12/discord-mcp.git
   cd discord-mcp
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Create a `.env` file from the example:
   ```bash
   cp .env.example .env
   ```

4. Configure your Discord bot token in `.env`:
   ```
   DISCORD_BOT_TOKEN=your_bot_token_here
   PORT=3000
   ```

5. Build the project:
   ```bash
   npm run build
   ```

6. Start the server:
   ```bash
   npm start
   ```

## Discord Bot Setup

Your Discord bot requires the following Gateway Intents enabled in the [Discord Developer Portal](https://discord.com/developers/applications):

- **GUILDS** - Access to guild information
- **GUILD_MEMBERS** - Access to member information (Privileged)
- **GUILD_MODERATION** - Access to moderation events
- **GUILD_MESSAGES** - Access to messages
- **GUILD_PRESENCES** - Access to presence information (Privileged)
- **MESSAGE_CONTENT** - Access to message content (Privileged)

## Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `DISCORD_BOT_TOKEN` | Your Discord bot token (required) | - |
| `PORT` | HTTP server port (HTTP mode only) | `3000` |
| `MCP_TRANSPORT` | Transport mode (`stdio` or `http`) | `http` |

## Usage

The server supports two transport modes:

### HTTP Mode (Default)

Start the server in HTTP mode:
```bash
npm start
```

#### HTTP Endpoints

- `POST /mcp` - MCP requests
- `GET /mcp` - SSE stream for server-initiated messages
- `DELETE /mcp` - Session cleanup
- `GET /health` - Health check endpoint

#### VS Code MCP Configuration (HTTP)

Add to your `.vscode/mcp.json`:

```json
{
  "servers": {
    "discord-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

### Stdio Mode

For use with Claude Desktop, Cline, or other MCP clients that use stdio transport:

```bash
npm start -- --stdio
# or
MCP_TRANSPORT=stdio npm start
```

#### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "discord-mcp": {
      "command": "node",
      "args": ["/path/to/discord-mcp/dist/index.js", "--stdio"],
      "env": {
        "DISCORD_BOT_TOKEN": "your_bot_token_here"
      }
    }
  }
}
```

#### Cline Configuration

Add to your Cline MCP settings:

```json
{
  "mcpServers": {
    "discord-mcp": {
      "command": "node",
      "args": ["/path/to/discord-mcp/dist/index.js", "--stdio"],
      "env": {
        "DISCORD_BOT_TOKEN": "your_bot_token_here"
      }
    }
  }
}
```

## Available Tools

### Server Management
- `list_servers` - List all Discord servers the bot has access to
- `get_server_info` - Get detailed information about a specific server
- `modify_server` - Modify server settings

### Channel Management
- `list_channels` - List all channels in a server
- `get_channel_info` - Get detailed channel information
- `create_channel` - Create a new channel
- `delete_channel` - Delete a channel
- `modify_channel` - Modify channel settings

### Member Management
- `list_members` - List server members
- `get_member_info` - Get member details
- `modify_member` - Modify member properties
- `kick_member` - Kick a member from the server
- `ban_member` - Ban a member
- `unban_member` - Unban a member
- `list_bans` - List all bans

### Role Management
- `list_roles` - List all roles
- `get_role_info` - Get role details
- `create_role` - Create a new role
- `delete_role` - Delete a role
- `modify_role` - Modify role settings
- `assign_role` - Assign a role to a member
- `remove_role` - Remove a role from a member

### Permission Management
- `get_channel_permissions` - Get channel permission overwrites
- `set_channel_permission` - Set channel permissions
- `delete_channel_permission` - Delete permission overwrites
- `list_permissions` - List available permissions
- `sync_channel_permissions` - Sync permissions with category

### Message Management
- `send_message` - Send a message to a channel
- `get_messages` - Retrieve messages from a channel
- `edit_message` - Edit a bot message
- `delete_message` - Delete a message
- `bulk_delete_messages` - Bulk delete messages (up to 100)
- `pin_message` / `unpin_message` - Pin/unpin messages
- `get_pinned_messages` - Get all pinned messages
- `add_reaction` / `remove_reactions` - Manage reactions

### Emoji & Sticker Management
- `list_emojis` - List server emojis
- `create_emoji` - Create a custom emoji
- `delete_emoji` - Delete an emoji
- `modify_emoji` - Modify emoji settings
- Sticker operations (list, create, delete, modify)

### Webhook Management
- `list_channel_webhooks` / `list_guild_webhooks` - List webhooks
- `create_webhook` - Create a webhook
- `delete_webhook` - Delete a webhook
- `modify_webhook` - Modify webhook settings
- `send_webhook_message` - Send a message via webhook

### Invite Management
- `list_invites` - List server invites
- `get_invite_info` - Get invite details
- `create_invite` - Create an invite
- `delete_invite` - Delete an invite

### Event Management
- `list_events` - List scheduled events
- `get_event_info` - Get event details
- `create_event` - Create a scheduled event
- `modify_event` - Modify an event
- `delete_event` - Delete an event
- `get_event_subscribers` - Get event subscribers

### Thread Management
- `list_threads` - List threads in a channel or server
- `create_thread` - Create a new thread
- `create_forum_post` - Create a forum post
- `modify_thread` - Modify thread settings
- `delete_thread` - Delete/archive a thread
- Thread join/leave and member management operations

### Audit & Moderation
- `get_audit_logs` - Retrieve server audit logs
- `list_audit_log_types` - List available audit log action types
- `list_automod_rules` - List AutoMod rules
- `get_automod_rule` - Get AutoMod rule details
- `delete_automod_rule` - Delete an AutoMod rule
- `toggle_automod_rule` - Enable/disable an AutoMod rule

## Available Prompts

MCP Prompts provide guided workflows for complex server management tasks. Use these prompts to start structured conversations for common administrative operations.

| Prompt | Description |
|--------|-------------|
| `server-audit` | Comprehensive security and configuration audit checklist |
| `moderation-report` | Generate moderation activity summaries from audit logs |
| `channel-setup-guide` | Step-by-step guidance for setting up new channels |
| `role-hierarchy-review` | Analyze and suggest improvements to role hierarchy |
| `permission-troubleshoot` | Diagnose why a user cannot perform a specific action |
| `welcome-message-template` | Generate customized server welcome messages |
| `announcement-draft` | Draft formatted server announcements |
| `automod-setup-guide` | Guide for configuring Discord AutoMod rules |
| `webhook-security-audit` | Audit webhooks for security concerns |
| `member-onboarding-review` | Review and improve new member experience |

### Using Prompts

Prompts can be invoked in MCP-compatible clients. Each prompt accepts arguments to customize the workflow:

```
# Example: Server Audit
Prompt: server-audit
Arguments: { "guildId": "123456789" }

# Example: Channel Setup Guide  
Prompt: channel-setup-guide
Arguments: { "channelType": "forum", "purpose": "community feedback" }
```

## Development

```bash
# Run in development mode with hot reload
npm run dev

# Build the project
npm run build

# Start the production server
npm start
```

## Attributions

This project is built with the following open-source libraries:

- **[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)** - Official MCP TypeScript SDK
- **[discord.js](https://discord.js.org/)** - A powerful JavaScript library for interacting with the Discord API
- **[Express](https://expressjs.com/)** - Fast, unopinionated, minimalist web framework for Node.js
- **[Zod](https://zod.dev/)** - TypeScript-first schema validation with static type inference
- **[dotenv](https://github.com/motdotla/dotenv)** - Loads environment variables from .env file

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

## License

ISC License - see the [LICENSE](LICENSE) file for details.

## Author

**Jacob Bowen** - [@scarecr0w12](https://github.com/scarecr0w12)