# ✉️ MCP Email Server with SendGrid
A Model Context Protocol (MCP) server that provides email sending capabilities through SendGrid. This server enables AI applications like Claude Desktop, Langflow, and other MCP clients to send emails programmatically.
## 🚀 Features
- **📧 Basic Email Sending** - Send text or HTML emails
- **🎨 Template Support** - Use SendGrid dynamic templates
- **📎 File Attachments** - Attach files to emails
- **👥 CC/BCC Support** - Send copies to multiple recipients
- **🐳 Docker Ready** - Containerized deployment
- **🔒 Secure** - Environment-based configuration
## 📋 Prerequisites
- Python 3.10 or higher
- SendGrid account and API key ([Sign up here](https://signup.sendgrid.com/))
- Verified sender email address in SendGrid
- Docker (optional, for containerized deployment)
## 🛠️ Installation
### Option 1: Local Python Setup
1. **Clone or navigate to the repository:**
```bash
cd d:\repos\mcp_mail
```
2. **Create and activate virtual environment:**
```bash
python -m venv venv
.\venv\Scripts\activate # Windows
```
3. **Install dependencies:**
```bash
pip install -e .
```
4. **Configure environment variables:**
```bash
copy .env.example .env
```
Edit `.env` and add your credentials:
```env
SENDGRID_API_KEY=your_actual_sendgrid_api_key
DEFAULT_FROM_EMAIL=your-verified-email@example.com
DEFAULT_FROM_NAME=Your Name
```
### Option 2: Docker Deployment
1. **Configure environment:**
```bash
copy .env.example .env
# Edit .env with your credentials
```
2. **Build and run with Docker Compose:**
```bash
docker-compose up -d
```
Or build manually:
```bash
docker build -t mcp-email-server .
docker run --env-file .env mcp-email-server
```
## 🔧 Configuration
### SendGrid Setup
1. **Create a SendGrid account** at [sendgrid.com](https://sendgrid.com)
2. **Generate an API key:**
- Go to Settings → API Keys
- Click "Create API Key"
- Select "Full Access" or "Restricted Access" with Mail Send permissions
- Copy the API key (you'll only see it once!)
3. **Verify sender email:**
- Go to Settings → Sender Authentication
- Verify the email address you'll use as the sender
- This is required by SendGrid to prevent spam
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `SENDGRID_API_KEY` | Yes | Your SendGrid API key |
| `DEFAULT_FROM_EMAIL` | Yes | Default sender email (must be verified in SendGrid) |
| `DEFAULT_FROM_NAME` | No | Default sender name displayed to recipients |
## 📖 Usage
### Running the Server
**Local:**
```bash
python server.py
```
**Docker:**
```bash
docker-compose up
```
The server communicates via stdio (standard input/output) using the MCP protocol.
### Available MCP Tools
#### 1. `send_email`
Send a basic email with text or HTML content.
**Parameters:**
- `to_email` (required): Recipient email address
- `subject` (required): Email subject line
- `body` (required): Email content (text or HTML)
- `from_email` (optional): Sender email (uses DEFAULT_FROM_EMAIL if not provided)
- `from_name` (optional): Sender name
- `cc_emails` (optional): List of CC recipients
- `bcc_emails` (optional): List of BCC recipients
- `is_html` (optional): Set to true for HTML emails (default: false)
**Example:**
```python
{
"to_email": "recipient@example.com",
"subject": "Hello from MCP",
"body": "<h1>Welcome!</h1><p>This is a test email.</p>",
"is_html": true
}
```
#### 2. `send_email_with_template`
Send an email using a SendGrid dynamic template.
**Parameters:**
- `to_email` (required): Recipient email address
- `template_id` (required): SendGrid template ID
- `dynamic_data` (required): Dictionary of template variables
- `from_email` (optional): Sender email
- `from_name` (optional): Sender name
- `subject` (optional): Override template subject
**Example:**
```python
{
"to_email": "user@example.com",
"template_id": "d-1234567890abcdef",
"dynamic_data": {
"username": "John",
"action_url": "https://example.com/verify"
}
}
```
#### 3. `send_email_with_attachments`
Send an email with file attachments.
**Parameters:**
- `to_email` (required): Recipient email address
- `subject` (required): Email subject line
- `body` (required): Email content
- `attachment_paths` (required): List of file paths to attach
- `from_email` (optional): Sender email
- `from_name` (optional): Sender name
- `is_html` (optional): HTML email flag
**Example:**
```python
{
"to_email": "recipient@example.com",
"subject": "Report Attached",
"body": "Please find the report attached.",
"attachment_paths": ["/path/to/report.pdf", "/path/to/data.csv"]
}
```
## 🔌 Integration Examples
### Claude Desktop
Add to your Claude Desktop config file (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"email": {
"command": "python",
"args": ["d:\\repos\\mcp_mail\\server.py"],
"env": {
"SENDGRID_API_KEY": "your_api_key",
"DEFAULT_FROM_EMAIL": "your-email@example.com",
"DEFAULT_FROM_NAME": "Your Name"
}
}
}
}
```
Or using Docker:
```json
{
"mcpServers": {
"email": {
"command": "docker",
"args": ["run", "-i", "--rm", "--env-file", "d:\\repos\\mcp_mail\\.env", "mcp-email-server"]
}
}
}
```
### Langflow Integration
1. Install an MCP client component in Langflow (if available) or use a custom Python component
2. Configure the MCP server connection with the email server's stdio transport
3. Call the email tools from your Langflow flows
See [examples/langflow_integration.md](examples/langflow_integration.md) for detailed instructions.
### Python Client Example
```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
server_params = StdioServerParameters(
command="python",
args=["d:/repos/mcp_mail/server.py"],
env={
"SENDGRID_API_KEY": "your_key",
"DEFAULT_FROM_EMAIL": "your@email.com"
}
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# Call the send_email tool
result = await session.call_tool("send_email", {
"to_email": "recipient@example.com",
"subject": "Test Email",
"body": "Hello from MCP!",
"is_html": False
})
print(result)
```
## 🧪 Testing
Run the test script to verify functionality:
```bash
python test_server.py
```
This will test the email sending functions with mocked SendGrid responses.
## 🐛 Troubleshooting
### "SendGrid client not initialized"
- Ensure `SENDGRID_API_KEY` is set in your `.env` file
- Verify the API key is valid and has Mail Send permissions
### "403 Forbidden" error
- Your sender email address must be verified in SendGrid
- Go to SendGrid Settings → Sender Authentication
### "No from_email provided"
- Set `DEFAULT_FROM_EMAIL` in your `.env` file, or
- Provide `from_email` parameter in each request
### Attachments not working
- Ensure the file paths are absolute and accessible
- Check file permissions
- Verify files exist at the specified paths
## 📚 Resources
- [SendGrid Documentation](https://docs.sendgrid.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)
## 📄 License
MIT License - feel free to use this in your projects!
## 🤝 Contributing
Contributions welcome! Feel free to submit issues or pull requests.
