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