MCP Mail Server

言語: English | 中文

Claude や Cursor などの AI アシスタントと連携して、IMAP/SMTP のメール操作を行うための Model Context Protocol サーバーです。

機能

• IMAP 操作: メールボックスを横断してメールの検索、既読の確認、管理ができます

• SMTP 対応: HTML/テキスト本文と添付ファイル付きのメールを送信できます

• 添付ファイル管理: 添付ファイルのメタデータを表示し、ローカルの各ファイルに保存できます

• セキュリティを重視した設定: TLS/SSL に対応した環境変数式の設定

• AI フレンドリー: 自然言語コマンドでメール操作が可能

• 自動接続管理: IMAP/SMTP 接続の自動処理

• 複数メールボックス対応: INBOX、送信済み、カスタムフォルダにアクセス

変更履歴

[1.2.1] - 2026-03-18

修正

• 検索条件 (FROM/TO/SUBJECT/BODY/KEYWORD/SINCE) が入れ子配列形式になっていないため、TO などの検索でエラーが発生していた点を修正

• search() が条件を余計な配列でラップし、複合検索条件を壊していた点を修正

• deleteMessage() がメールボックスを読み取り専用で開いた場合に黙々と失敗していた点を修正

• getRecentMessages() が IMAP の RECENT フラグを誤って使用していた点を修正。UID で最新の N 件を取得するように変更

• getRecentMessages() / getUnseenMessages() が以前の操作で残ったメールボックス状態に依存していた点を修正

• cleanReplySubject() が Re: プレフィックスを 1 層しか除去せず、未返信メールの判定で見落としが生じていた点を修正

• メールの日付をロケール文字列で保存していたため、new Date() の解釈がプラットフォームによって変わることがあった問題を修正し、ISO 8601 に変更

• ensureIMAPConnection() に並行初期化待ちのタイムア而がなかった項目を修正

• saveSentMessage() が保存失敗時にも常に sentFolderSaved: true を返していた問題を修正

• handleGetMessages() / handleDeleteMessage() がメッセージの特定に currentBox 状態依存だった問題を修正

• reply_to_email が本文 text が空のときに、本文面にリテラル "undefined" を書いた問題を修正

追加

• すべての検索ツールに、検索対象を INBOX に限定する inboxOnly 專用のパ段落を追加

改善

• rehSMTPConnection() に IMAP と同様の同時実行ガード（30 秒タイムアウト）を追加

• 送信済みメールボックスを RFC 6154 の \Sent 特殊用途属性で自動検出し、結果をキャッシュ化（すべてのメールプロパイダに対応）

• saveMessageToFolder() を簡素化し、送信済みフォルダがない場合は保存処理をスキップ

• 検索では slice(-limit) を使って新しいメールから取得し、日付絞り込み後に結果が空になることを防止

• 返信メールの引用部分に HTML エスケープを適用して XSS インジェクションを防止

完全なバージョン履歴は CHANGELOG.md を参照してください

クイックスタート

1. インストール: npm install -g mcp-mail-server

2. 設定: 環境変数を設定します（設定 を参照）

3. 追加: MCP クライアント設定に追加します

4. 利用: 自然言語で操作します。例: "今日の未読メールを表示して"

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

Cursor の MCP 設定に追加します：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

claude mcp add コマンドで追加します：

claude mcp add mcp-mail-server \
  -e IMAP_HOST=your-imap-server.com \
  -e IMAP_PORT=993 \
  -e IMAP_SECURE=true \
  -e SMTP_HOST=your-smtp-server.com \
  -e SMTP_PORT=465 \
  -e SMTP_SECURE=true \
  -e EMAIL_USER=your-email@domain.com \
  -e EMAIL_PASS=your-password \
  -- npx -y mcp-mail-server

または、手動で .claude/settings.json に追加します：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

プロジェクトルートの codex.json に追加します：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

Loader 方法も同様です。基本的な設定は次の通りです：

{
  "mcpServers": {
    "mcp-mail-server": {
      "command": "npx",
      "args": ["-y", "mcp-mail-server"],
      "env": {
        "IMAP_HOST": "your-imap-server.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "SMTP_HOST": "your-smtp-server.com",
        "SMTP_PORT": "465",
        "SMTP_SECURE": "true",
        "EMAIL_USER": "your-email@domain.com",
        "EMAIL_PASS": "your-password"
      }
    }
  }
}

設定ファイルの場所は、お使いの MCP クライアントのドキュメントを参照してください。

利用可能なツール

接続管理

• connect_all: パラメータは不要です

• get_connection_status: パラメータは不要です

• disconnect_all: パラメータは不要です

メールボック操作

• open_mailbox: mailboxName（文字列、デフォルト: "INBOX"）、readOnly（ブール値）

• list_mailboxes: パラメータは不要です

検索操作

• search_by_sender: sender（文字列、メールアドレス）、startDate（文字列、任意）、endDate（文字列、任意）

• search_by_subject: subject（文字列、キーワード）、, startDate（文字列、任意）、endDate`（文字列、任意）

• search_recipient: recipient（文字列、メールアドレス）、, startDate（文字列、任意）、endDate`（文字列、任意）

• search_body: text（文字列、検索テキスト）、startDate（文字列、任意）、, endDate`（文字列、任意）

• search_since_date: date（文字列、日付形式）

• search_unread_from_sender: sender（文字列、メールアドレス）、, startDate（文字列、任意）、, endDate（文字列、任意）

• search_unreplied_from_sender: sender（文字列、メールアドレス）、, startDate（文字列、任意）、, endDate（文字列、任意）、, limit`（数値、任意）

• search_with_keyword: keyword（文字列、キーワード）、, startDate（文字列、任意）、, endDate（文字列、任意）

• search_all_messages: startDate（文字列、任意）、, endDate（文字列、任意）、, limit（数値、任意、デフォルト: 50）

メッセージ操作

• get_message_count: パラメータは不要です

• get_unseen_messages: パラメータは不要です

• get_recent_messages: パラメータは不要です

• get_message: uid（数値）、markSeen（boolean、任意）

• get_messages: uids（配列）、, markSeen`（boolean、任意）

• delete_message: uid（数値）

メール送信

• send_email: to（文字列）、subject（文字列）、text（文字列、任意）、, html（文字列、任意）、, cc（文字列、任意）、, bcc（文字列、任意）、, attachments（文字列配列、任意、絶対ファイルパス）

• reply_to_email: originalUid（数字）、, text（文字列）、, html（文字列、任意）、, replyToAll（boolean、任意）、, includeOriginal（boolean、任意）

添付ファイル操作

• get_attachments: uid（数字）— fileName、contentType、size、index のメタデータを返します

• save_attachment: uid（数字）、savePath（文字列、絶対パス）、, attachmentIndex（数字、任意、0 始まり）、, returnBase64（boolean、任意、デフォルト: false）

使用例

AI アシスタントに自然言語で指示できます。

基本操作

• "メールサーバーに接続して"

• "未読メールを全部表示して"

• "boss@company.com からのメールを検索して"

• "team@company.com に会議についてのメールを送って"

• "UID 123 のメールに返信して"

高度な検索

• "先週の件名に「urgent」が含まれるメールを探して"

• "boss@company.com からの未返信メールを表示して"

• "team@company.com 宛のメールを検索して"

• "Sales フォルダのメールをすべて取得して"

• "boss@company.com からの未読メールを表示して"

• "過去 7 日間のすべてのメールを表示して"

• "すべてのメッセージを一覧表示して、20 件に制限して"

メール管理

• "UID 123 のメールを削除して"

• "最近のメールを既読にする"

• "メールフォルダをすべて一覧表示して"

添付ファイル操作

• "メール UID 456 の添付ファイルを表示して"

• "メール UID 456 のすべての添付ファイルを D:/Downloads に保存して"

• "メール UID 789 の最初の添付ファイルをダウンロードして"

• "添付ファイル D:/report.pdf を添えて team@company.com にメールを送って"

設定

環境変数

⚠️ すべての変数が必須です

任意の変数

トランスポルト モード（stdio / HTTP）

デフォルトでは、サーバーは stdio（ローカルクライアント用の標準MCPトランスポート）で動作します。また、Streamable HTTPサーバーとして、HTTPS上で動作させることもできます。

証明書と鍵が見つかった場合、サーバーは HTTPS で動作します。それ以外の場合は、警告とともに 平文 HTTP にフォールバックします。

ローカルで信頼される証明を mkcert で生成します:

mkcert -install   # one-time: install the local CA
mkcert -cert-file certs/localhost-cert.pem -key-file certs/localhost-key.pem localhost 127.0.0.1 ::1

HTTP モードで実行します:

MCP_TRANSPORT=http MCP_HTTP_PORT=8443 npm start
# → MCP endpoint:  https://localhost:8443/mcp
# → Health check:  https://localhost:8443/health

MCP エンドポイントは /mcp で提供され、Streamable HTTP 仕様に従って、セッション管理（mcp-session-id ヘッダー経由）と SSE ストリーミグをサポーをします。

一般的なメールプロバイダー

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_SECURE=true
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

注記: 通常のパスワードの代わりに App Passwords を使用してください。

IMAP_HOST=outlook.office365.com
IMAP_PORT=993
IMAP_SECURE=true
SMTP_HOST=smtp.office365.com
SMTP_PORT=587
SMTP_SECURE=true
EMAIL_USER=your-email@outlook.com
EMAIL_PASS=your-password

セキュリティ注意

• App Passwords を使用: 2FAを有効にし、対応可能な場合はアプリ固有のパスワードを使用してください

• TLS/SL必須: 常に安全な接続を使用してください（IMAP_SECURE=true、SMTP_SECURE=true）

• 環境変数: 設定ファイルに認証情報をハードコ不ドしない

開発

1. リポジトリをクローン:

   git clone https://github.com/yunfeizhu/mcp-mail-server.git
   cd mcp-mail-server

2. 依存関係をインストール:

   npm install

3. プロジェクトをビルド:

   npm run build

4. 環境変数を設定:

   export IMAP_HOST=your-imap-server.com
   export IMAP_PORT=993
   export IMAP_SECURE=true
   export SMTP_HOST=your-smtp-server.com
   export SMTP_PORT=465
   export SMTP_SECURE=true
   export EMAIL_USER=your-email@domain.com
   export EMAIL_PASS=your-password

5. サーバーを実装:

   npm start

コントリン

コントリビューションは歓迎です！Pull Request をお送付けてくださいのまま。

ライセンス

MIT ライセンス - 詳細は [LICENSE を]（LICENSE） ファイルをご覧ください。

パッケージ情報:

• パッケージ: mcp-mail-server

• Node.js: ≥18.0.0

• リポジトリ: GitHub

• イッシューチュー: バグを報告