MCP Email Server

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

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

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

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

# 必須 - パスワード保存用暗号化キー 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

# 最初に.envファイルにGmail OAuth2認証情報を設定し、その後： node scripts/gmail-desktop-auth.mjs ACCOUNT_NAME # 認証完了後、サーバーを再起動して設定を反映： ./scripts/server.sh restart

# 対話式IMAPセットアップ（推奨）： node scripts/setup-xserver.mjs # または手動でパスワードを暗号化： npx tsx scripts/encrypt-password.ts "あなたのパスワード"

# サーバー起動（LaunchAgent使用） ./scripts/server.sh start # サーバー状態確認 ./scripts/server.sh status # 包括的ヘルスチェック（推奨） ./scripts/server.sh health # または npm run health:check # 完全テストスイート npm test

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

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

ストリーミング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>

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

// 設定済みアカウントを全て一覧表示 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で暗号化
- インストールごとに固有の暗号化キーが必要
- セキュリティのための初期化ベクターのランダム化

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

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

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

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

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

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

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

# 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

# サーバー状態確認 ./scripts/server.sh status # サーバー再起動（認証後は必須） ./scripts/server.sh restart # ログ確認 ./scripts/server.sh logs ./scripts/server.sh logs error

# 横断検索テスト ./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

- 追加のメールプロバイダーサポート
- 高度なフィルタリングと検索オプション
- メールテンプレート管理
- 一括操作サポート
- 会議メール用カレンダー連携
- リポジトリをフォーク
- 機能ブランチを作成
- 包括的なテストを追加
- 全テストが合格することを確認
- プルリクエストを提出
- doc/re-auth.mdのAI向けワークフローを確認
- ヘルスチェックで問題を診断:./scripts/server.sh health
- サーバー管理ツールを活用:./scripts/server.sh --help
- デバッグログを確認:./scripts/server.sh logs
- 詳細なエラー情報と設定詳細を含めてissueを作成

Manage your Gmail account, including sending, reading, and organizing emails.