{"id":51150257,"url":"https://github.com/zebbern/discord-mcp-agent","last_synced_at":"2026-06-26T05:30:49.165Z","repository":{"id":343342150,"uuid":"1142769428","full_name":"zebbern/discord-mcp-agent","owner":"zebbern","description":"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.","archived":false,"fork":false,"pushed_at":"2026-01-26T20:47:05.000Z","size":12,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T20:09:12.334Z","etag":null,"topics":["agent-communication","agent-development-kit","agent-framework","agent-memory","agent-orchestration","agent-skills","discord","discord-agent","discord-api","discord-bot","discord-communication","discord-connect","discord-mcp","discord-py","discord-user-api","discord-userbot","discordbot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zebbern.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-26T20:45:37.000Z","updated_at":"2026-05-03T08:19:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zebbern/discord-mcp-agent","commit_stats":null,"previous_names":["zebbern/discord-mcp-agent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zebbern/discord-mcp-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zebbern%2Fdiscord-mcp-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zebbern%2Fdiscord-mcp-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zebbern%2Fdiscord-mcp-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zebbern%2Fdiscord-mcp-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zebbern","download_url":"https://codeload.github.com/zebbern/discord-mcp-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zebbern%2Fdiscord-mcp-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34805072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-communication","agent-development-kit","agent-framework","agent-memory","agent-orchestration","agent-skills","discord","discord-agent","discord-api","discord-bot","discord-communication","discord-connect","discord-mcp","discord-py","discord-user-api","discord-userbot","discordbot"],"created_at":"2026-06-26T05:30:48.209Z","updated_at":"2026-06-26T05:30:49.149Z","avatar_url":"https://github.com/zebbern.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Discord MCP Agent\n\n[![PyPI](https://img.shields.io/pypi/v/discord-mcp-agent)](https://pypi.org/project/discord-mcp-agent/)\n[![Python](https://img.shields.io/pypi/pyversions/discord-mcp-agent)](https://www.python.org/)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nA 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.\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Discord Bot Setup](#discord-bot-setup)\n- [Tools Reference](#tools-reference)\n- [Reaction Features](#reaction-features)\n- [Configuration](#configuration)\n- [Usage Examples](#usage-examples)\n- [Troubleshooting](#troubleshooting)\n- [Requirements](#requirements)\n- [Contributing](#contributing)\n- [Links](#links)\n\n## Quick Start\n\n### Installation\n\n```bash\n# Using uvx (recommended - no install needed)\nuvx discord-mcp-agent\n\n# Or install via pip\npip install discord-mcp-agent\n\n# For screenshot support\npip install discord-mcp-agent[screenshot]\n```\n\n### VS Code / GitHub Copilot\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"discord\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"discord-mcp-agent\"],\n      \"env\": {\n        \"DISCORD_TOKEN\": \"your-bot-token\",\n        \"DISCORD_GUILD_ID\": \"your-server-id\",\n        \"DISCORD_CHANNEL\": \"general\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"discord\": {\n      \"command\": \"uvx\",\n      \"args\": [\"discord-mcp-agent\"],\n      \"env\": {\n        \"DISCORD_TOKEN\": \"your-bot-token\",\n        \"DISCORD_GUILD_ID\": \"your-server-id\",\n        \"DISCORD_CHANNEL\": \"general\"\n      }\n    }\n  }\n}\n```\n\n## Discord Bot Setup\n\n1. Go to [Discord Developer Portal](https://discord.com/developers/applications)\n2. Click **New Application** → Give it a name → Create\n3. Go to **Bot** section → Click **Add Bot**\n4. Copy the **Bot Token** (keep this secret!)\n5. Enable under **Privileged Gateway Intents**:\n   - ✅ Message Content Intent\n6. Go to **OAuth2** → **URL Generator**:\n   - Scopes: `bot`\n   - Bot Permissions: `Send Messages`, `Read Message History`, `Add Reactions`, `Attach Files`\n7. Copy the generated URL and open it to invite the bot to your server\n8. Get your **Server ID**: Enable Developer Mode in Discord settings, right-click your server → Copy ID\n\n\u003e ⚠️ **Security Warning:** Never commit your bot token to version control! Use environment variables or `.env` files.\n\n## Tools Reference\n\n### `discord_ask`\n\nSend a question and wait for user response. Supports reaction-based interactions.\n\n| Parameter  | Type   | Required | Description              |\n| ---------- | ------ | -------- | ------------------------ |\n| `question` | string | ✅       | The question to ask user |\n\n**Reactions automatically added:**\n\n- 📷 Take screenshot\n- ❌ Cancel request\n\n**Response format:**\n\n```json\n{\n  \"text\": \"User's response text\",\n  \"attachments\": [{ \"filename\": \"...\", \"url\": \"...\" }],\n  \"cancelled\": false\n}\n```\n\n### `discord_notify`\n\nSend a notification (no response expected).\n\n| Parameter | Type   | Required | Description         |\n| --------- | ------ | -------- | ------------------- |\n| `message` | string | ✅       | The message to send |\n\n### `discord_send_file`\n\nSend a file to the user.\n\n| Parameter   | Type   | Required | Description                    |\n| ----------- | ------ | -------- | ------------------------------ |\n| `file_path` | string | ✅       | Absolute path to the file      |\n| `message`   | string | ❌       | Optional message with the file |\n\n### `discord_screenshot`\n\nTake and send a desktop screenshot.\n\n| Parameter | Type   | Required | Description                          |\n| --------- | ------ | -------- | ------------------------------------ |\n| `message` | string | ❌       | Optional message with the screenshot |\n\n\u003e Requires `pip install discord-mcp-agent[screenshot]`\n\n### `discord_embed`\n\nSend a rich embed message with full formatting.\n\n| Parameter       | Type    | Required | Description                              |\n| --------------- | ------- | -------- | ---------------------------------------- |\n| `title`         | string  | ❌       | Embed title                              |\n| `description`   | string  | ❌       | Main content                             |\n| `color`         | integer | ❌       | Hex color (default: `0x5865F2`)          |\n| `fields`        | array   | ❌       | Array of `{name, value, inline}` objects |\n| `footer`        | string  | ❌       | Footer text                              |\n| `thumbnail_url` | string  | ❌       | Small image (top-right)                  |\n| `image_url`     | string  | ❌       | Large image (bottom)                     |\n| `author_name`   | string  | ❌       | Author name (top)                        |\n| `url`           | string  | ❌       | Title link URL                           |\n\n## Reaction Features\n\nEvery message from the bot includes interactive reaction buttons:\n\n| Emoji | Action     | Description                                           |\n| ----- | ---------- | ----------------------------------------------------- |\n| 📷    | Screenshot | Takes a screenshot and sends it to Discord            |\n| ❌    | Cancel     | Cancels the current `discord_ask` and returns control |\n| ⏳    | Timeout    | Added automatically when a request times out          |\n\n### How It Works\n\n1. Bot sends a message with 📷 and ❌ reactions\n2. User can click reactions to trigger actions\n3. 📷 immediately captures and sends a screenshot\n4. ❌ cancels waiting and returns `\"cancelled\": true`\n\n## Configuration\n\n### Environment Variables\n\n| Variable                     | Required | Default   | Description                           |\n| ---------------------------- | -------- | --------- | ------------------------------------- |\n| `DISCORD_TOKEN`              | ✅       | -         | Your Discord bot token                |\n| `DISCORD_GUILD_ID`           | ✅       | -         | Your Discord server ID                |\n| `DISCORD_CHANNEL`            | ❌       | `general` | Channel name to use                   |\n| `DISCORD_REMINDER`           | ❌       | -         | Custom text appended to all responses |\n| `DISCORD_ASK_TIMEOUT`        | ❌       | `300`     | Seconds to wait for user response     |\n| `DISCORD_HTTP_TIMEOUT`       | ❌       | `30`      | Seconds for HTTP operations           |\n| `DISCORD_CONNECTION_TIMEOUT` | ❌       | `30`      | Seconds to establish connection       |\n\n### Custom Reminder\n\nInject custom instructions into every tool response:\n\n```json\n{\n  \"env\": {\n    \"DISCORD_REMINDER\": \"Remember: Always confirm with the user before completing tasks.\"\n  }\n}\n```\n\n### Timeout Configuration\n\nAdjust timeouts for your use case:\n\n```json\n{\n  \"env\": {\n    \"DISCORD_ASK_TIMEOUT\": \"600\",\n    \"DISCORD_HTTP_TIMEOUT\": \"60\"\n  }\n}\n```\n\n## Usage Examples\n\n### MCP Tool Call: Ask Question\n\n```json\n{\n  \"name\": \"discord_ask\",\n  \"arguments\": {\n    \"question\": \"What color theme would you like for the dashboard?\"\n  }\n}\n```\n\n**Response:**\n\n```json\n{\n  \"text\": \"I'd prefer a dark theme with blue accents\",\n  \"attachments\": [],\n  \"cancelled\": false\n}\n```\n\n### MCP Tool Call: Send Embed\n\n```json\n{\n  \"name\": \"discord_embed\",\n  \"arguments\": {\n    \"title\": \"Build Complete ✅\",\n    \"description\": \"Your project has been successfully built.\",\n    \"color\": 5763719,\n    \"fields\": [\n      { \"name\": \"Duration\", \"value\": \"2m 34s\", \"inline\": true },\n      { \"name\": \"Size\", \"value\": \"1.2 MB\", \"inline\": true }\n    ],\n    \"footer\": \"Built with discord-mcp-agent\"\n  }\n}\n```\n\n### Handling Image Attachments\n\nWhen users send images in response to `discord_ask`, they're automatically:\n\n1. Downloaded from Discord\n2. Encoded as base64\n3. Returned as `ImageContent` for AI model consumption\n\n## Troubleshooting\n\n| Error                                            | Cause                  | Solution                                            |\n| ------------------------------------------------ | ---------------------- | --------------------------------------------------- |\n| `DISCORD_TOKEN environment variable is required` | Missing token          | Set `DISCORD_TOKEN` in your MCP config              |\n| `Guild with ID X not found`                      | Bot not in server      | Invite bot using OAuth2 URL                         |\n| `Channel 'X' not found in guild`                 | Wrong channel name     | Check `DISCORD_CHANNEL` matches exactly             |\n| `Failed to connect within 30 seconds`            | Network/token issue    | Verify token and network connectivity               |\n| `PIL not installed`                              | Screenshot dep missing | Run `pip install discord-mcp-agent[screenshot]`     |\n| `⏳ No response received within X seconds`       | User didn't respond    | Increase `DISCORD_ASK_TIMEOUT` or user can click ❌ |\n\n### Common Issues\n\n**Bot appears offline:**\n\n- Ensure `Message Content Intent` is enabled in Discord Developer Portal\n- Check that the bot token is correct\n\n**Bot can't see messages:**\n\n- Enable `Message Content Intent` in bot settings\n- Ensure bot has `Read Message History` permission\n\n**Screenshots not working:**\n\n- Install Pillow: `pip install discord-mcp-agent[screenshot]`\n- On Linux, may require display server access\n\n## Requirements\n\n- Python 3.10+\n- `mcp \u003e= 1.0.0`\n- `discord.py \u003e= 2.0.0`\n- `pydantic \u003e= 2.0.0`\n- `aiohttp \u003e= 3.8.0`\n- `Pillow \u003e= 10.0.0` (optional, for screenshots)\n\n## Security\n\n⚠️ **Never commit your Discord bot token to version control!**\n\n- Use environment variables or `.env` files\n- Add `.env` to `.gitignore`\n- Regenerate token immediately if exposed\n\n## Contributing\n\nContributions are welcome!\n\n1. Fork the repository\n2. Create your feature branch\n3. Add tests for new features\n4. Submit a pull request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/zebbern/discord-mcp-agent.git\ncd discord-mcp-agent\npip install -e \".[dev]\"\npytest tests/ -v\n```\n\n## Links\n\n- 📦 [PyPI Package](https://pypi.org/project/discord-mcp-agent/)\n- 🐙 [GitHub Repository](https://github.com/zebbern/discord-mcp-agent)\n- 📖 [Model Context Protocol](https://modelcontextprotocol.io/)\n- 🎮 [Discord Developer Portal](https://discord.com/developers/applications)\n\n---\n\nMade with ❤️ for the MCP community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzebbern%2Fdiscord-mcp-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzebbern%2Fdiscord-mcp-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzebbern%2Fdiscord-mcp-agent/lists"}