# ✉️ 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.