email-mcp

IMAP + SMTPを介した単一メールボックス用の小規模な個人用MCPサーバーです。

主にプライベートなセットアップを想定しています：

• メールボックス1つ

• 認証情報は環境変数から提供

• IMAP経由でメールを読み取り

• SMTP経由でメールを送信

• Yandex Mailのデフォルト設定でうまく動作しますが、任意のIMAP/SMTPプロバイダーを指定可能です

変更点

このリポジトリは元々 stdio モードでのみ動作していました。ローカルのMCPクライアントには適していますが、ChatGPT Web統合にはHTTP MCPエンドポイントが必要です。サーバーは現在以下をサポートしています：

• ローカル/開発用の stdio

• ChatGPT Webアプリ用の streamable-http

• 互換性のための sse

また、メールスレッドの問題も修正しました：

• 以前の reply_to パラメータは Reply-To ヘッダーのみを設定していました

• 本来の返信には通常 In-Reply-To と References を使用すべきです

• read_email はこれらのヘッダーを返すようになり、send_email に渡せるようになりました

さらに read_email の出力を改善し、以下を返すようにしました：

• デコードされたヘッダー

• 添付ファイルのメタデータ

• メッセージスレッドヘッダー

Related MCP server: IMAP/SMTP Email MCP Server

添付ファイルのサポート

このバージョンでは、添付ファイルの読み取りと送信の両方をサポートしています。

受信メールから添付ファイルをダウンロードする

1. read_email(uid=..., folder="INBOX") を呼び出す

2. attachments リストを確認する

3. attachment_index を使用して get_attachment(...) を呼び出す

get_attachment(...) は以下を返します：

• filename

• content_type

• size_bytes

• content_base64

送信メールに添付ファイルを含める

send_email(...) は attachments リストを受け入れます。

各アイテムは以下のいずれかになります：

{"path": "/path/to/file.pdf"}

{"filename": "note.txt", "content_text": "hello from MCP"}

{"filename": "report.pdf", "content_base64": "JVBERi0x...", "content_type": "application/pdf"}

送信済みフォルダの動作

SMTP送信が成功した後、同じMIMEメッセージがIMAPの送信済みフォルダに追加されます。

デフォルトのフォルダ名は以下の通りです：

Sent

メールボックスで異なるIMAPフォルダ名を使用している場合は、上書き可能です：

export SENT_FOLDER="Sent"
# or
export MAILBOX_SENT_FOLDER="Sent"

送信済みメールが表示されない場合は、まず list_folders() を実行し、メールボックスから返された正確なフォルダ名を使用してください。

ファイル

• server.py — MCPツールの定義とトランスポートの起動

• mail_ops.py — IMAP/SMTPの実装

• requirements.txt — Pythonの依存関係

環境変数

必須：

export MAILBOX_EMAIL="you@example.com"
export MAILBOX_PASSWORD="your-app-password"

オプションのプロバイダー設定：

export IMAP_HOST="imap.yandex.com"
export IMAP_PORT="993"
export SMTP_HOST="smtp.yandex.com"
export SMTP_PORT="465"

オプションの送信済みフォルダ設定：

export SENT_FOLDER="Sent"

オプションのMCPサーバー設定：

export MCP_TRANSPORT="stdio"
export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"

利便性のためにエイリアスもサポートされています：

export YANDEX_EMAIL="you@yandex.ru"
export YANDEX_APP_PASSWORD="..."

インストール

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

stdioでローカル実行

python server.py

これは、プロセスを直接起動するローカルMCPクライアントに適したモードです。

ChatGPT Webアプリ用に実行

ChatGPT Webには公開HTTPS MCPエンドポイントが必要です。サーバーをHTTPモードで起動します：

python server.py --transport streamable-http --host 0.0.0.0 --port 8000

その後、公開HTTPSトンネルまたはリバースプロキシを通じてそのポートを公開し、生成されたMCP URLをChatGPTに登録します。

公開されているツール

list_folders()

利用可能なIMAPフォルダを一覧表示します。

search_emails(folder="INBOX", text=None, unseen_only=False, since_date=None, limit=30)

IMAPの条件でメッセージを検索します。

以下のような項目を返します：

• uid

• subject

• from

• to

• date

• flags

• size_bytes

read_email(uid, folder="INBOX")

既読にせずにメッセージ全体を取得します。

以下を返します：

• デコードされたヘッダー

• message_id

• in_reply_to

• references

• attachments

• body_plain

• body_html

get_attachment(uid, folder="INBOX", attachment_index=None, filename=None)

単一の添付ファイルを取得し、base64形式で返します。

send_email(...)

SMTP経由でメッセージを送信します。

重要なパラメータ：

• reply_to_header — Reply-Toヘッダーを設定します

• in_reply_to — スレッドヘッダー

• references — スレッドヘッダー

• attachments — 添付ファイル仕様のオプションリスト

実際の返信には in_reply_to を使用し、通常は references も使用してください。

Yandexに関する注意点

Yandexの一般的なデフォルト設定は以下の通りです：

• IMAP: imap.yandex.com:993 (SSL/TLS経由)

• SMTP: smtp.yandex.com:465 (SSL/TLS経由)

メインアカウントのパスワードではなく、アプリパスワードを使用してください。

今後のアップグレード案

• インライン/埋め込み画像添付

• 添付ファイルサイズ制限とストリーミング

• 確認付きの移動/アーカイブ/削除ツール

• 環境変数ベースの認証ではなくOAuthへの対応

• モック化されたIMAP/SMTPバックエンドを使用したテスト