Java Mcp Server For Smtp Mailing

SMTP MCP サーバー（Java SDK 0.11.0）

SMTP 連携を通じて堅牢なメール送信機能を提供する、包括的な Model Context Protocol（MCP）サーバーです。このサーバーは複数のトランスポートプロトコル（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 対応：TLS セキュリティを使用する Gmail SMTP 向けに事前設定済み
• 複数の宛先：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 段階認証を有効にします
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. ストリーマブル 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（任意）：CC のメールアドレス
• bcc（任意）：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 に適している	設定がより複雑
ストリーマブル HTTP	テスト、REST クライアント	HTTP/JSON	テストが容易、標準的な HTTP	リアルタイム処理の効率が低い

サーバーエンドポイント（HTTP トランスポート）

エンドポイント	メソッド	説明
/message	POST	MCP プロトコルのエンドポイント（ストリーマブル HTTP）
/sse	GET	Server-Sent Events エンドポイント
/api/test-email	POST	メール送信用の REST エンドポイント
/api/health	GET/POST	ヘルスチェック用エンドポイント

🔗 関連プロジェクト

このサーバーは、包括的な MCP エコシステムの一部です。

1. MCP Client Dataset Creating Assistant

• 目的：Web スクレイピングを利用した 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 アカウントで 2FA が有効になっていることを確認します。
• 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通あたり約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：無料アカウントは1日あたり約100通、有料アカウントはそれ以上
• Outlook：個人アカウントは1日あたり約300通
• Yahoo：1日あたり約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. リポジトリをフォークします
2. フォークしたリポジトリをクローンします：

   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 およびその他のオープンソースライブラリを使用しています。詳細については、各依存関係のライセンスを参照してください。

💡 サポート

問題や質問がある場合：

イシューを作成する

• バグ報告：詳細な再現手順を記載してください
• 機能リクエスト：ユースケースと期待する動作を説明してください
• 質問：まず既存のイシューを確認してください

デバッグ用チェックリスト

1. ✅ トラブルシューティングのセクションを確認します
2. ✅ サーバーログで詳細なエラーメッセージを確認します
3. ✅ 別のメールクライアントを使用して SMTP の設定を検証します
4. ✅ MCP 統合を使用する前に、REST エンドポイントでテストします
5. ✅ 問題を切り分けるため、異なるトランスポートプロトコルを試します
6. ✅ Java と Maven のバージョンが要件を満たしていることを確認します

ヘルプを受ける

• ドキュメント：この README とコード内のコメントを確認してください
• 例：統合例については関連プロジェクトを参照してください
• コミュニティ：コミュニティのサポートを受けるには、GitHub のイシューを作成してください
• エンタープライズ：本番環境へのデプロイでは、プロフェッショナルサポートをご検討ください

---

MCP エコシステムのために ❤️ を込めて作成

このサーバーは AI アプリケーションとメール通信の間のギャップを埋め、強力な自動化ワークフローとシームレスなユーザー通知を実現します。