MCP Email Server

Gmail と IMAP アカウントの両方をサポートする、統合メール管理用の包括的な Model Context Protocol (MCP) サーバーです。

🚀 機能

MCP プロトコル対応: ストリーミングHTTP MCPサーバー
Gmail 統合: OAuth2ベースのGmail API アクセスと自動トークン管理
IMAP サポート: 各種メールプロバイダーへの安全なIMAP接続
統一インターフェース: 自動検出機能付きのすべてのメールアカウント用単一MCPインターフェース
アカウント管理: 一元化された設定と接続テスト
堅牢なエラーハンドリング: 詳細なユーザーガイダンス付きの包括的なタイムアウトとエラー管理
セキュリティ: IMAPアカウント用の暗号化パスワードストレージ
クロスアカウント検索: 設定済みのすべてのアカウントを同時に検索

📋 利用可能なMCPツール

🔄 統合ツール（アカウント種別自動判定）

ツール	説明	パラメータ
`list_emails`	任意のアカウントからメール一覧を取得（種別自動判定）	`account_name`, `limit?`, `folder?`, `unread_only?`
`search_emails`	任意のアカウントでメール検索（種別自動判定）	`account_name`, `query`, `limit?`
`search_all_emails`	全てのGmailとIMAPアカウントを横断検索	`query`, `accounts?`, `limit?`, `sortBy?`
`get_email_detail`	任意のアカウントから詳細メール情報を取得	`account_name`, `email_id`
`archive_email`	任意のアカウントでメールをアーカイブ（種別自動判定）	`account_name`, `email_id`, `remove_unread?`
`send_email`	任意のアカウントからメール送信（種別自動判定）	`account_name`, `to`, `subject`, `text/html`, `cc?`, `bcc?`, `attachments?`

🔧 管理ツール

ツール	説明	パラメータ
`list_accounts`	設定済みメールアカウントをステータス付きで一覧表示	なし
`test_connection`	特定のアカウントへの接続テスト	`account_name`
`get_account_stats`	全アカウントの包括的統計情報を取得	なし

🛠️ 利用可能なスクリプト

scripts/ ディレクトリに配置：

📧 認証とセットアップ

スクリプト	目的	使用方法
`gmail-desktop-auth.mjs`	Gmail OAuth2認証セットアップ	`npx tsx scripts/gmail-desktop-auth.mjs [ACCOUNT_NAME]`
`cleanup-env-tokens.mjs`	環境変数のクリーンアップと標準化	`npx tsx scripts/cleanup-env-tokens.mjs`
`setup-xserver.mjs`	XServer用対話式IMAPアカウントセットアップ	`npx tsx scripts/setup-xserver.mjs`
`encrypt-password.ts`	IMAPアカウント用パスワード暗号化	`npx tsx scripts/encrypt-password.ts [PASSWORD]`

🖥️ サーバー管理

スクリプト	目的	使用方法
`server.sh`	MCP Email Server管理（起動/停止/再起動/状態確認）	`./scripts/server.sh {start\|stop\|restart\|status\|logs\|health}`
`monitor-health.ts`	包括的ヘルスチェック（認証状態診断付き）	`npm run health:check`
`test-search-all.sh`	横断検索機能テスト	`./scripts/test-search-all.sh`

⚙️ インストールとセットアップ

1. インストール

git clone <repository-url>
cd mcp-email-server
npm install

2. 環境設定

# 環境設定ファイルのサンプルをコピー
cp .env.example .env

# 設定を編集
nano .env

3. 必要な環境変数

# 必須 - パスワード保存用暗号化キー
EMAIL_ENCRYPTION_KEY=your-unique-32-character-encryption-key

# Gmail OAuth2設定（Gmailを使用する場合）
GMAIL_CLIENT_ID=your-gmail-client-id
GMAIL_CLIENT_SECRET=your-gmail-client-secret  
GMAIL_REDIRECT_URI=urn:ietf:wg:oauth:2.0:oob

# Gmailアカウントトークン（OAuthスクリプトで取得）
GMAIL_REFRESH_TOKEN_accountname=your-refresh-token

# IMAPアカウント設定（IMAPを使用する場合）
IMAP_HOST_accountname=mail.example.com
IMAP_USER_accountname=user@example.com
IMAP_PASSWORD_accountname=encrypted-password-here
IMAP_PORT_accountname=993
IMAP_TLS_accountname=true

4. アカウントセットアップ

Gmailアカウント

# 最初に.envファイルにGmail OAuth2認証情報を設定し、その後：
node scripts/gmail-desktop-auth.mjs ACCOUNT_NAME

# 認証完了後、サーバーを再起動して設定を反映：
./scripts/server.sh restart

IMAPアカウント

# 対話式IMAPセットアップ（推奨）：
node scripts/setup-xserver.mjs

# または手動でパスワードを暗号化：
npx tsx scripts/encrypt-password.ts "あなたのパスワード"

5. サーバー起動と確認

# サーバー起動（LaunchAgent使用）
./scripts/server.sh start

# サーバー状態確認
./scripts/server.sh status

# 包括的ヘルスチェック（推奨）
./scripts/server.sh health
# または
npm run health:check

# 完全テストスイート
npm test

🔧 MCP設定

Cursor MCPセットアップ（推奨）

Cursor MCP設定ファイル (~/.cursor/mcp.json) に追加：

{
  "mcpServers": {
    "mcp-email-server": {
      "url": "http://localhost:3456/mcp",
      "transport": "http"
    }
  }
}

【注意】認証なしで接続されるので、サーバーは絶対公開しないでください。

🖥️ サーバーとテスト

bin/ ディレクトリに配置：

スクリプト	目的	使用方法
`run-streaming-email-server.ts`	本番用MCPサーバー起動	`npx tsx bin/run-streaming-email-server.ts`
※ run-stdio-email-server.ts はメンテ終了

MacOSの常時起動方法

ストリーミングHTTPサーバーMCPですので、サーバーは利用時常時起動で運用してください。 macOSの場合、以下のようなLaunchAgentのplistファイルを作成しておくと便利です。 /PATH/TOは適切なパスに置換してください。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>localhost.mcp-email-server</string>
    <key>Program</key>
    <string>/PATH/TO/tsx</string>
    <key>ProgramArguments</key>
    <array>
        <string>/PATH/TO/.nvm/versions/node/v23.7.0/bin/tsx</string>
        <string>/PATH/TO/mcp-email-server/bin/run-streaming-email-server.ts</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/PATH/TO/src/git/mcp-email-server</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/PATH/TO/Library/Logs/mcp-email-server.log</string>
    <key>StandardErrorPath</key>
    <string>/PATH/TO/Library/Logs/mcp-email-server-error.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/PATH/TO/NODE/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        <key>NODE_PATH</key>
        <string>/PATH/TO/NODE/lib/node_modules</string>
    </dict>
</dict>
</plist>

LaunchAgentでサーバー起動

launchctl load ~/Library/LaunchAgents/localhost.mcp-email-server.plist

その他のテスト用スクリプトは scripts/ ディレクトリに配置：

スクリプト	目的	使用方法
`quick-test.ts`	高速接続・応答テスト	`npx tsx scripts/quick-test.ts`
`monitor-health.ts`	包括的ヘルスモニタリング	`npx tsx scripts/monitor-health.ts`
`decrypt-test.ts`	パスワード復号化機能テスト	`npx tsx scripts/decrypt-test.ts`

💡 MCPツール使用例

アカウント管理

// 設定済みアカウントを全て一覧表示
mcp_mcp-email-server_list_accounts()

// 特定アカウントの接続テスト
mcp_mcp-email-server_test_connection("business_gmail")

// 全アカウントの包括的統計情報を取得
mcp_mcp-email-server_get_account_stats()

メール操作

// 全アカウントを横断検索
mcp_mcp-email-server_search_all_emails({
  query: "invoice",
  accounts: "ALL",
  limit: 20,
  sortBy: "date"
})

// 特定アカウントからメール一覧を取得
mcp_mcp-email-server_list_emails({
  account_name: "business_gmail",
  limit: 10,
  unread_only: true
})

// メール送信（Gmail/IMAP自動判定）
mcp_mcp-email-server_send_email({
  account_name: "business_gmail",
  to: "recipient@example.com",
  subject: "会議スケジュール",
  text: "来週の会議のスケジュールを組みましょう。",
  cc: "manager@example.com"
})

// メールをアーカイブ
mcp_mcp-email-server_archive_email({
  account_name: "business_gmail", 
  email_id: "email_id_here"
})

🧪 テスト

このプロジェクトには、任意のアカウント設定で動作するよう設計された包括的なテストが含まれています：

# 完全テストスイート
npm test

# 特定のテストカテゴリ
npm run test:core          # コア機能テスト
npm run test:integration   # 統合テスト
npm run test:imap-timeout  # IMAPタイムアウト防止テスト

# ヘルスモニタリング
npm run health:check       # 包括的ヘルスチェック
npm run test:quick         # 高速接続テスト

テスト要件

最小構成: 少なくとも1つのGmailアカウントまたは1つのIMAPアカウントが設定済み
フルカバレッジ: 完全なテストにはGmailとIMAPアカウントの両方が必要
テストはアカウント設定を自動検出し、適応します

🔐 セキュリティ機能

パスワード暗号化

全てのIMAPパスワードはAES-256-GCMで暗号化
インストールごとに固有の暗号化キーが必要
セキュリティのための初期化ベクターのランダム化

OAuth2セキュリティ

Gmailアクセスはリフレッシュトークンローテーション付きOAuth2を使用
平文認証情報は保存されない
自動トークン更新

ベストプラクティス

環境変数の分離
バージョン管理に認証情報を含めない
定期的なトークンローテーションを推奨
最小限の権限スコープリクエスト

🛠️ アーキテクチャ

コアコンポーネント

MCPプロトコルハンドラ: JSON-RPC 2.0準拠のリクエスト処理
アカウントマネージャ: 一元化されたアカウント設定と検出
Gmailハンドラ: OAuth2認証されたGmail API操作
IMAPハンドラ: コネクションプーリング付きの安全なIMAPプロトコル実装
統合インターフェース: 自動アカウントタイプ検出とルーティング

エラーハンドリング

MCP準拠の包括的エラーレスポンス
一般的な問題に対する詳細なユーザーガイダンス
一時的な障害に対する自動リトライ機構
部分的サービス利用可能性に対するグレースフルデグラデーション

📊 現在の状態

✅ 完全稼働（100%成功率）

CLIとMCP環境の両方で全ツールのテストと検証が完了：

アカウント管理: 全アカウントタイプで100%成功率
メール操作: 完全なCRUD操作をサポート
クロスアカウント検索: GmailとIMAPを横断した統合検索
接続テスト: 堅牢な接続性検証
エラーハンドリング: 包括的なエラー復旧とユーザーガイダンス

🎯 パフォーマンス指標

応答時間: ほとんどの操作で5秒未満
タイムアウト防止: タイムアウトテストで100%成功率
アカウント検出: 設定済み7/7アカウントの自動検出
エラー復旧: ネットワークと認証問題のグレースフルな処理

🔧 トラブルシューティング

詳細なトラブルシューティングについては doc/re-auth.md を参照してください。

一般的な問題と解決フロー

1. 認証エラーの診断・解決

# 1. ヘルスチェック実行
npm run health:check

# 2. エラーパターンに応じて対処
# パターンA: Gmail認証エラー
node scripts/gmail-desktop-auth.mjs ACCOUNT_NAME
./scripts/server.sh restart

# パターンB: サーバー再起動のみ必要
./scripts/server.sh restart

# パターンC: IMAP認証エラー
npx tsx scripts/decrypt-test.ts

2. サーバー管理

# サーバー状態確認
./scripts/server.sh status

# サーバー再起動（認証後は必須）
./scripts/server.sh restart

# ログ確認
./scripts/server.sh logs
./scripts/server.sh logs error

3. 詳細診断

# 横断検索テスト
./scripts/test-search-all.sh

# 個別アカウントテスト
curl -X POST http://localhost:3456/mcp \
  -H "Content-Type: application/json" \
  -d '{"method":"tools/call","params":{"name":"test_connection","arguments":{"account_name":"ACCOUNT_NAME"}}}'

予防保守

# 定期ヘルスチェック（推奨: 毎日）
./scripts/server.sh health

# 定期再起動（推奨: 週1回）
./scripts/server.sh restart

デバッグモード

# 詳細ログでサーバー起動
DEBUG=1 npx tsx bin/run-streaming-email-server.ts

# 開発モードで実行
NODE_ENV=development npx tsx bin/run-streaming-email-server.ts

📈 将来の機能拡張

追加のメールプロバイダーサポート
高度なフィルタリングと検索オプション
メールテンプレート管理
一括操作サポート
会議メール用カレンダー連携

🤝 貢献

リポジトリをフォーク
機能ブランチを作成
包括的なテストを追加
全テストが合格することを確認
プルリクエストを提出

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照。

🆘 サポート

問題や質問について：

doc/re-auth.md のAI向けワークフローを確認
ヘルスチェックで問題を診断: ./scripts/server.sh health
サーバー管理ツールを活用: ./scripts/server.sh --help
デバッグログを確認: ./scripts/server.sh logs
詳細なエラー情報と設定詳細を含めてissueを作成

🤖 AI支援

このプロジェクトには AI（Claude、ChatGPT等）向けの診断・解決ワークフローが含まれています：

自動診断: npm run health:check による問題の自動分類
段階的解決: パターン別の具体的な対処手順
予防保守: 定期的なメンテナンス推奨事項