<div align="center">
  <h1>Discord Webhook MCP</h1>
  <p>Model Context Protocol server for Discord Webhooks</p>
</div>

<p align="center">
  <img src="https://img.shields.io/badge/Node.js-18%2B-green?style=for-the-badge&logo=node.js&logoColor=white">
  <img src="https://img.shields.io/badge/TypeScript-5.x-blue?style=for-the-badge&logo=typescript&logoColor=white">
  <img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge">
  <img src="https://img.shields.io/badge/MCP-1.0-purple?style=for-the-badge">
</p>

<div align="center">
  <h2>Overview</h2>
</div>

<div align="center">

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.

</div>

<div align="center">
  <h2>Core Features</h2>
</div>

<div align="center">
<table>
  <tr>
    <th>Feature</th>
    <th>Description</th>
    <th>Use Case</th>
  </tr>
  <tr>
    <td>Simple Messages</td>
    <td>Send plain text messages up to 2000 characters</td>
    <td>Quick notifications, status updates</td>
  </tr>
  <tr>
    <td>Rich Embeds</td>
    <td>Beautiful formatted messages with titles, descriptions, colors, images</td>
    <td>Structured data, announcements, alerts</td>
  </tr>
  <tr>
    <td>Custom Fields</td>
    <td>Add up to 25 name-value pairs with inline or block layout</td>
    <td>Data tables, metrics, lists</td>
  </tr>
  <tr>
    <td>Images & Thumbnails</td>
    <td>Attach images and thumbnails to embeds</td>
    <td>Visual content, branding</td>
  </tr>
  <tr>
    <td>Timestamps</td>
    <td>Automatic or custom timestamps on embeds</td>
    <td>Event tracking, logs</td>
  </tr>
  <tr>
    <td>Customization</td>
    <td>Override webhook username and avatar per message</td>
    <td>Multi-bot appearance, personalization</td>
  </tr>
  <tr>
    <td>Validation</td>
    <td>Comprehensive input validation and error handling</td>
    <td>Reliability, debugging</td>
  </tr>
</table>
</div>

<div align="center">
  <h2>MCP Tools</h2>
</div>

<div align="center">

The server exposes three tools through the Model Context Protocol interface.

</div>

<div align="center">
<table>
  <tr>
    <th>Tool</th>
    <th>Description</th>
    <th>Required Parameters</th>
  </tr>
  <tr>
    <td><code>send_message</code></td>
    <td>Send a simple text message to Discord</td>
    <td>content</td>
  </tr>
  <tr>
    <td><code>send_embed</code></td>
    <td>Send a rich embed with title, description, colors, images, and more</td>
    <td>None (at least one embed field required)</td>
  </tr>
  <tr>
    <td><code>send_embed_with_fields</code></td>
    <td>Send an embed with custom fields for structured data display</td>
    <td>fields</td>
  </tr>
</table>
</div>

<div align="center">
  <h2>Tool Parameters</h2>
</div>

<div align="center">

**send_message**

</div>

<div align="center">
<table>
  <tr>
    <th>Parameter</th>
    <th>Type</th>
    <th>Required</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>content</td>
    <td>string</td>
    <td>Yes</td>
    <td>Message content (max 2000 characters)</td>
  </tr>
  <tr>
    <td>username</td>
    <td>string</td>
    <td>No</td>
    <td>Override webhook username</td>
  </tr>
  <tr>
    <td>avatar_url</td>
    <td>string</td>
    <td>No</td>
    <td>Override webhook avatar URL</td>
  </tr>
</table>
</div>

<div align="center">

**send_embed**

</div>

<div align="center">
<table>
  <tr>
    <th>Parameter</th>
    <th>Type</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>content</td>
    <td>string</td>
    <td>Optional message content above the embed</td>
  </tr>
  <tr>
    <td>title</td>
    <td>string</td>
    <td>Embed title (max 256 characters)</td>
  </tr>
  <tr>
    <td>description</td>
    <td>string</td>
    <td>Embed description (max 4096 characters)</td>
  </tr>
  <tr>
    <td>url</td>
    <td>string</td>
    <td>URL that the title will link to</td>
  </tr>
  <tr>
    <td>color</td>
    <td>string</td>
    <td>Color as hex (#FF0000), named (red, blue, green, yellow, orange, purple, pink, blurple), or decimal</td>
  </tr>
  <tr>
    <td>timestamp</td>
    <td>boolean</td>
    <td>Add current timestamp to embed</td>
  </tr>
  <tr>
    <td>footer_text</td>
    <td>string</td>
    <td>Footer text (max 2048 characters)</td>
  </tr>
  <tr>
    <td>footer_icon</td>
    <td>string</td>
    <td>Footer icon URL</td>
  </tr>
  <tr>
    <td>image_url</td>
    <td>string</td>
    <td>Large image URL displayed in embed</td>
  </tr>
  <tr>
    <td>thumbnail_url</td>
    <td>string</td>
    <td>Small thumbnail URL (top right)</td>
  </tr>
  <tr>
    <td>author_name</td>
    <td>string</td>
    <td>Author name (max 256 characters)</td>
  </tr>
  <tr>
    <td>author_url</td>
    <td>string</td>
    <td>Author URL (makes name clickable)</td>
  </tr>
  <tr>
    <td>author_icon</td>
    <td>string</td>
    <td>Author icon URL</td>
  </tr>
  <tr>
    <td>username</td>
    <td>string</td>
    <td>Override webhook username</td>
  </tr>
  <tr>
    <td>avatar_url</td>
    <td>string</td>
    <td>Override webhook avatar URL</td>
  </tr>
</table>
</div>

<div align="center">

**send_embed_with_fields**

</div>

<div align="center">
<table>
  <tr>
    <th>Parameter</th>
    <th>Type</th>
    <th>Required</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>fields</td>
    <td>array</td>
    <td>Yes</td>
    <td>Array of field objects (max 25 fields)</td>
  </tr>
  <tr>
    <td colspan="4"><em>Each field object contains:</em></td>
  </tr>
  <tr>
    <td>- name</td>
    <td>string</td>
    <td>Yes</td>
    <td>Field name (max 256 characters)</td>
  </tr>
  <tr>
    <td>- value</td>
    <td>string</td>
    <td>Yes</td>
    <td>Field value (max 1024 characters)</td>
  </tr>
  <tr>
    <td>- inline</td>
    <td>boolean</td>
    <td>No</td>
    <td>Display inline (default: false)</td>
  </tr>
  <tr>
    <td colspan="4"><em>All send_embed parameters are also supported</em></td>
  </tr>
</table>
</div>

<div align="center">
  <h2>Embed Colors</h2>
</div>

<div align="center">
<table>
  <tr>
    <th>Format</th>
    <th>Example</th>
    <th>Result</th>
  </tr>
  <tr>
    <td>Hex</td>
    <td>#FF0000</td>
    <td>Red</td>
  </tr>
  <tr>
    <td>Named</td>
    <td>red, blue, green, yellow, orange, purple, pink, blurple, white, black, gray</td>
    <td>Predefined colors</td>
  </tr>
  <tr>
    <td>Decimal</td>
    <td>16711680</td>
    <td>Red</td>
  </tr>
</table>
</div>

<div align="center">
  <h2>Discord Limits</h2>
</div>

<div align="center">
<table>
  <tr>
    <th>Item</th>
    <th>Maximum</th>
  </tr>
  <tr>
    <td>Message content</td>
    <td>2000 characters</td>
  </tr>
  <tr>
    <td>Embed title</td>
    <td>256 characters</td>
  </tr>
  <tr>
    <td>Embed description</td>
    <td>4096 characters</td>
  </tr>
  <tr>
    <td>Field name</td>
    <td>256 characters</td>
  </tr>
  <tr>
    <td>Field value</td>
    <td>1024 characters</td>
  </tr>
  <tr>
    <td>Footer text</td>
    <td>2048 characters</td>
  </tr>
  <tr>
    <td>Author name</td>
    <td>256 characters</td>
  </tr>
  <tr>
    <td>Fields per embed</td>
    <td>25 fields</td>
  </tr>
  <tr>
    <td>Total embed characters</td>
    <td>6000 characters</td>
  </tr>
  <tr>
    <td>Embeds per message</td>
    <td>10 embeds</td>
  </tr>
  <tr>
    <td>Webhook rate limit</td>
    <td>30 requests/minute</td>
  </tr>
</table>
</div>

<div align="center">
  <h2>Installation</h2>
</div>

<div align="center">
<table>
  <tr>
    <th>Step</th>
    <th>Instructions</th>
  </tr>
  <tr>
    <td><strong>Prerequisites</strong></td>
    <td>
      Node.js 18.0.0 or higher<br>
      A Discord webhook URL
    </td>
  </tr>
  <tr>
    <td><strong>Getting Webhook URL</strong></td>
    <td>
      1. Open your Discord server<br>
      2. Go to Server Settings → Integrations → Webhooks<br>
      3. Click "New Webhook" or select an existing one<br>
      4. Copy the webhook URL<br>
      5. The URL format should be: <code>https://discord.com/api/webhooks/{id}/{token}</code>
    </td>
  </tr>
  <tr>
    <td><strong>Install Dependencies</strong></td>
    <td><code>npm install</code></td>
  </tr>
  <tr>
    <td><strong>Configure Environment</strong></td>
    <td>
      Create a <code>.env</code> file in the project root:<br>
      <code>DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN</code>
    </td>
  </tr>
  <tr>
    <td><strong>Build the Project</strong></td>
    <td><code>npm run build</code></td>
  </tr>
</table>
</div>

<div align="center">
  <h2>Configuration</h2>
</div>

<div align="center">

**Claude Desktop**

</div>

Add to your `claude_desktop_config.json`:

```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"
      }
    }
  }
}
```

<div align="center">

**Other MCP Clients**

</div>

The server runs on stdio transport and can be used with any MCP-compatible client. Ensure the `DISCORD_WEBHOOK_URL` environment variable is set.

<div align="center">
  <h2>Development</h2>
</div>

<div align="center">

**Project Structure**

</div>

<div align="center">
<table>
  <tr>
    <th>Directory</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>src/discord/</td>
    <td>Discord API integration (webhook client, embed builder, types)</td>
  </tr>
  <tr>
    <td>src/tools/</td>
    <td>MCP tool implementations (send-message, send-embed, send-embed-fields)</td>
  </tr>
  <tr>
    <td>src/utils/</td>
    <td>Utility functions (environment validation, custom errors)</td>
  </tr>
  <tr>
    <td>src/index.ts</td>
    <td>Main MCP server entry point</td>
  </tr>
  <tr>
    <td>tests/</td>
    <td>Comprehensive test suite with 80%+ coverage</td>
  </tr>
</table>
</div>

<div align="center">

**Development Commands**

</div>

<div align="center">
<table>
  <tr>
    <th>Command</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>npm install</code></td>
    <td>Install dependencies</td>
  </tr>
  <tr>
    <td><code>npm run dev</code></td>
    <td>Run in development mode</td>
  </tr>
  <tr>
    <td><code>npm run watch</code></td>
    <td>Watch for changes</td>
  </tr>
  <tr>
    <td><code>npm run build</code></td>
    <td>Build for production</td>
  </tr>
  <tr>
    <td><code>npm test</code></td>
    <td>Run tests</td>
  </tr>
  <tr>
    <td><code>npm run test:watch</code></td>
    <td>Run tests in watch mode</td>
  </tr>
  <tr>
    <td><code>npm run test:coverage</code></td>
    <td>Generate coverage report</td>
  </tr>
  <tr>
    <td><code>npm run typecheck</code></td>
    <td>Type check</td>
  </tr>
  <tr>
    <td><code>npm run lint</code></td>
    <td>Lint code</td>
  </tr>
  <tr>
    <td><code>npm run lint:fix</code></td>
    <td>Fix lint issues</td>
  </tr>
</table>
</div>