Discord Webhook MCP
Model Context Protocol server for Discord Webhooks
Overview
Enables LLMs to send messages and rich embeds to Discord via webhooks. Built with TypeScript and the official MCP SDK, it provides a simple, type-safe interface for sending plain text messages, formatted embeds with images and fields, and customizing webhook appearance. Perfect for AI-powered Discord notifications, monitoring, and integrations.
Core Features
| Feature | Description | Use Case |
|---|---|---|
| Simple Messages | Send plain text messages up to 2000 characters | Quick notifications, status updates |
| Rich Embeds | Beautiful formatted messages with titles, descriptions, colors, images | Structured data, announcements, alerts |
| Custom Fields | Add up to 25 name-value pairs with inline or block layout | Data tables, metrics, lists |
| Images & Thumbnails | Attach images and thumbnails to embeds | Visual content, branding |
| Timestamps | Automatic or custom timestamps on embeds | Event tracking, logs |
| Customization | Override webhook username and avatar per message | Multi-bot appearance, personalization |
| Validation | Comprehensive input validation and error handling | Reliability, debugging |
MCP Tools
The server exposes three tools through the Model Context Protocol interface.
| Tool | Description | Required Parameters |
|---|---|---|
send_message | Send a simple text message to Discord | content |
send_embed | Send a rich embed with title, description, colors, images, and more | None (at least one embed field required) |
send_embed_with_fields | Send an embed with custom fields for structured data display | fields |
Tool Parameters
send_message
| Parameter | Type | Required | Description |
|---|---|---|---|
| content | string | Yes | Message content (max 2000 characters) |
| username | string | No | Override webhook username |
| avatar_url | string | No | Override webhook avatar URL |
send_embed
| Parameter | Type | Description |
|---|---|---|
| content | string | Optional message content above the embed |
| title | string | Embed title (max 256 characters) |
| description | string | Embed description (max 4096 characters) |
| url | string | URL that the title will link to |
| color | string | Color as hex (#FF0000), named (red, blue, green, yellow, orange, purple, pink, blurple), or decimal |
| timestamp | boolean | Add current timestamp to embed |
| footer_text | string | Footer text (max 2048 characters) |
| footer_icon | string | Footer icon URL |
| image_url | string | Large image URL displayed in embed |
| thumbnail_url | string | Small thumbnail URL (top right) |
| author_name | string | Author name (max 256 characters) |
| author_url | string | Author URL (makes name clickable) |
| author_icon | string | Author icon URL |
| username | string | Override webhook username |
| avatar_url | string | Override webhook avatar URL |
send_embed_with_fields
| Parameter | Type | Required | Description |
|---|---|---|---|
| fields | array | Yes | Array of field objects (max 25 fields) |
| Each field object contains: | |||
| - name | string | Yes | Field name (max 256 characters) |
| - value | string | Yes | Field value (max 1024 characters) |
| - inline | boolean | No | Display inline (default: false) |
| All send_embed parameters are also supported | |||
Embed Colors
| Format | Example | Result |
|---|---|---|
| Hex | #FF0000 | Red |
| Named | red, blue, green, yellow, orange, purple, pink, blurple, white, black, gray | Predefined colors |
| Decimal | 16711680 | Red |
Discord Limits
| Item | Maximum |
|---|---|
| Message content | 2000 characters |
| Embed title | 256 characters |
| Embed description | 4096 characters |
| Field name | 256 characters |
| Field value | 1024 characters |
| Footer text | 2048 characters |
| Author name | 256 characters |
| Fields per embed | 25 fields |
| Total embed characters | 6000 characters |
| Embeds per message | 10 embeds |
| Webhook rate limit | 30 requests/minute |
Installation
| Step | Instructions |
|---|---|
| Prerequisites |
Node.js 18.0.0 or higher A Discord webhook URL |
| Getting Webhook URL |
1. Open your Discord server 2. Go to Server Settings → Integrations → Webhooks 3. Click "New Webhook" or select an existing one 4. Copy the webhook URL 5. The URL format should be: https://discord.com/api/webhooks/{id}/{token}
|
| Install Dependencies | npm install |
| Configure Environment |
Create a .env file in the project root:DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
|
| Build the Project | npm run build |
Configuration
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"discord-webhook": {
"command": "node",
"args": ["/path/to/discord-webhook-mcp/dist/index.js"],
"env": {
"DISCORD_WEBHOOK_URL": "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
}
}
}
}
Other MCP Clients
The server runs on stdio transport and can be used with any MCP-compatible client. Ensure the DISCORD_WEBHOOK_URL environment variable is set.
Development
Project Structure
| Directory | Description |
|---|---|
| src/discord/ | Discord API integration (webhook client, embed builder, types) |
| src/tools/ | MCP tool implementations (send-message, send-embed, send-embed-fields) |
| src/utils/ | Utility functions (environment validation, custom errors) |
| src/index.ts | Main MCP server entry point |
| tests/ | Comprehensive test suite with 80%+ coverage |
Development Commands
| Command | Description |
|---|---|
npm install | Install dependencies |
npm run dev | Run in development mode |
npm run watch | Watch for changes |
npm run build | Build for production |
npm test | Run tests |
npm run test:watch | Run tests in watch mode |
npm run test:coverage | Generate coverage report |
npm run typecheck | Type check |
npm run lint | Lint code |
npm run lint:fix | Fix lint issues |