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

📖 Usage

Running the Server

Local:

Docker:

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:

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:

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:

🔌 Integration Examples

Claude Desktop

Add to your Claude Desktop config file (claude_desktop_config.json):

Or using Docker:

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

🧪 Testing

Run the test script to verify functionality:

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.