EasyWebhook-MCP Server

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

License

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 file support 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:

cd c:\Users\plgon\Downloads\EasyWebhook-MCP
copy .env.example .env
notepad .env

Add your webhooks:

DISCORD_WEBHOOK=https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN
SLACK_WEBHOOK=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
MY_CUSTOM_API=https://api.example.com/webhook

2. Build Docker image:

docker build -t easywebhook-mcp-server .

3. Configure Claude Desktop:

# Copy catalog
copy custom.yaml $env:USERPROFILE\.docker\mcp\catalogs\custom.yaml

# Update registry
notepad $env:USERPROFILE\.docker\mcp\registry.yaml

Add to registry under registry::

  easywebhook:
    ref: ""

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

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "C:\\Users\\plgon\\.docker\\mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

4. Restart Claude Desktop

💡 Usage Examples

Using Stored Webhooks (Recommended)

List configured webhooks:

You: "List my webhooks"

Claude: 📋 Stored Webhooks:
  • DISCORD_WEBHOOK: https://discord.com/api/webh...
  • SLACK_WEBHOOK: https://hooks.slack.com/serv...
  • MY_CUSTOM_HOOK: https://example.com/webhook...

Simple Discord message:

You: "Send Discord message using DISCORD_WEBHOOK saying 'Hello World!'"

Claude: ✅ Discord embed sent successfully!

Discord with title and color:

You: "Send to DISCORD_WEBHOOK with title 'Deployment Status' message 'All systems operational' and color 00FF00"

Claude: ✅ Discord embed sent successfully!
📌 Title: Deployment Status

Discord with full embed (JSON):

You: "Send to DISCORD_WEBHOOK: {'title': 'Server Metrics', 'description': 'Current status', 'color': 3447003, 'fields': [{'name': 'CPU', 'value': '45%', 'inline': true}, {'name': 'RAM', 'value': '62%', 'inline': true}]}"

Claude: ✅ Discord embed sent successfully!

Slack message:

You: "Send to SLACK_WEBHOOK: 'Deployment complete'"

Claude: ✅ Slack message sent successfully!

Custom webhook:

You: "Use MY_CUSTOM_HOOK to send {\"status\": \"active\", \"uptime\": 3600}"

Claude: ✅ Webhook sent successfully!
📊 Status: 200

Using Direct URLs

Generic webhook:

You: "Send POST webhook to https://example.com/hook with payload {\"test\": true}"

Claude: ✅ Webhook sent successfully!

Discord with URL:

You: "Send Discord webhook to [URL] with message 'Alert!' and color FF0000"

Claude: ✅ Discord embed sent successfully!

Payload Formats

Simple text:

{"message": "Hello World"}

JSON payload:

{"title": "Alert", "status": "active", "priority": 1}

Custom headers:

{"Authorization": "Bearer token123", "X-Custom-Header": "value"}

Or comma-separated:

"Authorization: Bearer token123, X-Custom-Header: value"

📐 Architecture

Claude Desktop → MCP Gateway → EasyWebhook MCP Server → Target Webhook URL
                                         ↓
                                .env file (local)
                                         ↓
                            Discord/Slack/Custom API

📚 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:

❌ Copy/paste long URLs every time
❌ Risk of typos
❌ Hard to manage multiple webhooks

After:

✅ Simple aliases like "DISCORD_WEBHOOK"
✅ Store once, use everywhere
✅ Easy to update and manage
✅ More secure (URLs in local file)

🔧 Updating Webhooks

Edit .env file
Rebuild: docker build -t easywebhook-mcp-server .
Restart Claude Desktop

🔧 Development

Local Testing

# Run server directly
python easywebhook_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python easywebhook_server.py

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 SETUP_GUIDE.md

📁 Project Structure

EasyWebhook-MCP/
├── .env.example              # Webhook configuration template
├── .env                      # Your webhooks (create this)
├── .gitignore                # Git ignore rules (protects .env)
├── easywebhook_server.py     # Main MCP server
├── requirements.txt          # Python dependencies
├── Dockerfile                # Docker configuration
├── custom.yaml               # MCP catalog definition
├── README.md                 # This file (complete documentation)
├── QUICK_START.md           # Fast setup guide
├── SETUP_GUIDE.md           # Detailed instructions
├── VISUAL_GUIDE.txt         # Visual walkthrough
├── CHANGELOG.md             # Version history
└── CLAUDE.md                # Implementation guide

🤝 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

Fork and clone the repository

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

Create a .env file for testing

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

Make your changes
- Follow existing code style
- Use single-line docstrings for MCP tools
- Add error handling for new features
- Test thoroughly before submitting

Test your changes

# Build Docker image
docker build -t easywebhook-mcp-server .

# Test locally
python easywebhook_server.py

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:

Add the function to easywebhook_server.py

@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!"

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

Update custom.yaml

tools:
  - name: send_my_service_webhook

Update documentation
- Add usage examples to README.md
- Update SETUP_GUIDE.md if needed
- Update CHANGELOG.md

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

⚙️ 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! 🚀