MCP Sendmail Server

You will run an MCP Sendmail Server that exposes a Streamable HTTP transport to send emails via SMTP. It provides session-managed MCP interactions, server-sent events for updates, and robust SMTP support with template, bulk, and attachment capabilities tailored for email workflows.

How to use

You interact with the MCP Sendmail Server through a client that speaks the MCP Streamable HTTP protocol. Start a session, list available tools, verify your SMTP connection, and then issue commands to send emails, bulk emails, or template-based emails. Use server-sent events (SSE) for ongoing notifications and resume sessions if you reconnect after a drop.

Typical usage flow in practice is: initialize a session, fetch the list of available tools, verify the SMTP connection, and then perform email operations. You can send standard emails, HTML emails, or bulk messages. When using templates, provide variables to substitute into the template content. Attachments are supported via base64 encoding within email payloads.

How to install

Prerequisites you need before installing:

• Python 3.11 or newer
• Docker (optional but recommended for containerized runs)
• Docker Compose (optional for multi-container setups)
• A valid SMTP account (host, port, user, password)
• Internet access to install dependencies and reach the SMTP service

# Option A: Local development with Python and Uvicorn
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Load SMTP settings from environment (example)
export SMTP_HOST="smtp.example.com"
export SMTP_PORT="587"
export SMTP_USER="user@example.com"
export SMTP_PASSWORD="your-password"

# Run the server
uvicorn src.server:app --reload --port 8080

Option B: Docker (production-oriented) Start with a container image for easy deployment and isolation. Use Docker to build and run the server with the same SMTP environment variables.

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

Additional configuration notes

SMTP credentials are provided via environment variables. You can source a configuration script or pass them directly into the runtime command. A health endpoint is available to confirm the service is running, and the MCP endpoint is located at /mcp for interactive sessions.

Testing the server

Begin by checking the health endpoint, then initialize an MCP session, list tools, verify the SMTP connection, and perform email operations. Ensure your SMTP settings are loaded into the environment before tests.

# Health check
curl http://localhost:8080/health

# Initialize MCP session (example flow)
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "cli-client", "version": "1.0"}}}'

Security and reliability notes

All SMTP connections use TLS by default. Credentials live in environment variables only and should be protected. Input validation helps prevent malformed emails or invalid recipient addresses. The server runs as a non-root user in containerized environments for safer operation.

Available tools

initialize

Initialize an MCP session and establish a session context for subsequent MCP calls.

tools/list

List available MCP tools that you can call for email operations.

tools/call

Execute a specific tool such as send_email, send_bulk_email, or verify_connection.

verify_connection

Test the SMTP connection and credentials to ensure the server can reach the SMTP host.

send_email

Send a single email with optional attachments, CC, and BCC.

send_bulk_email

Send the same email to multiple recipients in a single operation.

send_template_email

Send an email using a template with variable substitutions.