# Dc-MCP

**Discord Administration MCP Server** for Cursor.

Dc-MCP connects Cursor to a Discord bot over the Model Context Protocol (stdio). Cursor can inspect a guild’s full structure and run precise admin actions through explicit tools — not a free-form Discord API executor.

```text
Cursor  ──MCP (stdio)──▶  Dc-MCP  ──discord.py──▶  Discord API
```

## Features

- Full guild map for Cursor (`discord_analyze_server` / `discord_server_structure`)
- Granular tools for channels, roles, members, messages, moderation, invites, webhooks, audit logs
- Central permission + hierarchy checks (no owner targeting, no roles above the bot)
- Destructive action protection (`confirm=true` + optional hard disable)
- Structured JSON results; secrets never returned or logged
- Stdio transport compatible with Cursor’s MCP client

## Requirements

- Python 3.11+
- A Discord application + bot
- Privileged intents: **Server Members Intent**, **Message Content Intent**

## Quick start

```bash
git clone https://github.com/669px/Dc-MCP.git
cd Dc-MCP
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
cp .env.example .env
```

Edit `.env`:

```env
DISCORD_BOT_TOKEN=your_bot_token
DISCORD_GUILD_ID=your_guild_id
ALLOW_DANGEROUS_ACTIONS=true
REQUIRE_CONFIRMATION=true
LOG_LEVEL=INFO
```

Run:

```bash
python -m src.main
```

Logs go to **stderr**. **stdout** is reserved for MCP JSON-RPC.

## Discord bot setup

1. Create an application at the [Discord Developer Portal](https://discord.com/developers/applications)
2. Add a bot and copy the token into `DISCORD_BOT_TOKEN`
3. Enable **Server Members Intent** and **Message Content Intent**
4. Invite the bot with permissions such as Manage Channels/Roles/Messages, Kick/Ban, Moderate Members, View Audit Log, Manage Webhooks/Guild, Send Messages, Embed Links, Add Reactions, Read Message History, Create Instant Invite
5. Place the bot role high enough to manage the roles/members you intend to administer
6. Set `DISCORD_GUILD_ID` to restrict all operations to one guild

## Cursor MCP config

Project or user `mcp.json`:

```json
{
  "mcpServers": {
    "discord-admin": {
      "command": "/ABSOLUTE/PATH/TO/Dc-MCP/.venv/bin/python",
      "args": ["-m", "src.main"],
      "cwd": "/ABSOLUTE/PATH/TO/Dc-MCP"
    }
  }
}
```

Secrets load from `.env` in `cwd`. After saving, enable/refresh **discord-admin** under **Settings → Tools & MCP**.

CLI:

```bash
agent mcp enable discord-admin
agent mcp list
```

## Core tools

| Tool | Purpose |
|---|---|
| `discord_analyze_server` | Full guild map + summary for Cursor |
| `discord_server_structure` | Lighter category/channel/role tree |
| `discord_server_info` | Guild metadata |
| `discord_list_channels` / `discord_list_roles` / `discord_list_members` | Inventory |
| `discord_get_audit_log` | Filtered audit entries |

Also included: channel CRUD + permissions, role CRUD + assign/remove, member moderation (kick/ban/timeout/nick), messaging (send/edit/delete/pin/react), invites, webhooks, and `discord_purge_messages`.

Destructive tools require `confirm=true` when `REQUIRE_CONFIRMATION=true`.

## Security

- Never commit `.env`
- Prefer `REQUIRE_CONFIRMATION=true`
- Scope with `DISCORD_GUILD_ID`
- Mentions default to restricted (`@everyone` / mass roles off unless allowed)
- No shell, eval, HTTP proxy, or generic API executor tools
- Webhook tokens are never returned

## Project layout

```text
src/
  main.py              MCP entrypoint (stdio)
  config.py            Environment settings
  discord_client.py    discord.py client
  permissions.py       Guild / hierarchy / confirmation gates
  errors.py            Structured error mapping
  responses.py         Success / failure payloads
  server_map.py        Full guild analysis for Cursor
  tools/               Granular MCP tools
tests/                 Unit tests (mocked Discord)
```

## Development

```bash
source .venv/bin/activate
python -m compileall src
python -m pytest
python -c "import discord; print(discord.__version__)"
```

## Discord limitations

- Bulk delete only works for messages younger than 14 days
- Bulk/purge caps default to 100
- Cannot moderate the guild owner or targets at/above the bot’s highest role
- Managed/integration roles cannot be edited
- Member list/search requires Server Members Intent

## License

MIT