x-mahar/mail-mcpServer

Email MCP Server

A minimal, production-ready MCP (Model Context Protocol) server that enables Claude Desktop to send emails via Mailjet's API over Server-Sent Events (SSE).

🚀 Quick Start

1. Deploy the Server

Local Development:

# Clone and setup
git clone <your-repo>
cd email-mcp-server
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your API tokens

# Run server
python main.py
# Server runs on http://localhost:8000

Production Deploy (Railway/Render/Vercel):

1. Fork this repository
2. Connect to your hosting platform
3. Set environment variables:
   • VALID_API_TOKENS=your-secure-tokens-here
   • HOST=0.0.0.0
   • PORT=8000

2. Get Your API Token

Visit your deployed server at https://your-domain.com and get a valid API token from the VALID_API_TOKENS environment variable.

3. Configure Claude Desktop

Add this to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "email-sender": {
      "transport": {
        "type": "sse",
        "url": "https://your-domain.com/sse?api_token=your-api-token"
      }
    }
  }
}

4. Get Mailjet Credentials

1. Sign up at Mailjet.com (free tier available)
2. Go to Account Settings → API Keys
3. Copy your API Key and Secret Key

5. Send Emails with Claude

Now you can ask Claude to send emails:

"Send an email to john@example.com with the subject 'Meeting Follow-up' saying 'Thanks for the great discussion today. Let's schedule a follow-up for next week.'"

Claude will ask for your Mailjet credentials the first time.

🛡️ Security Features

• API Token Authentication: Each request requires a valid token
• User-Provided Credentials: Server never stores user email credentials
• Input Validation: Email format validation and error handling
• CORS Protection: Configurable origin restrictions

📡 API Endpoints

• GET / - Server status and information
• GET /sse?api_token=TOKEN - SSE endpoint for MCP protocol
• POST /mcp?api_token=TOKEN - Direct MCP message handling (debugging)

🔧 Environment Variables

HOST=0.0.0.0                    # Server host
PORT=8000                       # Server port
VALID_API_TOKENS=token1,token2  # Comma-separated valid tokens

📝 Usage Examples

Basic Email:

Send email to user@domain.com saying "Hello World"

With HTML:

Send a professional email to client@company.com with subject "Proposal" including both plain text and HTML formatting

Multiple Recipients (coming soon): Currently supports single emails only. Bulk email functionality planned for v2.

🚨 Troubleshooting

Common Issues:

1. "Invalid API token" - Check your token in the SSE URL
2. "Invalid Mailjet credentials" - Verify your API key and secret
3. "Invalid email format" - Ensure email addresses are properly formatted
4. Connection timeouts - Check your server deployment status

🏗️ Architecture

• FastAPI - Modern Python web framework
• SSE Transport - Real-time MCP protocol communication
• Mailjet API - Reliable email delivery service
• In-Memory Auth - Simple token validation (no database required)

📄 License

MIT License - feel free to use in your own projects!

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

For major changes, please open an issue first to discuss the proposed changes.