Java Mcp Server For Smtp Mailing

SMTP MCP Server（Java SDK 0.11.0）

一款功能全面的 Model Context Protocol（MCP）服务，可通过 SMTP 集成提供可靠的邮件发送功能。该服务支持多种传输协议（STDIO、SSE 和 Streamable HTTP），并通过 MCP 工具和 REST 端点提供邮件功能，非常适合将邮件能力集成到 AI 应用、自动化工作流和测试环境中。

📋 目录

• 功能
• 前置条件
• 架构概览
• 安装与构建
• 配置
• 用法
  • STDIO 传输
  • SSE 传输
  • Streamable HTTP
• 测试
• API 参考
• 相关项目
• 故障排除
• 性能与监控
• 贡献

🚀 功能

核心功能

• 多种传输协议：STDIO、Server-Sent Events（SSE）和 Streamable HTTP
• MCP 工具集成：为 MCP 客户端提供 send-email 工具
• REST API：简洁的 REST 端点，用于测试和集成
• Gmail SMTP 支持：预配置 Gmail SMTP，并采用 TLS 安全保护
• 多个收件人：支持 TO、CC 和 BCC 收件人
• 运行状况监控：内置运行状况检查端点
• 兼容 Claude Desktop：可直接与 Claude Desktop 和其他 MCP 客户端配合使用

高级功能

• 丰富的邮件格式：支持 HTML 和纯文本邮件
• 附件支持（计划中）：支持文件附件
• 邮件模板（计划中）：可重复使用的邮件模板
• 重试机制：邮件发送失败时自动重试
• 速率限制：内置保护机制，防止垃圾邮件和过度使用
• 全面的日志记录：提供详细日志，便于调试和监控

📋 前置条件

• Java 21 或更高版本
• Maven 3.6+
• Gmail 账号及应用专用密码（或其他 SMTP 服务的凭据）
• MCP 客户端（Claude Desktop、自定义客户端或用于测试的 MCP Inspector）

🏗️ 架构概览

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │   MCP Server     │    │   SMTP Server   │
│  (Claude, etc.) │◄───┤  (This Project)  │────►│   (Gmail, etc.) │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                         ┌────▼────┐
                         │ REST API│
                         │ Testing │
                         └─────────┘

应用由以下部分组成：

• MCP 服务：通过多种传输方式处理 MCP 协议通信
• 邮件服务：基于 JavaMail 的核心 SMTP 邮件发送功能
• REST 端点：用于测试和运行状况检查的其他 HTTP 端点
• 传输层：支持 STDIO、SSE 和 Streamable HTTP 协议
• 配置层：为不同 SMTP 服务商提供灵活配置

🛠️ 安装与构建

1. 克隆仓库

git clone https://github.com/RayenMalouche/Java-MCP-Server-For-SMTP-Mailing.git
cd Java-MCP-Server-For-SMTP-Mailing

2. 配置邮件设置

编辑 Application.java 中的 SMTP 配置：

// SMTP Configuration - Update these values
private static final String SMTP_USERNAME = "[email protected]";
private static final String SMTP_PASSWORD = "your-app-password";
private static final String SMTP_HOST = "smtp.gmail.com";
private static final int SMTP_PORT = 587;
private static final boolean SMTP_TLS_ENABLED = true;
private static final boolean SMTP_SSL_ENABLED = false;

3. 构建项目

# Clean build
mvn clean compile

# Create JAR file
mvn clean package -DskipTests

# Build with tests (optional)
mvn clean package

⚙️ 配置

设置 Gmail 应用专用密码

1. 在 Gmail 账号上启用两步验证
2. 前往Google 账号设置 > 安全性 > 应用专用密码
3. 为此应用生成新的应用专用密码
4. 在 SMTP_PASSWORD 字段中使用生成的密码

其他 SMTP 服务商

Microsoft Outlook/Hotmail

private static final String SMTP_HOST = "smtp-mail.outlook.com";
private static final int SMTP_PORT = 587;
private static final boolean SMTP_TLS_ENABLED = true;

Yahoo Mail

private static final String SMTP_HOST = "smtp.mail.yahoo.com";
private static final int SMTP_PORT = 587;
private static final boolean SMTP_TLS_ENABLED = true;

自定义 SMTP 服务

private static final String SMTP_HOST = "your-smtp-server.com";
private static final int SMTP_PORT = 25; // or 465/587
private static final boolean SMTP_TLS_ENABLED = true;

📖 用法

查找所需路径

使用此服务前，请先在系统中找到以下路径：

项目路径

Windows：右键单击文件夹 → 属性 → 位置

Example: C:\Users\YourName\Documents\Java-MCP-Server-For-SMTP-Mailing

macOS/Linux：

cd /path/to/project && pwd
# Example: /home/username/Java-MCP-Server-For-SMTP-Mailing

Java 可执行文件路径

Windows：

where java
# Example: C:\Program Files\Common Files\Oracle\Java\javapath\java.exe

macOS/Linux：

which java
# Example: /usr/bin/java or /opt/homebrew/bin/java

Java Home 路径

Windows：

echo %JAVA_HOME%
# Example: C:\Program Files\Java\jdk-21

macOS/Linux：

echo $JAVA_HOME
# Example: /usr/lib/jvm/java-21-openjdk

1. STDIO 传输（推荐用于 Claude Desktop）

使用 MCP Inspector 进行测试

# From inside your project directory:

# 1. Start the server
java -jar target/RayenMalouche-0.0.1-SNAPSHOT.jar --stdio

# 2. In another terminal, run the inspector
npx @modelcontextprotocol/inspector java -jar "<FULL_PATH_TO_PROJECT>/target/RayenMalouche-0.0.1-SNAPSHOT.jar" --stdio

Claude Desktop 集成

Windows 配置（%APPDATA%\Claude\config.json）：

{
  "mcpServers": {
    "smtp-email-server": {
      "command": "<JAVA_EXECUTABLE_PATH>",
      "args": [
        "-jar",
        "<FULL_PATH_TO_PROJECT>\\target\\RayenMalouche-0.0.1-SNAPSHOT.jar",
        "--stdio"
      ],
      "env": {
        "JAVA_HOME": "<JAVA_HOME_PATH>"
      }
    }
  }
}

macOS/Linux 配置（~/Library/Application Support/Claude/config.json 或 ~/.config/Claude/config.json）：

{
  "mcpServers": {
    "smtp-email-server": {
      "command": "<JAVA_EXECUTABLE_PATH>",
      "args": [
        "-jar",
        "<FULL_PATH_TO_PROJECT>/target/RayenMalouche-0.0.1-SNAPSHOT.jar",
        "--stdio"
      ],
      "env": {
        "JAVA_HOME": "<JAVA_HOME_PATH>"
      }
    }
  }
}

注意：env 部分为可选项，但建议配置以保持一致。

2. Server-Sent Events（SSE）传输

启动 SSE 服务

java -jar target/RayenMalouche-0.0.1-SNAPSHOT.jar --sse

使用 MCP Inspector 进行测试

npx @modelcontextprotocol/inspector java -jar "<FULL_PATH_TO_PROJECT>/target/RayenMalouche-0.0.1-SNAPSHOT.jar" --sse

直接连接 MCP 客户端

将 MCP 客户端连接到：http://localhost:45450/sse

3. Streamable HTTP 传输

启动 HTTP 服务

java -jar target/RayenMalouche-0.0.1-SNAPSHOT.jar --streamable-http

使用 MCP Inspector 进行测试

npx @modelcontextprotocol/inspector java -jar "<FULL_PATH_TO_PROJECT>/target/RayenMalouche-0.0.1-SNAPSHOT.jar" --streamable-http

🧪 测试

REST API 测试

发送邮件

curl -X POST http://localhost:45450/api/test-email \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "subject": "Test Email from MCP Server",
    "body": "This is a test email sent via the MCP SMTP server!",
    "cc": "[email protected]",
    "bcc": "[email protected]"
  }'

健康检查

curl http://localhost:45450/api/health

使用 Postman

1. 将端点导入 Postman
2. 基础 URL：http://localhost:45450
3. 端点：
   • POST /api/test-email（发送邮件）
   • GET /api/health（健康检查）

通过 Claude Desktop 测试 MCP 工具

设置好 Claude Desktop 集成后，你可以通过向 Claude 提问来进行测试：

"Send an email to [email protected] with the subject 'Meeting Reminder' and body 'Don't forget about our meeting tomorrow at 2 PM.'"

Claude 会使用 MCP 工具，通过你配置的 SMTP 服务发送邮件。

📚 API 参考

MCP 工具：send-email

参数：

• to（必填）：收件人电子邮件地址
• subject（必填）：邮件主题
• body（必填）：邮件正文
• cc（可选）：抄送电子邮件地址
• bcc（可选）：密送电子邮件地址

在 MCP 客户端中的用法示例：

{
  "tool": "send-email",
  "parameters": {
    "to": "[email protected]",
    "subject": "Hello from MCP",
    "body": "This email was sent via Model Context Protocol!",
    "cc": "[email protected]"
  }
}

REST 端点

POST /api/test-email

通过 REST API 发送邮件。

请求正文：

{
  "to": "[email protected]",
  "subject": "Email Subject",
  "body": "Email body content",
  "cc": "[email protected]",
  "bcc": "[email protected]"
}

成功响应（200 OK）：

{
  "status": "success",
  "message": "Email sent successfully",
  "details": {
    "to": "[email protected]",
    "subject": "Email Subject",
    "cc": "[email protected]",
    "bcc": "[email protected]"
  }
}

错误响应（500 Internal Server Error）：

{
  "status": "error",
  "message": "Failed to send email: [error details]",
  "errorType": "AuthenticationFailedException"
}

GET /api/health

检查服务健康状态。

响应（200 OK）：

{
  "status": "UP",
  "timestamp": "2025-08-29T10:30:00Z",
  "smtp": {
    "status": "UP",
    "host": "smtp.gmail.com",
    "port": 587
  }
}

传输协议对比

传输方式	使用场景	连接方式	优点	缺点
STDIO	Claude Desktop、直接集成	进程管道	简单、直接、高效	需要管理进程
SSE	Web 应用、实时场景	HTTP/SSE	实时更新、适合 Web	设置较复杂
Streamable HTTP	测试、REST 客户端	HTTP/JSON	易于测试、标准 HTTP	实时场景下效率较低

服务端点（HTTP 传输）

端点	方法	描述
/message	POST	MCP 协议端点（Streamable HTTP）
/sse	GET	Server-Sent Events 端点
/api/test-email	POST	用于发送邮件的 REST 端点
/api/health	GET/POST	健康检查端点

🔗 相关项目

此服务属于一个全面的 MCP 生态系统：

1. MCP Client Dataset Creating Assistant

• 用途：使用网页抓取生成 AI 数据集
• 集成方式：使用此 SMTP 服务发送完成通知
• 传输方式：通过 SSE 连接到此服务
• 使用场景：自动将生成的数据集通过邮件发送给用户

2. AI Agents Performance Testing MCP Server

• 用途：对 MCP 客户端进行性能测试和基准测试
• 集成方式：可在负载下测试此 SMTP 服务的性能
• 功能：负载测试、指标收集、成本分析
• 使用场景：验证生产环境中邮件服务的性能

3. AI Agents Performance Testing MCP Client

• 用途：连接到性能测试服务的客户端应用
• 集成方式：可使用此 SMTP 服务发送测试结果通知
• 功能：自动化测试工作流、结果报告
• 使用场景：端到端测试 MCP 邮件工作流

集成示例

与数据集创建助手集成

// The dataset assistant sends completion emails like:
{
  "to": "[email protected]",
  "subject": "Dataset Generation Complete - 150 samples created",
  "body": "Your requested dataset has been generated successfully. Total samples: 150. Processing time: 45 seconds. Dataset available at: /datasets/company-solutions-2025-08-29.json"
}

与性能测试集成

// Performance test results notification:
{
  "to": "[email protected]",
  "subject": "MCP Performance Test Results - Dataset Assistant",
  "body": "Performance test completed. Average response time: 12.5s. Success rate: 95%. Total cost: $0.45. Full report attached."
}

🐛 故障排除

常见问题

1. 身份验证失败

症状：发送邮件时出现身份验证错误

解决方案：

• 确保使用 Gmail 的应用专用密码（而不是账户密码）
• 确认 Google 账户已启用双重身份验证
• 仔细检查 Application.java 中的用户名和密码
• 使用简单的邮件客户端测试 SMTP 凭据

调试步骤：

# Enable detailed JavaMail debug logging
java -Dmail.debug=true -jar target/RayenMalouche-0.0.1-SNAPSHOT.jar --stdio

2. 连接被拒绝

症状：无法连接到 SMTP 服务器

解决方案：

• 检查 SMTP 服务器设置是否正确
• 确认防火墙允许通过端口 587 建立出站连接
• 确保 TLS 设置符合 SMTP 服务提供商的要求
• 尝试不同的 SMTP 端口（25、465、587）

网络测试：

# Test SMTP server connectivity
telnet smtp.gmail.com 587

3. 端口已被占用

症状：服务器启动失败，并出现端口绑定错误

解决方案：

• 服务器默认使用端口 45450
• 停止所有正在使用该端口的进程
• 或在 Application.java 中修改端口

检查端口占用情况：

# Windows
netstat -ano | findstr 45450

# macOS/Linux  
lsof -i :45450

4. MCP Inspector 连接问题

症状：Inspector 无法连接到 MCP 服务

解决方案：

• 确保先启动服务器，再启动 Inspector
• 检查是否使用了正确的传输参数（--stdio、--sse、--streamable-http）
• 确认 JAR 文件路径正确且为绝对路径
• 检查服务器日志中的启动错误

5. Claude Desktop 集成问题

症状：Claude 无法识别邮件工具

解决方案：

• 检查 config.json 文件的位置和语法
• 修改配置后重启 Claude Desktop
• 检查 Java 路径是否正确且为绝对路径
• 确保 JAR 文件已构建且可访问
• 确认 JAVA_HOME 环境变量

配置验证：

# Test Java path
"<JAVA_EXECUTABLE_PATH>" -version

# Test JAR file
"<JAVA_EXECUTABLE_PATH>" -jar "<FULL_PATH_TO_PROJECT>/target/RayenMalouche-0.0.1-SNAPSHOT.jar" --stdio

调试模式

启用全面日志记录：

# Full debug mode with JavaMail debugging
java -Dmail.debug=true -Dlogging.level.com.mcp=DEBUG -jar target/RayenMalouche-0.0.1-SNAPSHOT.jar --stdio

测试建议

1. 从 STDIO 开始：最容易测试和调试
2. 使用 REST 端点：独立于 MCP 测试邮件功能
3. 通过 Inspector 验证：确认 MCP 协议集成正常
4. 检查日志：查看控制台输出，获取详细错误信息
5. 测试邮件送达情况：发送邮件到你控制的测试邮箱
6. 验证 SMTP 设置：使用独立的邮件客户端验证 SMTP 凭据

📊 性能与监控

性能特征

• 启动时间：约 5-10 秒（包括 SMTP 连接验证）
• 邮件发送：每封邮件约 1-3 秒（取决于 SMTP 服务器）
• 内存使用量：约 100-200 MB（因 Java 堆大小而异）
• 吞吐量：每分钟最多 100 封邮件（受 Gmail 速率限制影响）

监控

健康检查端点

# Check server status
curl http://localhost:45450/api/health

# Expected response
{
  "status": "UP",
  "smtp": {
    "status": "UP",
    "host": "smtp.gmail.com", 
    "port": 587
  }
}

日志监控

# Monitor real-time logs
java -jar target/RayenMalouche-0.0.1-SNAPSHOT.jar --stdio | tee server.log

# Search for errors
grep -i error server.log
grep -i exception server.log

速率限制

Gmail 和其他服务提供商都有速率限制：

• Gmail：免费账户每天约 100 封邮件，付费账户的限额更高
• Outlook：个人账户每天约 300 封邮件
• Yahoo：每天约 100 封邮件

在生产环境中使用时，请实现客户端速率限制。

🔧 依赖项

• Spring Boot 3.5.4：应用框架
• MCP SDK 0.11.0：Model Context Protocol 实现
• Eclipse Jetty 12.0.18：HTTP 传输的嵌入式服务器
• Jakarta Mail 2.0.1：邮件发送功能
• Jackson 2.15.2：JSON 处理
• SLF4J + Logback：日志框架

🔒 安全说明

生产环境注意事项

• 切勿将凭据提交到版本控制系统
• 使用环境变量存储敏感配置：

  export [email protected]
  export SMTP_PASSWORD=your-app-password
  

• 为 REST 端点实施速率限制，防止滥用
• 所有 SMTP 连接都使用 TLS 加密
• 企业部署可考虑使用 OAuth2 替代应用专用密码
• 验证并清理所有邮件输入，防止注入攻击

环境变量配置

// Example environment variable usage
private static final String SMTP_USERNAME = System.getenv("SMTP_USERNAME");
private static final String SMTP_PASSWORD = System.getenv("SMTP_PASSWORD");

🤝 参与贡献

欢迎贡献！以下是开始参与的方式：

开发环境设置

1. Fork 此仓库
2. 克隆你的 fork：

   git clone https://github.com/yourusername/Java-MCP-Server-For-SMTP-Mailing.git
   

3. 创建功能分支：

   git checkout -b feature/amazing-feature
   

4. 进行更改并全面测试
5. 使用所有传输协议进行测试
6. 提交拉取请求

代码风格

• 遵循标准 Java 规范
• 添加完整的 JavaDoc 注释
• 为新功能编写单元测试
• 确保所有现有测试均通过

测试要求

# Run all tests
mvn test

# Run with different transports
mvn test -Dtest.transport=stdio
mvn test -Dtest.transport=sse  
mvn test -Dtest.transport=http

📄 许可证

本项目使用 Spring Boot 和其他开源库。更多信息请参阅各依赖项的许可证。

💡 支持

如有问题或疑问：

创建 Issue

• Bug 报告：提供详细的复现步骤
• 功能请求：描述使用场景和预期行为
• 问题咨询：先查看现有 Issue

调试检查清单

1. ✅ 查看故障排除部分
2. ✅ 检查服务日志以获取详细错误信息
3. ✅ 使用独立的邮件客户端验证 SMTP 配置
4. ✅ 在使用 MCP 集成前，先通过 REST 端点进行测试
5. ✅ 尝试不同的传输协议以定位问题
6. ✅ 确认 Java 和 Maven 版本符合要求

获取帮助

• 文档：查看此 README 和内联代码注释
• 示例：查看相关项目中的集成示例
• 社区：在 GitHub 上创建 Issue 以获取社区支持
• 企业：对于生产部署，可考虑寻求专业支持

---

为 MCP 生态系统倾心打造 ❤️

此服务连接了 AI 应用与电子邮件通信，使强大的自动化工作流和无缝的用户通知成为可能。