npm package: @iflow-mcp/discord-mcp
Description: Model Context Protocol (MCP) server for Discord API integration
Author: SaseQ
Latest version: 0.0.3

# Discord MCP Server

> **⚠️ SECURITY WARNING**: This project handles Discord bot tokens and server access. Please read our [Security Policy](SECURITY.md) before using or contributing.

A comprehensive Model Context Protocol (MCP) server for Discord API integration, providing powerful Discord bot management capabilities through a standardized interface.

## Features

This server provides **93 Discord tools** organized into the following categories:

| Category | Tools Count | Description |
|----------|-------------|-------------|
| Message Management | 18 tools | Send, edit, delete, reactions, pin, bulk operations |
| Channel Management | 25 tools | Create/edit/delete all channel types, positions, privacy |
| Member & Role Management | 12 tools | Add/remove roles, edit members, search, info retrieval |
| Voice & Audio | 6 tools | Join/leave voice, play audio, volume control |
| Webhooks | 4 tools | Create, delete, list, send webhook messages |
| Events & Scheduling | 4 tools | Create, edit, delete, list server events |
| Emoji & Stickers | 6 tools | Manage custom emojis and stickers |
| Privacy & Security | 7 tools | Auto-moderation, privacy controls, bulk settings |
| Server Administration | 6 tools | Server settings, welcome screen, widget management |
| Analytics & Export | 5 tools | Statistics, message history, chat log export |

### Key Tools

- **`discord_manage`** - Unified tool that handles all 93 operations through one interface
- **`comprehensive_channel_management`** - Multi-operation channel orchestrator
- **`bulk_set_privacy`** - Mass privacy control across channels/categories
- **`organize_channels`** - Advanced channel/category positioning system
- **`export_chat_log`** - Professional chat export in JSON/CSV/TXT formats

## Quick Start

### Prerequisites

- Node.js 18+ and npm
- Discord bot token (see setup below)

### Installation

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

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start
```

### Development Mode

```bash
npm run dev
```

## Configuration

### Discord Bot Setup

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Create a new application and bot
3. Copy the bot token to your `.env` file
4. **IMPORTANT**: Regenerate your token if you suspect it's been exposed

### Environment Variables

Create a `.env` file:

```env
# Your Discord bot token (KEEP SECRET!)
DISCORD_TOKEN=your_bot_token_here

# Default Discord server ID (optional)
DISCORD_GUILD_ID=your_guild_id_here
```

### Required Bot Permissions

```
Manage Server
Manage Roles  
Manage Channels
Manage Messages
View Channels
Send Messages
Connect (for voice)
Speak (for voice)
```

## Usage

### MCP Integration

Use with MCP-compatible clients:

```bash
# Via stdio
npx discord-mcp

# Via HTTP (port 3001)
HTTP_PORT=3001 npx discord-mcp
```

### Examples

#### Using the Master Control Tool

```typescript
// All operations through one unified interface
await discord_manage({
  action: 'send_message',
  channelId: '123',
  message: 'Hello World!'
});

await discord_manage({
  action: 'create_text_channel',
  guildId: '456',
  name: 'new-channel'
});

await discord_manage({
  action: 'comprehensive_channel_management',
  guildId: '456',
  operations: [
    { action: 'create_category', name: 'New Category' },
    { action: 'create_text_channel', name: 'general', categoryId: 'cat_id' },
    { action: 'set_channel_private', channelId: 'chan_id', isPrivate: true }
  ]
});
```

#### Using Individual Tools

```typescript
// Server information
await discord.getServerInfo(guildId);

// Advanced channel creation
await discord.createForumChannel(guildId, "discussions", categoryId, {
  topic: "Community discussions",
  slowmode: 30,
  isPrivate: true,
  allowedRoles: ["member_role_id"]
});

// Bulk privacy management
await discord.bulkSetPrivacy(guildId, {
  targets: [
    { id: "channel1", type: "channel", isPrivate: true },
    { id: "category1", type: "category", isPrivate: false }
  ]
});

// Export chat logs
await discord.exportChatLog(channelId, "JSON", {
  limit: 1000,
  dateRange: { start: "2024-01-01", end: "2024-12-31" }
});
```

## Security

### For Users

- Keep your Discord bot token secret
- Regularly rotate your tokens
- Monitor bot activity
- Use minimal required permissions

### For Contributors

- Never commit tokens or secrets
- Validate all user inputs
- Review dependencies for vulnerabilities
- Follow secure coding practices

## Tool Reference

<details>
<summary>Complete Tool List (93 Tools)</summary>

### Message Management Tools (18)

| Tool Name | Description |
|-----------|-------------|
| `send_message` | Send messages to channels |
| `edit_message` | Edit existing messages |
| `delete_message` | Delete specific messages |
| `read_messages` | Read message history from channels |
| `send_private_message` | Send DMs to users |
| `edit_private_message` | Edit private messages |
| `delete_private_message` | Delete private messages |
| `read_private_messages` | Read DM history |
| `add_reaction` | Add emoji reactions |
| `remove_reaction` | Remove emoji reactions |
| `pin_message` | Pin messages in channels |
| `unpin_message` | Unpin messages |
| `get_pinned_messages` | List pinned messages |
| `bulk_delete_messages` | Delete multiple messages |
| `crosspost_message` | Crosspost announcements |
| `get_message_history` | Advanced message history with pagination |
| `get_message_attachments` | Extract message attachments |
| `read_images` | Read and analyze images from messages |

### Channel Management Tools (25)

| Tool Name | Description |
|-----------|-------------|
| `create_text_channel` | Create text channels |
| `create_voice_channel` | Create voice channels |
| `create_forum_channel` | Create forum channels |
| `create_announcement_channel` | Create announcement channels |
| `create_stage_channel` | Create stage channels |
| `edit_channel_advanced` | Edit any channel with advanced settings |
| `delete_channel` | Delete channels |
| `find_channel` | Find channels by name |
| `list_channels` | List all server channels |
| `create_category` | Create channel categories |
| `delete_category` | Delete categories |
| `find_category` | Find categories by name |
| `list_channels_in_category` | List channels in specific category |
| `set_channel_position` | Move channel position |
| `set_channel_positions` | Move multiple channels |
| `set_category_position` | Move category position |
| `move_channel_to_category` | Move channels between categories |
| `organize_channels` | Comprehensive channel organization |
| `get_channel_structure` | Get complete channel hierarchy |
| `set_channel_private` | Set channel privacy settings |
| `set_category_private` | Set category privacy settings |
| `bulk_set_privacy` | Bulk privacy management |
| `comprehensive_channel_management` | All-in-one channel operations |
| `upload_file` | Upload files to channels |
| `export_chat_log` | Export chat logs (JSON/CSV/TXT) |

### Member & Role Management Tools (12)

| Tool Name | Description |
|-----------|-------------|
| `get_user_id_by_name` | Find user IDs by username |
| `get_members` | List server members with pagination |
| `search_members` | Search members by name |
| `edit_member` | Edit member properties |
| `get_member_info` | Get detailed member information |
| `create_role` | Create new server roles |
| `delete_role` | Delete server roles |
| `edit_role` | Modify role properties |
| `add_role_to_member` | Assign roles to members |
| `remove_role_from_member` | Remove roles from members |
| `get_roles` | List all server roles |
| `set_role_positions` | Reorder role hierarchy |

### Voice & Audio Tools (6)

| Tool Name | Description |
|-----------|-------------|
| `join_voice_channel` | Connect bot to voice channels |
| `leave_voice_channel` | Disconnect from voice channels |
| `play_audio` | Stream audio in voice channels |
| `stop_audio` | Stop audio playback |
| `set_volume` | Control audio volume |
| `get_voice_connections` | List active voice connections |

### Webhook Tools (4)

| Tool Name | Description |
|-----------|-------------|
| `create_webhook` | Create channel webhooks |
| `delete_webhook` | Delete webhooks |
| `list_webhooks` | List channel webhooks |
| `send_webhook_message` | Send messages via webhooks |

### Events & Scheduling Tools (4)

| Tool Name | Description |
|-----------|-------------|
| `create_event` | Create scheduled server events |
| `edit_event` | Edit existing events |
| `delete_event` | Delete server events |
| `get_events` | List all scheduled events |

### Emoji & Sticker Tools (6)

| Tool Name | Description |
|-----------|-------------|
| `create_emoji` | Create custom server emojis |
| `delete_emoji` | Delete custom emojis |
| `get_emojis` | List all server emojis |
| `create_sticker` | Create custom server stickers |
| `delete_sticker` | Delete custom stickers |
| `get_stickers` | List all server stickers |

### Privacy & Security Tools (7)

| Tool Name | Description |
|-----------|-------------|
| `create_automod_rule` | Create automoderation rules |
| `edit_automod_rule` | Edit automod rules |
| `delete_automod_rule` | Delete automod rules |
| `get_automod_rules` | List all automod rules |
| `create_invite` | Create server invites |
| `delete_invite` | Delete/revoke invites |
| `get_invites` | List all server invites |

### Server Administration Tools (6)

| Tool Name | Description |
|-----------|-------------|
| `get_server_info` | Get comprehensive server information |
| `edit_server` | Edit server settings |
| `get_server_widget` | Get server widget information |
| `get_welcome_screen` | Get welcome screen settings |
| `edit_welcome_screen` | Configure welcome screen |
| `get_server_stats` | Get comprehensive server statistics |

### Interactive Components Tools (4)

| Tool Name | Description |
|-----------|-------------|
| `send_embed` | Send rich embed messages |
| `send_button` | Send messages with interactive buttons |
| `send_select_menu` | Send messages with select menus |
| `send_modal` | Send modal dialogs (interaction context) |

### Master Control Tool (1)

| Tool Name | Description |
|-----------|-------------|
| `discord_manage` | Unified tool - access ALL 93 operations through one interface |

</details>

## Contributing

**Project Creator & Lead Developer**: [@sashathelambo](https://github.com/sashathelambo) (Dr. Vova)

This project is primarily developed and maintained by sashathelambo. For contributions:

1. Read our [Contributing Guidelines](CONTRIBUTING.md)
2. Follow our [Security Policy](SECURITY.md)
3. Use the PR template
4. Test thoroughly before submitting
5. Discuss major changes with [@sashathelambo](https://github.com/sashathelambo) first

### Development Guidelines

- Use TypeScript for all code
- Follow existing code style
- Add tests for new features
- Never commit sensitive data
- Update documentation

## Troubleshooting

### Common Issues

- **Token Invalid**: Regenerate your Discord bot token
- **Permission Denied**: Check bot permissions in Discord server
- **Build Errors**: Ensure Node.js 18+ and TypeScript are installed

### Getting Help

- Check our [documentation](docs/)
- [Report bugs](issues/new?template=bug_report.md)
- [Request features](issues/new?template=feature_request.md)
- Join our community discussions

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer

This software is provided "as-is" without warranty. Users are responsible for:

- Complying with Discord's Terms of Service
- Securing their bot tokens and credentials  
- Using appropriate permissions and rate limiting
- Monitoring and maintaining their Discord bots

## Acknowledgments

- **[@sashathelambo](https://github.com/sashathelambo) (Dr. Vova)** - Project creator, lead developer, and architect of all 93 Discord tools
- Discord.js team for the excellent Discord API wrapper
- Model Context Protocol community for the standardized protocol
- Everyone who uses and supports this project