# Email MCP Server Setup Guide
## Step-by-Step Setup
### 1. Server Deployment
#### Option A: Railway (Recommended)
1. Fork this repository to your GitHub account
2. Go to [Railway.app](https://railway.app) and sign in with GitHub
3. Click "New Project" → "Deploy from GitHub repo"
4. Select your forked repository
5. Set environment variables in Railway dashboard:
```
VALID_API_TOKENS=abc123,def456,ghi789
HOST=0.0.0.0
PORT=8000
```
6. Deploy and note your app URL (e.g., `https://email-mcp-abc123.railway.app`)
#### Option B: Render
1. Fork this repository
2. Go to [Render.com](https://render.com) and connect your GitHub
3. Create new "Web Service" from your repo
4. Set build command: `pip install -r requirements.txt`
5. Set start command: `python main.py`
6. Add environment variables in Render dashboard
7. Deploy and get your service URL
#### Option C: Local Development
```bash
git clone <your-fork>
cd email-mcp-server
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your tokens
python main.py
```
### 2. Get API Token
Your server needs API tokens defined in `VALID_API_TOKENS`. Generate secure tokens:
```bash
# Generate random tokens (example)
python -c "import secrets; print(','.join([secrets.token_urlsafe(32) for _ in range(3)]))"
```
Use one of these tokens for your Claude Desktop configuration.
### 3. Mailjet Account Setup
1. **Sign up**: Go to [Mailjet.com](https://mailjet.com)
2. **Free tier**: 6,000 emails/month, 200 emails/day
3. **Verify email**: Confirm your account email
4. **Get API keys**:
- Go to Account → API Keys
- Copy "API Key" and "Secret Key"
- Keep these secure - you'll enter them in Claude
### 4. Claude Desktop Configuration
#### Find your config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
#### Add configuration:
```json
{
"mcpServers": {
"email-sender": {
"transport": {
"type": "sse",
"url": "https://your-deployed-app.railway.app/sse?api_token=your-api-token-here"
}
}
}
}
```
#### Restart Claude Desktop
Close and reopen Claude Desktop application.
### 5. Test the Setup
Ask Claude:
> "Send a test email to yourself@example.com with subject 'Test' saying 'Hello from Claude!'"
Claude should:
1. Ask for your Mailjet API credentials
2. Send the email successfully
3. Confirm delivery
## Troubleshooting
### Server Issues
**Server won't start:**
- Check environment variables are set
- Verify port 8000 is available
- Check logs for import errors
**"Invalid API token":**
- Verify token in SSE URL matches `VALID_API_TOKENS`
- Check for extra spaces or special characters
- Regenerate tokens if needed
### Mailjet Issues
**"Invalid Mailjet credentials":**
- Double-check API Key and Secret Key
- Ensure Mailjet account is verified
- Try generating new API keys
**"Sender email not allowed":**
- Use an email address you own
- Add sender domain to Mailjet (for custom domains)
- Use your verified account email as sender
**Rate limiting:**
- Free tier: 200 emails/day
- Upgrade account if needed
- Space out email sending
### Claude Desktop Issues
**MCP server not connecting:**
- Check config file syntax (valid JSON)
- Ensure correct file path for your OS
- Restart Claude Desktop after config changes
- Check server is accessible at the URL
**Tool not appearing:**
- Wait 30 seconds after restart
- Check server logs for errors
- Try restarting Claude Desktop again
## Security Best Practices
1. **API Tokens**: Use long, random tokens (32+ characters)
2. **HTTPS**: Always use HTTPS URLs in production
3. **Environment Variables**: Never commit tokens to git
4. **Domain Verification**: Add your domain to Mailjet for better deliverability
5. **Rate Limiting**: Consider adding rate limits for production use
## Advanced Configuration
### Custom Domains (Optional)
1. Add domain to Mailjet
2. Configure SPF/DKIM records
3. Use custom domain in "from_email"
### Production Hardening
- Set specific CORS origins instead of "*"
- Add request rate limiting
- Use secure token storage
- Monitor email delivery rates
## Support
If you encounter issues:
1. Check server logs for error details
2. Verify all steps were completed
3. Test with simple email first
4. Check Mailjet delivery status in their dashboard
For questions, open an issue on GitHub with:
- Error messages
- Configuration (without sensitive data)
- Steps to reproduce the issue
