Discord MCP Agent

January 26, 2026 · View on GitHub

A Model Context Protocol (MCP) server for Discord-based AI agent-user communication. Enables AI agents to communicate with users through Discord instead of IDE chat interfaces.

Quick Start
Discord Bot Setup
Tools Reference
Reaction Features
Configuration
Usage Examples
Troubleshooting
Requirements
Contributing
Links

Quick Start

Installation

# Using uvx (recommended - no install needed)
uvx discord-mcp-agent

# Or install via pip
pip install discord-mcp-agent

# For screenshot support
pip install discord-mcp-agent[screenshot]

VS Code / GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "discord": {
      "type": "stdio",
      "command": "uvx",
      "args": ["discord-mcp-agent"],
      "env": {
        "DISCORD_TOKEN": "your-bot-token",
        "DISCORD_GUILD_ID": "your-server-id",
        "DISCORD_CHANNEL": "general"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "discord": {
      "command": "uvx",
      "args": ["discord-mcp-agent"],
      "env": {
        "DISCORD_TOKEN": "your-bot-token",
        "DISCORD_GUILD_ID": "your-server-id",
        "DISCORD_CHANNEL": "general"
      }
    }
  }
}

Discord Bot Setup

Go to Discord Developer Portal
Click New Application → Give it a name → Create
Go to Bot section → Click Add Bot
Copy the Bot Token (keep this secret!)
Enable under Privileged Gateway Intents:
- ✅ Message Content Intent
Go to OAuth2 → URL Generator:
- Scopes: bot
- Bot Permissions: Send Messages, Read Message History, Add Reactions, Attach Files
Copy the generated URL and open it to invite the bot to your server
Get your Server ID: Enable Developer Mode in Discord settings, right-click your server → Copy ID

⚠️ Security Warning: Never commit your bot token to version control! Use environment variables or .env files.

Tools Reference

`discord_ask`

Send a question and wait for user response. Supports reaction-based interactions.

Parameter	Type	Required	Description
`question`	string	✅	The question to ask user

Reactions automatically added:

📷 Take screenshot
❌ Cancel request

Response format:

{
  "text": "User's response text",
  "attachments": [{ "filename": "...", "url": "..." }],
  "cancelled": false
}

`discord_notify`

Send a notification (no response expected).

Parameter	Type	Required	Description
`message`	string	✅	The message to send

`discord_send_file`

Send a file to the user.

Parameter	Type	Required	Description
`file_path`	string	✅	Absolute path to the file
`message`	string	❌	Optional message with the file

`discord_screenshot`

Take and send a desktop screenshot.

Parameter	Type	Required	Description
`message`	string	❌	Optional message with the screenshot

Requires pip install discord-mcp-agent[screenshot]

`discord_embed`

Send a rich embed message with full formatting.

Parameter	Type	Required	Description
`title`	string	❌	Embed title
`description`	string	❌	Main content
`color`	integer	❌	Hex color (default: `0x5865F2`)
`fields`	array	❌	Array of `{name, value, inline}` objects
`footer`	string	❌	Footer text
`thumbnail_url`	string	❌	Small image (top-right)
`image_url`	string	❌	Large image (bottom)
`author_name`	string	❌	Author name (top)
`url`	string	❌	Title link URL

Reaction Features

Every message from the bot includes interactive reaction buttons:

Emoji	Action	Description
📷	Screenshot	Takes a screenshot and sends it to Discord
❌	Cancel	Cancels the current `discord_ask` and returns control
⏳	Timeout	Added automatically when a request times out

How It Works

Bot sends a message with 📷 and ❌ reactions
User can click reactions to trigger actions
📷 immediately captures and sends a screenshot
❌ cancels waiting and returns "cancelled": true

Configuration

Environment Variables

Variable	Required	Default	Description
`DISCORD_TOKEN`	✅	-	Your Discord bot token
`DISCORD_GUILD_ID`	✅	-	Your Discord server ID
`DISCORD_CHANNEL`	❌	`general`	Channel name to use
`DISCORD_REMINDER`	❌	-	Custom text appended to all responses
`DISCORD_ASK_TIMEOUT`	❌	`300`	Seconds to wait for user response
`DISCORD_HTTP_TIMEOUT`	❌	`30`	Seconds for HTTP operations
`DISCORD_CONNECTION_TIMEOUT`	❌	`30`	Seconds to establish connection

Custom Reminder

Inject custom instructions into every tool response:

{
  "env": {
    "DISCORD_REMINDER": "Remember: Always confirm with the user before completing tasks."
  }
}

Timeout Configuration

Adjust timeouts for your use case:

{
  "env": {
    "DISCORD_ASK_TIMEOUT": "600",
    "DISCORD_HTTP_TIMEOUT": "60"
  }
}

Usage Examples

MCP Tool Call: Ask Question

{
  "name": "discord_ask",
  "arguments": {
    "question": "What color theme would you like for the dashboard?"
  }
}

Response:

{
  "text": "I'd prefer a dark theme with blue accents",
  "attachments": [],
  "cancelled": false
}

MCP Tool Call: Send Embed

{
  "name": "discord_embed",
  "arguments": {
    "title": "Build Complete ✅",
    "description": "Your project has been successfully built.",
    "color": 5763719,
    "fields": [
      { "name": "Duration", "value": "2m 34s", "inline": true },
      { "name": "Size", "value": "1.2 MB", "inline": true }
    ],
    "footer": "Built with discord-mcp-agent"
  }
}

Handling Image Attachments

When users send images in response to discord_ask, they're automatically:

Downloaded from Discord
Encoded as base64
Returned as ImageContent for AI model consumption

Troubleshooting

Error	Cause	Solution
`DISCORD_TOKEN environment variable is required`	Missing token	Set `DISCORD_TOKEN` in your MCP config
`Guild with ID X not found`	Bot not in server	Invite bot using OAuth2 URL
`Channel 'X' not found in guild`	Wrong channel name	Check `DISCORD_CHANNEL` matches exactly
`Failed to connect within 30 seconds`	Network/token issue	Verify token and network connectivity
`PIL not installed`	Screenshot dep missing	Run `pip install discord-mcp-agent[screenshot]`
`⏳ No response received within X seconds`	User didn't respond	Increase `DISCORD_ASK_TIMEOUT` or user can click ❌

Common Issues

Bot appears offline:

Ensure Message Content Intent is enabled in Discord Developer Portal
Check that the bot token is correct

Bot can't see messages:

Enable Message Content Intent in bot settings
Ensure bot has Read Message History permission

Screenshots not working:

Install Pillow: pip install discord-mcp-agent[screenshot]
On Linux, may require display server access

Requirements

Python 3.10+
mcp >= 1.0.0
discord.py >= 2.0.0
pydantic >= 2.0.0
aiohttp >= 3.8.0
Pillow >= 10.0.0 (optional, for screenshots)

Security

⚠️ Never commit your Discord bot token to version control!

Use environment variables or .env files
Add .env to .gitignore
Regenerate token immediately if exposed

Contributing

Contributions are welcome!

Fork the repository
Create your feature branch
Add tests for new features
Submit a pull request

Development Setup

git clone https://github.com/zebbern/discord-mcp-agent.git
cd discord-mcp-agent
pip install -e ".[dev]"
pytest tests/ -v

Links

Made with ❤️ for the MCP community