# mcp-discord-mod

A lightweight [Model Context Protocol](https://modelcontextprotocol.io/) server for **Discord server moderation**. Built with discord.js v14 and TypeScript.

Focused on what matters: kick, ban, timeout, roles, channels, audit logs, and member management. No bloat.

## Setup

### 1. Create a Discord Bot

1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Create a new application → Bot
3. Under **Privileged Gateway Intents**, enable:
   - Server Members Intent
   - Message Content Intent
4. Copy the bot token

### 2. Install

```bash
git clone https://github.com/YOUR_USERNAME/mcp-discord-mod.git
cd mcp-discord-mod
npm install
npm run build
```

### 3. Configure

Set your bot token as an environment variable:

```bash
export DISCORD_TOKEN="your_bot_token_here"
```

Or create a `.env` file:

```
DISCORD_TOKEN=your_bot_token_here
```

### 4. Add to your MCP client

Add to your MCP config (e.g. `opencode.json`, `claude_desktop_config.json`, etc.):

```json
{
  "discord-mod": {
    "type": "local",
    "command": ["node", "/path/to/mcp-discord-mod/build/index.js"],
    "env": {
      "DISCORD_TOKEN": "your_bot_token_here"
    }
  }
}
```

## Tools

| Tool | Description |
|---|---|
| `discord_mod_login` | Login to Discord (auto-logins if DISCORD_TOKEN is set) |
| `discord_mod_kick_member` | Kick a member from a server |
| `discord_mod_ban_member` | Ban a member (optionally delete recent messages) |
| `discord_mod_unban_member` | Unban a user |
| `discord_mod_timeout_member` | Timeout (mute) a member for a duration |
| `discord_mod_warn_member` | Send a warning DM to a member |
| `discord_mod_list_bans` | List all banned users |
| `discord_mod_set_nickname` | Set or clear a member's nickname |
| `discord_mod_list_roles` | List all roles in a server |
| `discord_mod_create_role` | Create a new role |
| `discord_mod_edit_role` | Edit role properties |
| `discord_mod_delete_role` | Delete a role |
| `discord_mod_assign_role` | Assign a role to a member |
| `discord_mod_remove_role` | Remove a role from a member |
| `discord_mod_create_category` | Create a channel category |
| `discord_mod_create_channel` | Create a text or voice channel |
| `discord_mod_delete_channel` | Delete a channel |
| `discord_mod_edit_channel` | Edit channel name, topic, slowmode |
| `discord_mod_set_permissions` | Set role/user permissions on a channel |
| `discord_mod_remove_permissions` | Remove permission overrides |
| `discord_mod_list_members` | List server members |
| `discord_mod_get_member` | Get detailed member info |
| `discord_mod_list_servers` | List all bot servers |
| `discord_mod_get_server_info` | Get server details and channels |
| `discord_mod_get_audit_log` | View the server audit log |
| `discord_mod_send_dm` | Send a direct message to a user |
| `discord_mod_purge_messages` | Bulk delete messages with filters |
| `discord_mod_bulk_delete_messages` | Delete up to 100 messages by ID |
| `discord_mod_pin_message` | Pin a message |
| `discord_mod_unpin_message` | Unpin a message |

## Bot Permissions

Your bot needs these permissions in the server:

- **Kick Members**
- **Ban Members**
- **Moderate Members** (for timeouts)
- **Manage Roles**
- **Manage Channels**
- **View Audit Log**
- **Send Messages**
- **Read Message History**
- **Manage Messages** (for purge)

## License

MIT