EasyWebhook-MCP Server

Send webhooks to any HTTP endpoint from Claude Desktop with .env file support!

Overview

EasyWebhook-MCP is a Model Context Protocol (MCP) server that enables Claude to send webhooks to Discord, Slack, or any custom HTTP endpoint. It provides a secure interface for AI assistants to send webhook requests to various services without requiring direct API access or file system permissions. Now with .env for easy webhook management!

✨ Features

🎯 Core Capabilities

• ✅ Send webhooks to any HTTP endpoint

• ✅ Support for GET, POST, PUT, PATCH, DELETE methods

• ✅ Custom headers and JSON payloads

• ✅ Discord embeds with title, color, and fields

• ✅ Slack integration for team notifications

• ✅ Store webhooks in .env file for easy management

• ✅ Reference webhooks by alias - no more copy/paste!

• ✅ Detailed response feedback with status codes

• ✅ Error handling with clear error messages

🔐 Security

• No file system access required

• Runs in isolated Docker container as non-root user

• Webhook URLs masked in list output

• 30-second timeout protection prevents hanging

• HTTPS recommended for all webhook URLs

• .env file protected by .gitignore

🛠️ Available Tools

Alias-Based Tools (use stored webhooks from .env):

• list_webhooks - List all configured webhook aliases

• send_webhook_by_alias - Send webhook using stored alias

• send_discord_webhook_by_alias - Discord embed by alias (supports title, color, username, avatar)

• send_slack_webhook_by_alias - Slack message by alias

Direct URL Tools (pass webhook URL each time):

• send_webhook - Universal webhook sender (GET, POST, PUT, PATCH, DELETE)

• send_discord_webhook - Discord embed with URL (supports title, color, username, avatar)

• send_slack_webhook - Slack message with URL

🚀 Quick Start

Prerequisites

• Docker Desktop with MCP Toolkit

• Claude Desktop app

Installation

1. Create .env file:

Add your webhooks:

2. Build Docker image:

3. Configure Claude Desktop:

Add to registry under registry::

Update Claude config at %APPDATA%\Claude\claude_desktop_config.json:

4. Restart Claude Desktop

💡 Usage Examples

Using Stored Webhooks (Recommended)

List configured webhooks:

Simple Discord message:

Discord with title and color:

Discord with full embed (JSON):

Slack message:

Custom webhook:

Using Direct URLs

Generic webhook:

Discord with URL:

Payload Formats

Simple text:

JSON payload:

Custom headers:

Or comma-separated:

📐 Architecture

📚 Documentation

• QUICK_START.md - 5-minute setup guide

• SETUP_GUIDE.md - Comprehensive setup instructions

• CLAUDE.md - Developer implementation guide

• CHANGELOG.md - Version history

• VISUAL_GUIDE.txt - Visual walkthrough

🎯 Why Use .env Files?

Before:

After:

🔧 Updating Webhooks

1. Edit .env file

2. Rebuild: docker build -t easywebhook-mcp-server .

3. Restart Claude Desktop

🔧 Development

Local Testing

Testing Webhooks

Discord Webhook:

Create a webhook in Discord: Server Settings → Integrations → Webhooks

Slack Webhook:

Create an app at api.slack.com/apps and enable Incoming Webhooks

Custom Webhook:

Any HTTP endpoint that accepts POST/GET/PUT/PATCH/DELETE requests

🐛 Troubleshooting

Tools Not Appearing

• Verify Docker image built successfully: docker images | grep easywebhook

• Check catalog and registry files for syntax errors

• Ensure Claude Desktop config includes custom catalog path

• Restart Claude Desktop completely (quit and reopen)

Webhook Failures

• Verify the webhook URL is correct and accessible

• Check that the webhook hasn't been deleted or revoked

• Ensure payload format matches the expected format for the service

• Review error messages for HTTP status codes

Timeout Errors

• Webhook endpoint may be slow or unavailable

• Check network connectivity

• Verify the target service is operational

"No webhook found for alias"

• Check .env file exists in project directory

• Verify alias name matches (case-insensitive)

• Rebuild Docker image: docker build -t easywebhook-mcp-server .

• Ensure the URL starts with http:// or https://

Invalid URL Errors

• Ensure URL includes http:// or https://

• Verify no typos in the webhook URL

• Check that the URL is properly formatted

Full troubleshooting guide in

📁 Project Structure

🤝 Contributing

Contributions are welcome! This is an open-source MCP server and we'd love your help making it better.

Ways to Contribute

• 🐛 Report bugs - Open an issue describing the problem

• 💡 Suggest features - Share ideas for new tools or improvements

• 📝 Improve documentation - Fix typos, clarify instructions, add examples

• 🔧 Submit code - Fix bugs, add features, improve performance

• ⭐ Star the repo - Show your support!

Development Setup

1. Fork and clone the repository

   git clone https://github.com/YOUR_USERNAME/EasyWebhook-MCP.git cd EasyWebhook-MCP

2. Create a

   cp .env.example .env # Add your test webhook URLs

3. Make your changes

   • Follow existing code style

   • Use single-line docstrings for MCP tools

   • Add error handling for new features

   • Test thoroughly before submitting

4. Test your changes

   # Build Docker image docker build -t easywebhook-mcp-server . # Test locally python easywebhook_server.py

5. Submit a pull request

   • Describe what your PR does

   • Reference any related issues

   • Include examples if adding new features

Adding New Tools

To add a new webhook tool:

1. Add the function to

   @mcp.tool() async def send_my_service_webhook(webhook_url: str = "", message: str = "") -> str: """Send a message to MyService using a webhook URL."" # Single-line only! # Implementation here return "✅ Message sent successfully!"

2. Use these guidelines:

   • Decorate with @mcp.tool()

   • Use single-line docstrings only (multi-line causes errors)

   • Use empty string defaults: param: str = "" not param: str = None

   • Return formatted strings with emojis (✅ ❌ ⚠️ 📊)

   • Add comprehensive error handling

   • Log actions to stderr

3. Update

   tools: - name: send_my_service_webhook

4. Update documentation

   • Add usage examples to README.md

   • Update SETUP_GUIDE.md if needed

   • Update CHANGELOG.md

5. Rebuild and test

   docker build -t easywebhook-mcp-server . # Test in Claude Desktop

Code Style Guidelines

• Python: Follow PEP 8, use async/await for HTTP operations

• Error messages: User-friendly with emoji indicators

• Logging: Use logger.info() and logger.error() for important events

• Security: Never log full webhook URLs, mask sensitive data

• Type hints: Use simple types (str, int), avoid Optional/Union

Testing Guidelines

Before submitting:

• ✅ Test all new tools with real webhook URLs

• ✅ Test error conditions (invalid URLs, timeouts, etc.)

• ✅ Verify changes work in Docker container

• ✅ Check that Claude Desktop recognizes new tools

• ✅ Ensure no secrets are hardcoded or logged

Documentation Guidelines

• Keep README.md concise and user-focused

• Add detailed examples for complex features

• Update CHANGELOG.md for all changes

• Use clear, friendly language

• Include emoji for visual clarity 🎨

Getting Help

• Questions? Open a discussion or issue

• Stuck? Check CLAUDE.md for implementation details

• Need examples? See existing tools in easywebhook_server.py

License

By contributing, you agree that your contributions will be licensed under the MIT License.

📄 License

MIT License - Use freely in your projects

🔗 Resources

• Model Context Protocol

• Docker MCP

• FastMCP

⚙️ Response Format

All tools return formatted strings with:

• ✅ Success indicators

• ❌ Error messages

• 📊 Status codes

• 🌐 URL information

• ⚡ Method used

• 📄 Response previews (first 200 chars)

⚠️ Limitations

• Maximum 30-second timeout per request

• Response body limited to 200 characters in output

• JSON payload format required for most structured data

• No support for file uploads via webhooks

🎉 What's New in v2.0

• ✨ .env file support for webhook storage

• 🔧 Four new alias-based tools

• 📋 list_webhooks tool to view configurations

• 🔒 Enhanced security with URL masking

• 🎨 Discord embeds with full customization (title, color, fields)

• 📚 Comprehensive documentation

Ready to send webhooks from Claude? Follow QUICK_START.md to get started in 5 minutes! 🚀