Skip to main content
Glama

MCP Sendmail Server

by maxyychen
GitHub
Python
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP Sendmail Server

A Model Context Protocol (MCP) server with Streamable HTTP transport for sending emails via SMTP.

Features

  • ✅ MCP Streamable HTTP - Full MCP specification compliance (2024-11-05)

  • ✅ Stateful Sessions - Session management with automatic cleanup

  • ✅ Bidirectional Communication - SSE for server-to-client messaging

  • ✅ Stream Resumability - Reconnect and resume from last event

  • ✅ Email Tools - Send emails, bulk emails, and template-based emails

  • ✅ SMTP Support - Full SMTP/TLS support with authentication

  • ✅ Attachments - Support for email attachments (base64 encoded)

  • ✅ Docker Ready - Multi-stage build, production-optimized

  • ✅ Type Safe - Full Python type hints and Pydantic models

  • ✅ Async Support - FastAPI async/await patterns

  • ✅ Backward Compatible - Legacy JSON-RPC 2.0 endpoints still work

Configuration

SMTP credentials are configured via environment variables. The repository includes .env.sh for easy configuration:

# Source SMTP settings source .env.sh # Your settings are now available: # SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD

Quick Start

Option 1: Local Development

# Create virtual environment python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Load SMTP settings from .env.sh source .env.sh # Run server uvicorn src.server:app --reload --port 8080

Option 2: Docker

# Build and run with Docker docker build -t mcp-sendmail-server:latest . docker run -d -p 8080:8080 \ -e SMTP_HOST="smtp.gmail.com" \ -e SMTP_PORT="587" \ -e SMTP_USER="your-email@gmail.com" \ -e SMTP_PASSWORD="your-password" \ -v $(pwd)/logs:/app/logs \ --name mcp-sendmail \ mcp-sendmail-server:latest

Option 3: Docker Compose (Recommended)

Quick Start with Convenience Scripts

# Start the server (automatically loads .env.sh) ./start.sh # View logs docker compose logs -f # Stop the server ./stop.sh

Manual Start

Configure your SMTP credentials using .env.sh:

# 1. Edit .env.sh with your SMTP credentials (already configured in this repo) nano .env.sh # Example .env.sh contents: export SMTP_HOST="mail.example.com" export SMTP_PORT="25" export SMTP_USER="test@example.com" export SMTP_PASSWORD="your-password" # 2. Source the environment variables source .env.sh # 3. Start services (will use variables from .env.sh) docker compose up -d # View logs docker compose logs -f # Stop services docker compose down

Important: Always run source .env.sh before docker compose up to load the SMTP configuration, or use the ./start.sh script which does this automatically.

How it works: The docker-compose.yml reads environment variables from your shell using ${SMTP_HOST} syntax. If variables aren't set, it falls back to safe defaults (localhost:587).

Environment Variables

Variable

Description

Default

SMTP_HOST

SMTP server hostname

localhost

SMTP_PORT

SMTP server port

587

SMTP_USER

SMTP username/email

``

SMTP_PASSWORD

SMTP password

``

Testing the Server

MCP Streamable HTTP (Recommended)

# Check health curl http://localhost:8080/health # Initialize MCP session (note the /mcp endpoint) curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "curl-client", "version": "1.0"} } }' # Save the Mcp-Session-Id from response headers! # Example: Mcp-Session-Id: 318a19a9-b757-4c0b-9ddb-a8dc1b40d240 # List available tools curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: YOUR_SESSION_ID_HERE" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }' # Verify SMTP connection curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: YOUR_SESSION_ID_HERE" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "verify_connection", "arguments": {} } }' # Send an email curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: YOUR_SESSION_ID_HERE" \ -d '{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "send_email", "arguments": { "to": "recipient@example.com", "subject": "Test Email", "body": "This is a test email sent via MCP Sendmail Server" } } }' # Send an HTML email curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: YOUR_SESSION_ID_HERE" \ -d '{ "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "send_email", "arguments": { "to": "recipient@example.com", "subject": "HTML Test Email", "body": "<h1>Hello</h1><p>This is an <strong>HTML</strong> email!</p>", "html": true } } }' # Send bulk emails curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: YOUR_SESSION_ID_HERE" \ -d '{ "jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": { "name": "send_bulk_email", "arguments": { "recipients": ["user1@example.com", "user2@example.com", "user3@example.com"], "subject": "Bulk Email", "body": "This email was sent to multiple recipients" } } }' # Send template email curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Mcp-Session-Id: YOUR_SESSION_ID_HERE" \ -d '{ "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "send_template_email", "arguments": { "to": "recipient@example.com", "subject": "Welcome {name}!", "template": "Hello {name},\n\nWelcome to {company}!\n\nYour account is: {account}", "variables": { "name": "John Doe", "company": "Acme Corp", "account": "john.doe@acme.com" } } } }'

Available MCP Tools

1. send_email

Send an email with optional attachments, CC, and BCC.

Parameters:

  • to (string, required): Recipient email address

  • subject (string, required): Email subject

  • body (string, required): Email body content

  • from_addr (string, optional): Sender email address (defaults to SMTP_USER)

  • cc (array, optional): List of CC recipients

  • bcc (array, optional): List of BCC recipients

  • html (boolean, optional): Whether body is HTML (default: false)

  • attachments (array, optional): List of attachments with filename and base64 content

Example:

{ "to": "recipient@example.com", "subject": "Meeting Tomorrow", "body": "Hi, let's meet tomorrow at 10 AM.", "cc": ["manager@example.com"], "html": false }

2. send_bulk_email

Send the same email to multiple recipients.

Parameters:

  • recipients (array, required): List of recipient email addresses

  • subject (string, required): Email subject

  • body (string, required): Email body content

  • from_addr (string, optional): Sender email address (defaults to SMTP_USER)

  • html (boolean, optional): Whether body is HTML (default: false)

Example:

{ "recipients": ["user1@example.com", "user2@example.com", "user3@example.com"], "subject": "System Maintenance Notice", "body": "The system will be down for maintenance on Saturday." }

3. send_template_email

Send an email using a template with variable substitution.

Parameters:

  • to (string, required): Recipient email address

  • subject (string, required): Email subject

  • template (string, required): Email template with {variable} placeholders

  • variables (object, required): Dictionary of variable names and values

  • from_addr (string, optional): Sender email address (defaults to SMTP_USER)

  • html (boolean, optional): Whether template is HTML (default: false)

Example:

{ "to": "customer@example.com", "subject": "Order Confirmation", "template": "Dear {customer_name},\n\nYour order #{order_id} has been confirmed.\n\nTotal: ${total}", "variables": { "customer_name": "Jane Smith", "order_id": "12345", "total": "99.99" } }

4. verify_connection

Verify SMTP connection and credentials.

Parameters: None

Returns: Connection status, server details, and port information

API Endpoints

MCP Streamable HTTP (Primary)

Method

Endpoint

Description

POST

/mcp

MCP requests with session management

GET

/mcp

Open SSE stream for server notifications

GET

/health

Health check

Required Headers:

  • Mcp-Session-Id: Session ID (after initialize)

  • Mcp-Protocol-Version: 2024-11-05

  • Accept: application/json, text/event-stream

Legacy Endpoints (Backward Compatible)

Method

Endpoint

Description

POST

/

,

/rpc

,

/jsonrpc

Plain JSON-RPC 2.0 (no sessions)

GET

/sse

Legacy SSE (deprecated)

JSON-RPC Methods

Method

Description

initialize

Initialize MCP session (returns session ID)

ping

Keep-alive ping

tools/list

List available tools

tools/call

Execute a tool

Project Structure

mcp-mail/ ├── src/ │ ├── server.py # FastAPI server with tool registration │ ├── mcp_handler.py # MCP protocol implementation │ ├── mcp_transport.py # MCP transport layer │ ├── mcp_session.py # Session management │ ├── email/ │ │ ├── __init__.py │ │ └── email_operations.py # Email sending via SMTP │ ├── jsonrpc/ │ │ ├── __init__.py │ │ ├── handler.py # JSON-RPC handler │ │ └── models.py # JSON-RPC models │ └── utils/ │ ├── errors.py # Custom exceptions │ ├── validation.py # Input validation │ └── security.py # Security utilities ├── tests/ # Test suite ├── logs/ # Application logs ├── Dockerfile # Docker image definition ├── docker-compose.yml # Docker Compose setup └── requirements.txt # Python dependencies

SMTP Configuration Examples

Gmail

export SMTP_HOST="smtp.gmail.com" export SMTP_PORT="587" export SMTP_USER="your-email@gmail.com" export SMTP_PASSWORD="your-app-password" # Use App Password, not regular password

Outlook/Office 365

export SMTP_HOST="smtp.office365.com" export SMTP_PORT="587" export SMTP_USER="your-email@outlook.com" export SMTP_PASSWORD="your-password"

SendGrid

export SMTP_HOST="smtp.sendgrid.net" export SMTP_PORT="587" export SMTP_USER="apikey" export SMTP_PASSWORD="your-sendgrid-api-key"

Mailgun

export SMTP_HOST="smtp.mailgun.org" export SMTP_PORT="587" export SMTP_USER="postmaster@your-domain.mailgun.org" export SMTP_PASSWORD="your-mailgun-smtp-password"

Amazon SES

export SMTP_HOST="email-smtp.us-east-1.amazonaws.com" export SMTP_PORT="587" export SMTP_USER="your-ses-smtp-username" export SMTP_PASSWORD="your-ses-smtp-password"

Security Features

  • TLS Encryption: All SMTP connections use TLS by default

  • Secure Credentials: SMTP credentials stored in environment variables

  • Input Validation: Email addresses and content validated

  • Non-root User: Docker runs as mcpuser (UID 1000)

Development

# Install dev dependencies pip install -r requirements.txt # Run tests pytest tests/ -v # Type checking mypy src/ # Linting ruff check src/ # Code formatting black src/

Docker Image Details

  • Base Image: python:3.11-slim

  • Size: ~150-200MB (optimized with multi-stage build)

  • User: Non-root mcpuser

  • Health Checks: Built-in

  • Volumes: /app/logs (logs)

Troubleshooting

Gmail Authentication Issues

If you're using Gmail, you need to:

  1. Enable 2-factor authentication

  2. Generate an App Password (not your regular password)

  3. Use the App Password in SMTP_PASSWORD

Connection Timeouts

If you get connection timeouts:

  1. Check your firewall settings

  2. Verify the SMTP host and port

  3. Try port 465 (SSL) instead of 587 (TLS)

  4. Use the verify_connection tool to test

Certificate Errors

If you get SSL certificate errors:

  1. Make sure you're using a valid SMTP server

  2. Check if your network has SSL inspection enabled

  3. Verify the server's certificate is valid

License

MIT License

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Commit your changes

  4. Push to the branch

  5. Create a Pull Request

Support

For issues and questions, please open an issue on GitHub.

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables sending emails via SMTP with support for HTML content, attachments, bulk sending, and template-based emails. Features session management and full MCP Streamable HTTP transport compliance.

  1. Features
    1. Configuration
      1. Quick Start
        1. Option 1: Local Development
        2. Option 2: Docker
        3. Option 3: Docker Compose (Recommended)
      2. Environment Variables
        1. Testing the Server
          1. MCP Streamable HTTP (Recommended)
        2. Available MCP Tools
          1. 1. send_email
          2. 2. send_bulk_email
          3. 3. send_template_email
          4. 4. verify_connection
        3. API Endpoints
          1. MCP Streamable HTTP (Primary)
          2. Legacy Endpoints (Backward Compatible)
          3. JSON-RPC Methods
        4. Project Structure
          1. SMTP Configuration Examples
            1. Gmail
            2. Outlook/Office 365
            3. SendGrid
            4. Mailgun
            5. Amazon SES
          2. Security Features
            1. Development
              1. Docker Image Details
                1. Troubleshooting
                  1. Gmail Authentication Issues
                  2. Connection Timeouts
                  3. Certificate Errors
                2. License
                  1. Contributing
                    1. Support

                      New MCP Servers

                      MCP directory API

                      We provide all the information about MCP servers via our MCP API.

                      curl -X GET 'https://glama.ai/api/mcp/v1/servers/maxyychen/mcp-sendmail'

                      If you have feedback or need assistance with the MCP directory API, please join our Discord server