MCP Sendmail Server

MCP发送邮件服务器

一种模型上下文协议（MCP）服务器 可流式HTTP传输 用于通过SMTP发送电子邮件。

特性

• ✅ MCP流式HTTP -完全符合MCP规范（2024-11-05）
• ✅ 有意义的会议 -具有自动清理功能的会话管理
• ✅ 双向通信 -SSE用于服务器到客户端的消息传递
• ✅ 流可恢复性 -重新连接并从上次事件恢复
• ✅ 电子邮件工具 -发送电子邮件、批量电子邮件和基于模板的电子邮件
• ✅ SMTP支持 -完全支持SMTP/TLS认证
• ✅ 附件 -支持电子邮件附件（base64编码）
• ✅ Docker就绪 -多阶段构建，生产优化
• ✅ 类型安全 -完整的Python类型提示和Pydantic模型
• ✅ 异步支持 -FastAPI异步/等待模式
• ✅ 向后兼容 -传统的JSON-RPC 2.0端点仍然有效

配置

SMTP凭据是通过环境变量配置的。存储库包括 .env.sh 为了便于配置：

# Source SMTP settings
source .env.sh

# Your settings are now available:
# SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD

快速开始

方案1：地方发展

# 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

选项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

选项3:Docker Compose（推荐）

使用便利脚本快速入门

# Start the server (automatically loads .env.sh)
./start.sh

# View logs
docker compose logs -f

# Stop the server
./stop.sh

手动启动

使用配置SMTP凭据 .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

重要提示： 始终运行 source .env.sh 之前 docker compose up 加载SMTP配置，或使用 ./start.sh 自动执行此操作的脚本。

它是如何工作的： docker-compose.yml使用以下命令从shell读取环境变量 ${SMTP_HOST} 语法。如果未设置变量，则返回到安全默认值（localhost:587）。

环境变量

测试服务器

MCP流式HTTP（推荐）

# 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": "
Hello

This is an HTML email!
",
        "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"
        }
      }
    }
  }'

可用的MCP工具

1. send_email

发送一封带有可选附件、抄送和密送的电子邮件。

参数：

• to （字符串，必填）：收件人电子邮件地址
• subject （字符串，必填）：电子邮件主题
• body （字符串，必填）：电子邮件正文内容
• from_addr （字符串，可选）：发件人电子邮件地址（默认为SMTP_USER）
• cc （数组，可选）：抄送收件人列表
• bcc （数组，可选）：BCC收件人列表
• html （boolean，可选）：正文是否为HTML（默认值：false）
• attachments （数组，可选）：包含文件名和base64内容的附件列表

例子：

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

将同一封电子邮件发送给多个收件人。

参数：

• recipients （数组，必填）：收件人电子邮件地址列表
• subject （字符串，必填）：电子邮件主题
• body （字符串，必填）：电子邮件正文内容
• from_addr （字符串，可选）：发件人电子邮件地址（默认为SMTP_USER）
• html （boolean，可选）：正文是否为HTML（默认值：false）

例子：

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

使用带有变量替换的模板发送电子邮件。

参数：

• to （字符串，必填）：收件人电子邮件地址
• subject （字符串，必填）：电子邮件主题
• template （字符串，必填）：带有｛variable｝占位符的电子邮件模板
• variables （object，必填）：变量名和值字典
• from_addr （字符串，可选）：发件人电子邮件地址（默认为SMTP_USER）
• html （布尔值，可选）：模板是否为HTML（默认值：false）

例子：

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

验证SMTP连接和凭据。

参数： 无

退货： 连接状态、服务器详细信息和端口信息

API终点

MCP流式HTTP（主）

所需标题：

• Mcp-Session-Id：会话ID（初始化后）
• Mcp-Protocol-Version: 2024-11-05
• Accept: application/json, text/event-stream

传统端点（向后兼容）

JSON-RPC方法

项目结构

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配置示例

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"

亚马逊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"

安全特性

• TLS加密：默认情况下，所有SMTP连接都使用TLS
• 安全凭据：SMTP凭据存储在环境变量中
• 输入验证：电子邮件地址和内容已验证
• 非root用户：Docker运行方式为 mcpuser （UID 1000）

发展

# 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镜像详细信息

• 基本图像: python:3.11-slim
• 尺寸：~150-200MB（通过多阶段构建进行了优化）
• 用户：非根 mcpuser
• 健康检查：内置
• 卷: /app/logs （日志）

故障排除

Gmail身份验证问题

如果你正在使用Gmail，你需要：

1. 启用双因素身份验证
2. 生成应用程序密码（不是常规密码）
3. 在中使用应用程序密码 SMTP_PASSWORD

连接超时

如果您遇到连接超时：

1. 检查防火墙设置
2. 验证SMTP主机和端口
3. 尝试使用端口465（SSL）而不是587（TLS）
4. 使用 verify_connection 测试工具

证书错误

如果您收到SSL证书错误：

1. 确保您使用的是有效的SMTP服务器
2. 检查您的网络是否启用了SSL检查
3. 验证服务器的证书是否有效

许可证

MIT许可证

贡献

1. 分叉存储库
2. 创建要素分支
3. 提交您的更改
4. 推到分支
5. 创建拉取请求

支持

有关问题和疑问，请在GitHub上打开问题。