https://github.com/kstonekuan/discord-notification-mcp
Simple MCP server to send you notifications on discord
https://github.com/kstonekuan/discord-notification-mcp
claude-code cloudflare-agents discord mcp typescript
Last synced: 2 months ago
JSON representation
Simple MCP server to send you notifications on discord
- Host: GitHub
- URL: https://github.com/kstonekuan/discord-notification-mcp
- Owner: kstonekuan
- License: mit
- Created: 2025-06-02T13:42:21.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-06-03T00:30:33.000Z (5 months ago)
- Last Synced: 2025-06-03T02:45:13.849Z (5 months ago)
- Topics: claude-code, cloudflare-agents, discord, mcp, typescript
- Language: TypeScript
- Homepage:
- Size: 1.92 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **discord-notification-mcp** - Simple MCP server to send you notifications on discord `typescript` `claude-code` `cloudflare-agents` `discord` `mcp` `npm install kstonekuan/discord-notification-mcp` (💬 Communication)
- awesome-mcp-servers - **discord-notification-mcp** - Simple MCP server to send you notifications on discord `typescript` `claude-code` `cloudflare-agents` `discord` `mcp` `npm install kstonekuan/discord-notification-mcp` (Communication)
README
# Discord Notification MCP Server
An MCP (Model Context Protocol) server that sends notifications to Discord when Claude Code completes tasks. Built with TypeScript using the Cloudflare Agents SDK and deployable on Cloudflare Workers.
## Features
- 🤖 **MCP Tool**: Provides a `send_discord_message` tool for sending notifications
- 🚀 **Cloudflare Workers**: Runs serverless with global distribution
- 🔐 **Secure**: Uses Cloudflare secrets for credentials
- 🌐 **Dual Transport**: Supports both SSE and Streamable HTTP for maximum compatibility
- 💾 **Durable Objects**: State management required by McpAgent
- 💬 **Rich Formatting**: Supports embeds, TTS messages, and mention controls
## Architecture
This server implements the MCP specification using Cloudflare's Agents SDK:
- **GET /sse**: SSE endpoint for MCP communication
- **POST /mcp**: Streamable HTTP endpoint for MCP communication
- Built with TypeScript, MCP SDK, and Cloudflare Agents SDK
- Proper JSON-RPC 2.0 error handling
- Durable Objects for stateful connections (required by McpAgent)
- Node.js compatibility mode enabled
## Setup
### Prerequisites
1. **Discord Webhook**: Create a webhook in your Discord channel:
- Right-click on the channel → Edit Channel → Integrations → Webhooks
- Click "New Webhook" and copy the webhook URL
2. **Cloudflare Account**: Sign up at [cloudflare.com](https://cloudflare.com)
### Installation
1. Clone this repository
2. Install dependencies:
```bash
pnpm install
```
### Configuration
1. Create a `.dev.vars` file from the example:
```bash
cp .dev.vars.example .dev.vars
```
Then edit `.dev.vars` with your webhook URL. This file is used for both local development and deployment.
2. For production deployment, set up Cloudflare secrets:
```bash
npx wrangler secret put WEBHOOK_URL
```
3. Update `wrangler.toml` with your worker name if desired
### Deployment
Deploy to Cloudflare Workers:
```bash
# First set secrets
npx wrangler secret put WEBHOOK_URL
# Then deploy
pnpm run deploy
```
**Alternative: Continuous Deployment**
You can also set up continuous deployment directly from the Cloudflare dashboard.
Learn more about [Git Integration with Cloudflare](https://developers.cloudflare.com/pages/configuration/git-integration/)
### Claude Code Configuration
Add the MCP server to Claude Code using the CLI via SSE transport:
```bash
# For production deployment (SSE)
claude mcp add discord-notify https://your-worker-name.workers.dev/sse -t sse
# For local development
claude mcp add discord-notify http://localhost:8787/sse -t sse
```
**Note**: This server supports both SSE (Server-Sent Events) and Streamable HTTP transport. While SSE works well, Streamable HTTP provides better reliability and is the newer standard.
You can verify the configuration with:
```bash
claude mcp list
```
## Usage
Once configured, Claude Code can send notifications to your Discord whenever you need them.
### Available Tool
**send_discord_message**: Send a notification message to Discord
- `content` (required): The message content to send
- `tts` (optional): Send as Text-to-Speech message
- `embeds` (optional): Array of embed objects for rich formatting
- `allowed_mentions` (optional): Control which mentions are parsed
Example usage:
```javascript
// Simple message
await send_discord_message({ content: "Task completed!" })
// Rich embed message
await send_discord_message({
content: "Status Update",
embeds: [{
title: "Build Results",
description: "All tests passed",
color: 5025616, // Green
fields: [
{ name: "Tests", value: "52/52", inline: true },
{ name: "Duration", value: "2m 34s", inline: true }
]
}]
})
```
### When You'll Get Notifications
Claude Code sends notifications when:
- You explicitly ask: "notify me when done" or "let me know on Discord"
- Errors occur during execution
- Important milestones are reached
- User input or intervention is needed
### Example Scenarios
```bash
# You say: "Deploy to production and notify me when done"
# Result: 🤖 Claude Code Notification
# Deployment completed successfully! The app is now live.
# You say: "Run all tests and let me know the results"
# Result: 🤖 Claude Code Notification
# All tests passed! 52/52 tests successful.
# You say: "Process this data and notify me if there are any errors"
# Result: 🤖 Claude Code Notification
# Error: Failed to process row 451 - invalid date format
```
### Example Notifications
Example of Discord notifications from Claude Code
Claude Code sending notifications during task completion
### CLAUDE.md Examples
To encourage Claude Code to use Discord notifications effectively, add these to your CLAUDE.md:
```markdown
# Discord Notifications
Use the mcp__discord-notify__send_discord_message tool to send notifications to Discord.
- Always send a Discord notification when:
- A task is fully complete
- You need user input to continue
- An error occurs that requires user attention
- The user explicitly asks for a notification (e.g., "notify me", "send me a message", "let me know")
- Include relevant details in notifications:
- For builds/tests: success/failure status and counts
- For errors: the specific error message and file location
- Use concise, informative messages like:
- "✅ Build completed successfully (2m 34s)"
- "❌ Tests failed: 3/52 failing in auth.test.ts"
- "⚠️ Need permission to modify /etc/hosts"
```
## Development
Run locally:
```bash
# Start local development server
pnpm dev
```
For local development, Wrangler will automatically load environment variables from your `.dev.vars` file.
Run all checks before deployment:
```bash
pnpm build
```
This command runs:
1. `pnpm format` - Format code with Biome
2. `pnpm lint:fix` - Fix linting issues
3. `pnpm cf-typegen` - Generate Cloudflare types
4. `pnpm type-check` - Check TypeScript types
Test the server:
```bash
# Test SSE connection
curl http://localhost:8787/sse
# Test health endpoint
curl http://localhost:8787/
```
## Debugging
### Testing the SSE Connection
You can test the SSE endpoint directly:
```bash
curl -N http://localhost:8787/sse
```
This should return an event stream starting with an `endpoint` event.
### Common Issues
1. **Connection closes immediately**: Check that your worker is running and accessible at the specified URL.
2. **No endpoint event received**: Ensure the SSE headers are being sent correctly and the stream is properly formatted.
3. **Discord notifications not sent**: Verify your `WEBHOOK_URL` is correctly set in the worker environment.
## Technical Details
- **Language**: TypeScript (ES2021 target)
- **Runtime**: Cloudflare Workers with Node.js compatibility
- **Protocol**: MCP (Model Context Protocol)
- **Transport**: SSE and Streamable HTTP
- **State Management**: Durable Objects (required by McpAgent)
- **Observability**: Enabled for monitoring
## References
This project was built following these guides:
- [Build a Remote MCP server - Cloudflare Agents](https://developers.cloudflare.com/agents/guides/remote-mcp-server/)
- [Model Context Protocol (MCP) - Cloudflare Agents](https://developers.cloudflare.com/agents/model-context-protocol/)
- [MCP Transport Methods - Cloudflare Agents](https://developers.cloudflare.com/agents/model-context-protocol/transport/)
- [Cloudflare MCP Template (remote-mcp-authless)](https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-authless)
## Related Projects
- [Telegram Notification MCP](https://github.com/kstonekuan/telegram-notification-mcp) - Send notifications to Telegram instead of Discord
## License
MIT