MCP Email Server

MCP Email Server

メール操作（TLS を使用した POP3/SMTP）向けの Model Context Protocol（MCP）サーバーです。Claude のような LLM がメールの閲覧、送信、管理を行えます。

クイックスタート

方法 1：uvx（推奨）

クローンもインストールも不要です。GitHub から直接実行します。

uvx git+https://github.com/ptbsare/email-mcp-server \
  --email-user [email protected] \
  --email-pass yourpassword \
  --pop3-server pop.example.com \
  --smtp-server smtp.example.com

初回の実行時にパッケージがキャッシュされ、次回以降はすぐに起動します。

方法 2：クローンしてローカルで実行

git clone https://github.com/ptbsare/email-mcp-server
cd email-mcp-server
uv pip install -e .
uv run main.py --email-user [email protected] --email-pass yourpassword \
  --pop3-server pop.example.com --smtp-server smtp.example.com

方法 3：.env ファイル

作業ディレクトリに .env ファイルを作成します。

[email protected]
EMAIL_PASS=yourpassword
POP3_SERVER=pop.example.com
SMTP_SERVER=smtp.example.com

あとは、次のコマンドを実行するだけです。

uvx git+https://github.com/ptbsare/email-mcp-server
# or
uv run main.py

設定

設定の優先順位（高い順）

1. CLI 引数 — すべての設定より優先されます
2. 環境変数 — .env ファイルの設定より優先されます
3. .env ファイル — フォールバックのデフォルト値です

すべての設定オプション

CLI 引数	環境変数	必須	デフォルト	説明
--email-user	EMAIL_USER	✅	—	メールアドレス
--email-pass	EMAIL_PASS	✅	—	メールパスワード／アプリパスワード
--pop3-server	POP3_SERVER	✅	—	POP3 サーバーのホスト名
--pop3-port	POP3_PORT		995	POP3 SSL ポート
--smtp-server	SMTP_SERVER	✅	—	SMTP サーバーのホスト名
--smtp-port	SMTP_PORT		587	SMTP ポート（--smtp-use-ssl の場合は自動的に 465）
--smtp-use-ssl	SMTP_USE_SSL		false	STARTTLS の代わりに SMTP_SSL（ポート 465）を使用します
--log-level	LOG_LEVEL		INFO	ログレベル：DEBUG／INFO／WARNING／ERROR

例：設定ソースの組み合わせ

# CLI args only (no .env needed):
uv run main.py --email-user [email protected] --email-pass xxx \
  --pop3-server pop.gmail.com --smtp-server smtp.gmail.com

# .env file for credentials, CLI for servers:
# .env: [email protected] / EMAIL_PASS=xxx
uv run main.py --pop3-server pop.gmail.com --smtp-server smtp.gmail.com

# Env vars override .env:
[email protected] uv run main.py --pop3-server pop.gmail.com ...

Claude Desktop での使用

Claude Desktop の設定ファイルに追加します。

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%/Claude/claude_desktop_config.json

環境変数を使用する場合（設定内）：

{
  "mcpServers": {
    "email-mcp-server": {
      "command": "uvx",
      "args": ["git+https://github.com/ptbsare/email-mcp-server"],
      "env": {
        "EMAIL_USER": "[email protected]",
        "EMAIL_PASS": "your-app-password",
        "POP3_SERVER": "pop.example.com",
        "SMTP_SERVER": "smtp.example.com"
      }
    }
  }
}

CLI 引数を使用する場合（設定内）：

{
  "mcpServers": {
    "email-mcp-server": {
      "command": "uvx",
      "args": [
        "git+https://github.com/ptbsare/email-mcp-server",
        "--email-user", "[email protected]",
        "--email-pass", "your-app-password",
        "--pop3-server", "pop.example.com",
        "--smtp-server", "smtp.example.com"
      ]
    }
  }
}

ヒント： env セクションと CLI 引数は併用できます。CLI 引数が常に優先されます。

機能

• メールの取得： 設定可能な上限数で受信トレイのメールヘッダーを一覧表示します（pollEmails）
• メール全文の取得： ID を指定してメールの全内容を取得し、添付ファイルを自動的に抽出します（getEmailsById）
• メールの削除： ID を指定してメールを削除します（deleteEmailsById）
• メールの送信： プレーンテキスト（sendTextEmail）または HTML（sendHtmlEmail）形式のメールを、任意のファイル添付付きで送信します
• セキュアな接続： SSL 経由の POP3（ポート 995）、STARTTLS（ポート 587）または直接 SSL（ポート 465）を使用した SMTP
• 添付ファイルのサポート： ローカルファイルを添付ファイルとして送信できます。受信した添付ファイルは /tmp/email_mcp_attachments/<email_id>/ に自動保存されます

ツール

pollEmails(limit=50)

最近のメールヘッダーを一覧表示します（本文は含みません）。新しい順に返します。まずこれを使用して、getEmailsById／deleteEmailsById に渡す ID を取得してください。

パラメーター	型	デフォルト	説明
limit	int	50	返すメールの最大数。新しい順

戻り値： [{"id": int, "Subject": str, "From": str, "Date": str, "Message-ID": str}]

pollEmails(limit=10)   # 10 most recent
pollEmails()           # default 50

---

getEmailsById(ids)

pollEmails から取得した ID を指定して、メールの全内容（ヘッダー＋本文）を取得します。添付ファイルは /tmp/email_mcp_attachments/<id>/ に自動保存されます。

パラメーター	型	必須	説明
ids	list[int]	✅	pollEmails() で取得したメール ID。例：[1, 3, 5]

戻り値： [{"id": int, "headers": dict, "body": str, "attachments": [{"filename": str, "local_path": str, "size": int, "content_type": str}]}]

getEmailsById(ids=[1, 3, 5])

---

deleteEmailsById(ids)

ID を指定してメールを完全に削除します。元に戻せません。 先に pollEmails を呼び出してください。

パラメーター	型	必須	説明
ids	list[int]	✅	pollEmails() で取得したメール ID。例：[1, 2, 3]

戻り値： {"deleted": [int], "failed": {"id": "error msg"}}

deleteEmailsById(ids=[1, 2, 3])

---

sendTextEmail(toAddresses, subject, body, attachments=None)

プレーンテキストのメールを送信します。添付ファイルには、["/tmp/file.pdf"] のようなローカルファイルパスのリストを指定します。

Parameter	Type	Required	Default	Description
toAddresses	list[str]	✅	—	宛先。例：["[email protected]"]
subject	str	✅	—	件名
body	str	✅	—	プレーンテキストの本文
attachments	list[str]		None	ローカルファイルパス。例：["/tmp/report.pdf"]

戻り値： {"status": "success"}

sendTextEmail(
    toAddresses=["[email protected]"],
    subject="Hello",
    body="Hi Alice!",
    attachments=["/tmp/report.pdf"]
)

---

sendHtmlEmail(toAddresses, subject, body, attachments=None)

HTML メールを送信します。添付ファイルには、["/tmp/file.png"] のようなローカルファイルパスのリストを指定します。

Parameter	Type	Required	Default	Description
toAddresses	list[str]	✅	—	宛先。例：["[email protected]"]
subject	str	✅	—	件名
body	str	✅	—	HTML コンテンツ。例："<h1>Hi</h1><p>Hello!</p>"
attachments	list[str]		None	ローカルファイルパス。例：["/tmp/chart.png"]

戻り値： {"status": "success"}

sendHtmlEmail(
    toAddresses=["[email protected]"],
    subject="Report",
    body="<h1>Report</h1><p>Sales up <b>20%</b>.</p>",
    attachments=["/tmp/chart.png"]
)

---

開発環境のセットアップ

前提条件

• Python 3.12+
• uv

手順

git clone https://github.com/ptbsare/email-mcp-server
cd email-mcp-server
uv pip install -e .
uv run main.py --help

重要な注意事項

• アプリパスワード： メールプロバイダーで 2FA を使用している場合は、EMAIL_PASS 用のアプリパスワードを生成してください
• メール ID： POP3 ID はセッションごとに異なります。getEmailsById() または deleteEmailsById() を呼び出す前に、pollEmails() を呼び出してください
• 添付ファイルの保存先： 受信した添付ファイルは /tmp/email_mcp_attachments/<email_id>/ に保存されます
• セキュリティ： .env ファイルは絶対にコミットしないでください。すでに .gitignore に登録されています
• 設定の優先順位： CLI 引数 > 環境変数 > .env ファイル

プロジェクト構成

email-mcp-server/
├── main.py              # MCP server entry point (all logic)
├── pyproject.toml       # Package config & dependencies
├── uv.lock              # Dependency lock file
├── .env                 # Credentials (create your own)
├── .gitignore
└── README.md

ライセンス

MIT