README.md
Send notifications, create channels, and post interactive questions to Discord.
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: 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
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(oruv run python) - Args:
["/absolute/path/to/mcp-discord-notify/main.py"] - Env:
DISCORD_BOT_TOKEN=...(and optionallyDISCORD_GUILD_ID,DISCORD_CHANNELS)
Cursor
Add to MCP settings (or .cursor/mcp.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
optionsas 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.
Tools (4)
list_channelsList channels in a guild including ID, name, and key if configured.send_notificationSend a message to a specific Discord channel using its ID or key.create_channelCreate a new text channel with an optional key for future reference.send_questionPost a question with yes/no, multiple choice, or extended answer options and wait for a response.Environment Variables
DISCORD_BOT_TOKENrequiredThe authentication token for your Discord bot.DISCORD_GUILD_IDDefault guild ID for list_channels when guild_id is omitted.DISCORD_CHANNELSJSON map of channel keys to IDs.DISCORD_MCP_CONFIG_DIRDirectory for channels.json configuration file.Configuration
claude_desktop_config.json
{"mcpServers": {"discord-notifications": {"command": "python", "args": ["/path/to/mcp-discord-notify/main.py"], "env": {"DISCORD_BOT_TOKEN": "your_bot_token", "DISCORD_GUILD_ID": "your_guild_id"}}}}Try it
→List all available channels in my Discord server to see where I can send updates.
→Send a notification to the 'alerts' channel saying that the deployment process has finished successfully.
→Create a new Discord channel named 'project-alpha' and save it as a key for future use.
→Post a multiple-choice question in the 'general' channel asking the team to vote on the next feature to prioritize.
→Ask the team a yes/no question in the 'alerts' channel about whether they are ready for the upcoming maintenance.