Discord MCP Server

A Model Context Protocol (MCP) server for Discord integration via webhooks - TypeScript Edition.

Features

• Send Messages: Post messages to Discord channels via webhooks

• Release Announcements: Send beautifully formatted release announcements with rich embeds

• Teaser Announcements: Send "coming soon" style teasers for upcoming releases

• Webhook Management: Add, remove, and list webhook configurations

• Secure Storage: Webhook URLs stored locally with partial URL display for security

• Type Safe: Built with TypeScript and Zod validation for runtime safety

Technology Stack

• Runtime: Bun (fast JavaScript runtime with native TypeScript support)

• MCP SDK: @modelcontextprotocol/sdk (official TypeScript implementation)

• HTTP Client: axios for Discord webhook API calls

• Validation: Zod for runtime type validation

• Language: TypeScript with strict mode enabled

Installation

Prerequisites

• Bun 1.0+ or Node.js 20+ (Bun recommended for best performance)

• Discord server with webhook access

Using Bun (Recommended)

# Clone the repository
git clone https://github.com/MoshPitCodes/mcp-server-discord.git ~/.opencode/mcp-servers/mcp-discord
cd ~/.opencode/mcp-servers/mcp-discord

# Install dependencies
bun install

# Build the server
bun run build

Using Node.js

cd ~/.opencode/mcp-servers/mcp-discord
npm install
npm run build

NixOS with Flakes

# Enter development environment (automatically installs dependencies)
nix develop

Configuration

1. Add to OpenCode

Add to your OpenCode configuration:

For Bun users:

opencode mcp add discord --scope user -- bun ~/.opencode/mcp-servers/mcp-discord/src/index.ts

For Node.js users:

opencode mcp add discord --scope user -- node ~/.opencode/mcp-servers/mcp-discord/dist/index.js

Or manually add to ~/.opencode.json:

{
  "mcpServers": {
    "discord": {
      "command": "bun",
      "args": ["~/.opencode/mcp-servers/mcp-discord/src/index.ts"]
    }
  }
}

2. Verify Connection

opencode mcp list
# Should show: discord: ... - ✓ Connected

3. Configure Webhooks

To get your Discord webhook URL:

1. Go to your Discord server

2. Server Settings → Integrations → Webhooks

3. Click New Webhook

4. Choose a name and channel

5. Copy Webhook URL

6. Use the discord_add_webhook tool in OpenCode to add it

Environment Variables (Optional)

• DISCORD_MCP_CONFIG_DIR: Custom directory for webhook configurations (default: ~/.config/discord_mcp)

Usage

Simply ask OpenCode in natural language! The MCP server tools will be invoked automatically.

Send a Simple Message

Send "Hello from OpenCode!" to the releases webhook

Send a Release Announcement

Send a release announcement for v2.6.0-beta with:
- Headline: The Claims Module is here!
- Changes: Land claiming system, Trust management, Map visualization
- Beta warning: yes
- Download link: https://curseforge.com/...

The announcement will be formatted as a rich Discord embed with:

• Colored sidebar (green for release, yellow for beta, red for hotfix)

• Version title with emoji

• Feature highlights

• Download link

• Automatic Living Lands logo thumbnail

• Donation section

Send a Teaser

Send a teaser for v3.0.0 with:
- Headline: A Complete Rewrite
- Highlights: New architecture, Better performance, Modern UI

Tools

discord_send_message

Send a plain text message to a Discord channel.

Parameters:

• webhookName (required): Name of configured webhook

• content (required): Message content (max 2000 chars)

• username (optional): Override webhook username

• avatarUrl (optional): Override webhook avatar

• responseFormat (optional): markdown or json

discord_send_announcement

Send a formatted release announcement with rich Discord embeds.

Parameters:

• webhookName (required): Name of configured webhook

• version (required): Version number (e.g., "v2.6.0-beta")

• headline (required): Main announcement headline (max 256 chars)

• changes (required): Array of changes/features (1-10 items)

• downloadUrl (optional): Download/info URL

• style (optional): release (green) / hotfix (red) / beta (yellow) / custom (blue)

• betaWarning (optional): Include backup warning

• useEmbed (optional): Use rich embed format (default: true)

• embedColor (optional): Custom hex color (e.g., "#5865F2")

• thumbnailUrl (optional): Custom thumbnail URL (defaults to Living Lands logo)

• footerText (optional): Custom footer text

• username (optional): Override webhook display name

• responseFormat (optional): markdown or json

Embed Format:

• Colored sidebar based on style

• Version title with emoji (📦 release, 🧪 beta, 🚨 hotfix, 📢 custom)

• Headline as description

• "What's New" field with changes

• Optional warning field

• Download link field

• Living Lands logo thumbnail (automatic)

• Donation section (automatic)

• Timestamp footer

discord_send_teaser

Send a teaser/preview announcement for upcoming releases.

Parameters:

• webhookName (required): Name of configured webhook

• version (required): Version number

• headline (required): Teaser headline

• highlights (required): Array of features to highlight (1-10 items)

• additionalInfo (optional): Additional context (max 500 chars)

• style (optional): Teaser style (default: custom)

• thumbnailUrl (optional): Custom thumbnail URL

• footerText (optional): Custom footer text

• username (optional): Override webhook username

• responseFormat (optional): markdown or json

discord_add_webhook

Add or update a webhook configuration.

Parameters:

• name (required): Friendly name for the webhook

• url (required): Discord webhook URL

• description (optional): What this webhook is for

Note: Webhook names are automatically sanitized (lowercase, spaces replaced with underscores).

discord_remove_webhook

Remove a webhook configuration.

Parameters:

• name (required): Name of webhook to remove

discord_list_webhooks

List all configured webhooks (URLs partially hidden for security).

Parameters:

• responseFormat (optional): markdown or json

Development

Project Structure

mcp-discord/
├── src/
│   ├── index.ts                    # Server entry point & MCP setup
│   ├── constants.ts                # Global configuration constants
│   ├── types/
│   │   ├── enums.ts               # ResponseFormat, AnnouncementStyle
│   │   ├── schemas.ts             # Zod validation schemas
│   │   └── interfaces.ts          # TypeScript interfaces
│   ├── utils/
│   │   ├── storage.ts             # Webhook storage (JSON file I/O)
│   │   ├── webhook.ts             # Discord webhook HTTP operations
│   │   ├── embed.ts               # Discord embed builders
│   │   └── errors.ts              # Centralized error handling
│   └── tools/
│       ├── sendMessage.ts         # discord_send_message tool
│       ├── sendAnnouncement.ts    # discord_send_announcement tool
│       ├── sendTeaser.ts          # discord_send_teaser tool
│       ├── addWebhook.ts          # discord_add_webhook tool
│       ├── removeWebhook.ts       # discord_remove_webhook tool
│       └── listWebhooks.ts        # discord_list_webhooks tool
├── dist/                          # Compiled output (generated)
├── package.json                   # Project metadata & dependencies
├── tsconfig.json                  # TypeScript configuration
└── flake.nix                      # NixOS development environment

Scripts

# Development mode (watch & reload)
bun run dev

# Build for production
bun run build

# Run production build
bun run start

# Type check without building
bun run typecheck

Type Safety

The server uses strict TypeScript mode with Zod for runtime validation:

• All inputs are validated against Zod schemas

• Type inference from schemas ensures consistency

• No any types in the codebase

• Comprehensive error handling

Security

• Webhook URLs are stored locally in ~/.config/discord_mcp/webhooks.json

• Full URLs are never displayed in tool outputs (only last 8 characters shown)

• Keep your configuration file secure as webhook URLs allow posting to channels

• The webhooks.json file is gitignored by default

Performance

• Startup time: ~50ms

• Memory usage: ~30MB

• Type safety: Compile-time + runtime validation

• Bundle size: ~1.3MB (includes all dependencies)

Troubleshooting

Server won't start

# Check if dependencies are installed
bun install

# Verify TypeScript compilation
bun run typecheck

# Try rebuilding
bun run build

Webhook not found errors

# List configured webhooks
# (use discord_list_webhooks tool in OpenCode)

# Add a webhook
# (use discord_add_webhook tool in OpenCode)

Discord API errors

Common errors and solutions:

• 400 Bad Request: Message content exceeds 2000 characters or invalid format

• 401 Unauthorized: Webhook URL is invalid or expired

• 403 Forbidden: Webhook has been deleted from Discord

• 404 Not Found: Webhook URL is incorrect

• 429 Rate Limited: Too many requests, wait before retrying

License

MIT

Links

• Model Context Protocol Documentation

• Discord Webhook Documentation

• Bun Documentation

• Technical Design Document