# Discord Notifications MCP Server

MCP server that gives AI coding agents access to Discord: send notifications to multiple channels, create channels for new projects, and post questions (yes/no, multiple choice, extended answer) with optional two-way response.

## Requirements

- Python 3.10+
- A [Discord Bot](https://discord.com/developers/applications): create an application, add a bot, copy the token. Invite the bot to your server with scopes: `bot`, permissions: Send Messages, View Channels, Manage Channels, Read Message History, Use Slash Commands (if needed). For **questions with buttons**, enable **Message Content Intent** in the Bot settings.

## Config

| Env / file | Purpose |
|------------|--------|
| `DISCORD_BOT_TOKEN` or `DISCORD_TOKEN` | Bot token (required). |
| `DISCORD_GUILD_ID` | Default guild ID for `list_channels` when guild_id is omitted. |
| `DISCORD_CHANNELS` | JSON map of channel keys → IDs, e.g. `{"general": "123","alerts": "456"}`. |
| `DISCORD_MCP_CONFIG_DIR` | Directory for `channels.json` (default: current dir). |
| `channels.json` | Same as `DISCORD_CHANNELS`: `{"general": 123, "alerts": 456}`. |

Channel keys let agents use `send_notification("general", "Done.")` instead of raw channel IDs.

## Install and run

```bash
cd mcp-discord-notify
pip install -r requirements.txt
export DISCORD_BOT_TOKEN=your_bot_token
# optional: export DISCORD_GUILD_ID=your_server_id
# optional: create channels.json or set DISCORD_CHANNELS
python main.py
```

The server runs over stdio (JSON-RPC). Configure your MCP client to run:

- **Command**: `python` (or `uv run python`)
- **Args**: `["/absolute/path/to/mcp-discord-notify/main.py"]`
- **Env**: `DISCORD_BOT_TOKEN=...` (and optionally `DISCORD_GUILD_ID`, `DISCORD_CHANNELS`)

## Cursor

Add to MCP settings (or `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "discord-notifications": {
      "command": "python",
      "args": ["/home/skitz0/Documents/claude-cord/mcp-discord-notify/main.py"],
      "env": {
        "DISCORD_BOT_TOKEN": "your_bot_token",
        "DISCORD_GUILD_ID": "your_guild_id"
      }
    }
  }
}
```

Use the real path to `main.py` and set the env vars (or rely on your shell env).

## Tools

| Tool | Description |
|------|-------------|
| **list_channels** | List channels in a guild (id, name, key if in config). |
| **send_notification** | Send a message to a channel (by ID or key). |
| **create_channel** | Create a text channel; optional `register_key` to save for future use by name. |
| **send_question** | Post a question with yes/no, multiple choice, or extended answer; optionally wait for first response. |

### Questions (two-way)

- **yes_no**: Two buttons (Yes / No).
- **multiple_choice**: Buttons per option; pass `options` as JSON array string, e.g. `["A","B","C"]`.
- **extended**: "Reply" button opens a modal for long-form text.

Set `wait_timeout_seconds` (default 300); the tool returns the first response or timeout.

## New project channels

Use **create_channel** with **register_key** so agents can target the channel by name. See the project skill: `.cursor/skills/discord-notifications/SKILL.md`.