✉️ 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)
• Verified sender email address in SendGrid
• Docker (optional, for containerized deployment)

🛠️ Installation

Option 1: Local Python Setup

1. Clone or navigate to the repository:

   cd d:\repos\mcp_mail
   

2. Create and activate virtual environment:

   python -m venv venv
   .\venv\Scripts\activate  # Windows
   

3. Install dependencies:

   pip install -e .
   

4. Configure environment variables:

   copy .env.example .env
   

   Edit .env and add your credentials:

   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:

   copy .env.example .env
   # Edit .env with your credentials
   

2. Build and run with Docker Compose:

   docker-compose up -d
   

   Or build manually:

   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

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:

python server.py

Docker:

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:

{
  "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:

{
  "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:

{
  "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):

{
  "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:

{
  "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 for detailed instructions.

Python Client Example

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:

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
• Model Context Protocol
• FastMCP Framework

📄 License

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

🤝 Contributing

Contributions welcome! Feel free to submit issues or pull requests.