better-email-mcp

メール

mcp-name: io.github.n24q02m/better-email-mcp

AI エージェント向けの IMAP/SMTP メール機能 — アカウント間でメールの読み取り、送信、整理、添付ファイルの管理ができます。

n24q02m の関連プロジェクト（クリックして展開）

| プロジェクト | キャッチコピー | タグ | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | ピア AI エージェントが共有フォルダーでチャットします — 人間による中継も、オーケストレーターも不要です。... | ツール | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | トークン効率の高いコードレビュー向けナレッジグラフ — セマンティック検索と呼び出し... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | .driveignore フィルターを使った Google Drive の双方向同期 — rclone エンジン、Windows トレイ | ツール | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | AI エージェント向け IMAP/SMTP メール — 読み取り、送信、フォルダーの整理、添付ファイルの管理... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Godot Engine 向け複合 MCP サーバー — AI 支援によるゲーム開発のための 17 個の複合ツール... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | AI エージェント向け Markdown ファーストの Notion — ページ、データベース、ブロック、コメント... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | リリース安全性ガードを標準搭載した python-semantic-release のドロップインフォーク（オープ... | ツール | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | AI エージェント向け Telegram — 両方のボ...でのメッセージ、チャット、メディア、連絡先... | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP サーバー（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | n24q02m MCP サーバー向け Claude Code プラグインマーケットプレイス — ウェブ検索をインストール... | マーケットプレイス | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | AI エージェント向け画像・動画の理解と生成 — Gemini、Op...に対応... | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | batchexecute API を介して Jules タスクを一括操作する Chrome 拡張機能 — ... | ツール | | [mcp-core](https://github.com/n24q02m/mcp-core) | MCP サーバー構築のための共有基盤 — Streamable HTTP トランスポート、OAuth... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | ハイブリッド検索と埋め込み同期による永続的な AI メモリ。オープン、無料、無制限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | ONNX Runtime と GGUF による軽量な Qwen3 テキスト埋め込みと再ランキング | ライブラリ | | [skret](https://github.com/n24q02m/skret) | サーバー不要のシークレット管理。 | CLI | | [tacet](https://github.com/n24q02m/tacet) | ナレッジ...にわたって LLM コストを償却する、自己蒸留型のニューロシンボリックカスケード... | ツール | | [web-core](https://github.com/n24q02m/web-core) | 検索、スクレイピング、HTTP セキュリティ、スト...向けの共有ウェブインフラストラクチャパッケージ... | ライブラリ | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | AI エージェント向けオープンソース MCP サーバー：ウェブ検索、コンテンツ抽出、ライブラリ... | MCP |

目次

• 機能
• インストール
• CLI
• Smithery
• ドキュメント
• ツール
• 比較
• リモート（HTTP モード）
• Outlook OAuth デバイスコード（HTTP モード）
• 設定
• セキュリティ
• ソースからビルド
• 信頼モデル
• ライセンス

## 機能

• 複数アカウント対応 -- 6つ以上のメールアカウント（Gmail、Outlook、Yahoo、iCloud、Zoho、ProtonMail、カスタム IMAP）を管理できます
• アプリパスワード -- ほとんどのプロバイダーでは OAuth2 の設定は不要です。クローンして1分で実行できます
• 4つの複合ツール（および help）-- 検索、読み取り、送信、返信、転送、整理、認証情報の状態確認を1回の呼び出しで実行できます
• 自動検出 -- メールアドレスからプロバイダー設定を検出し、カスタム IMAP ホストにも対応します
• スレッド対応 -- 返信や転送時に In-Reply-To ヘッダーと References ヘッダーを維持します
• 段階的なトークン最適化 -- 圧縮された説明、必要に応じて呼び出す help ツール、および MCP リソース

インストール

このサーバーは2つのモードで動作します。stdio（デフォルト。シングルユーザーで、認証情報は環境変数から取得）と HTTP（オプトイン。シングルユーザーで、ベアラートークンを使用）です。stdio の場合は、MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/email@latest"],
      "env": {
        "EMAIL_CREDENTIALS": "[email protected]:app-password"
      }
    }
  }
}

パッケージは @n24q02m/email です（以前の名称は @n24q02m/better-email-mcp。旧パッケージは最終リリース後に更新を停止します）。MCP Registry の ID は io.github.n24q02m/better-email-mcp のままです。また、従来の better-email-mcp コマンドは email のエイリアスとして引き続き使用できます。

複数のアカウントはカンマ区切りで指定します：[email protected]:pass1,[email protected]:pass2。すべての環境変数については設定を、ホスト型のマルチユーザーサーバーの実行についてはリモート（HTTP モード）を参照してください。

ほとんどのプロバイダーではアプリパスワードを使用します（OAuth の設定は不要です）。Outlook／Hotmail／Live では、HTTP モードで同梱の OAuth デバイスコードフローを使用します。設定（IMAP／SMTP のホスト、ポート）はメールドメインから自動検出されます。

インストールマトリックス

クライアント	インストール
Claude Code	/plugin marketplace add n24q02m/claude-plugins + /plugin install better-email-mcp@n24q02m-plugins（stdio。EMAIL_CREDENTIALS の入力を求められます）、または .mcp.json／クライアント設定に mcpServers エントリを追加
Codex CLI	~/.codex/config.toml に [mcp_servers.email] ブロックを追加（stdio の command／args または HTTP の type／url）
OpenCode	opencode.json に mcpServers ブロックを追加
Cursor／Windsurf／Gemini CLI／その他の MCP クライアント	クライアントの設定に mcpServers JSON を追加。上記の例と同じ形式です

クライアントごとの詳しい手順：mcp.n24q02m.com/servers/better-email-mcp/setup/。

CLI

このパッケージには email というバイナリが含まれています（npx @n24q02m/email で実行）。従来の名称 better-email-mcp でもインストールされます。引数を指定せずに実行すると、stdio 経由で MCP サーバーが起動します。また、1つのフラグと1つのサブコマンドを受け付けます。

呼び出し	説明
email	stdio 経由で MCP サーバーを起動します（デフォルト）。EMAIL_CREDENTIALS、または EMAIL_USER と EMAIL_APP_PASSWORD から認証情報を読み込みます
email --http	HTTP（シングルユーザー、ベアラートークン）モードでサーバーを起動します。MCP_TRANSPORT=http または TRANSPORT_MODE=http と同じです
email auth [outlook] <email> [--client-id=<id>]	OAuth2 デバイスコードフローで Outlook／Hotmail／Live アカウントを認証します。トークンは ~/.better-email-mcp/tokens.json に保存されます。outlook プロバイダーの位置引数は省略可能です（OAuth2 プロバイダーは email に1つのみです）。セルフホストする Azure AD アプリの場合、--client-id で OUTLOOK_CLIENT_ID を上書きできます
email logout [<email>]	ローカルに保存された Outlook トークンを削除します。保存されたすべてのトークンを削除するには <email> を省略します

# stdio server (normally launched by your MCP client, not by hand)
EMAIL_CREDENTIALS="[email protected]:app-password" npx @n24q02m/email

# HTTP multi-user server
npx @n24q02m/email --http

# One-off Outlook OAuth device-code sign-in
npx @n24q02m/email auth [email protected]

# Sign out of a single account (or omit the email to clear all)
npx @n24q02m/email logout [email protected]

auth／logout は Outlook／Hotmail／Live のアドレスでのみ使用します。それ以外のプロバイダーでは、EMAIL_CREDENTIALS にアプリパスワードを指定します。HTTP の設定についてはリモート（HTTP モード）を参照してください。

Smithery

Smithery の設定（smithery.yaml）とともに公開されています。Smithery はビルド設定なしでサーバーを stdio 経由で実行します。認証情報は環境から取得します（設定を参照）。起動コマンドは次のとおりです。

startCommand:
  type: stdio
  commandFunction: |-
    (config) => ({ command: 'npx', args: ['-y', '@n24q02m/email'] })

ドキュメント

ドキュメント全文は mcp.n24q02m.com/servers/better-email-mcp/ をご覧ください：

• セットアップ -- Claude Code、Codex、Gemini CLI、Cursor、Windsurf、mcp.json のインストール方法

AI エージェントでインストール -- 以下を AI コーディングエージェントに貼り付けてください：

次の手順に従って MCP サーバー email をインストールしてください。 https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-email-mcp/setup-with-agent.md

ツール

公開ツール名の変更

公開ツール send は、action: new、reply、または forward を指定する messages に置き換えられます。 これは MCP N+2 標準に準拠しています。送信は messages ドメイン内のアクションであるため、独立した send エントリーを残すと、そのドメインが重複し、ツール一覧とヘルプトピックの項目が冗長になります。旧名称は直接削除され、互換性エイリアスはありません。

旧公開名	新公開名	理由	エイリアスの削除
send	messages（action: new | reply | forward）	N+2 のドメインツール規則：送信メールは messages メガツールに含まれ、別個のアクションレベルのツールではありません。	Unreleased リリースで直接削除。エイリアスなし

ツール	アクション	説明
messages	search、read、mark_read、mark_unread、flag、unflag、move、archive、trash、new、reply、forward	メールの検索、読み取り、整理、作成、返信、転送
folders	list、status	メールボックスのフォルダー一覧、または対象を指定した IMAP STATUS メタデータの読み取り
attachments	list、download	メール添付ファイルの一覧表示とダウンロード
config	status、setup_status、setup_start、setup_reset、setup_complete、set、cache_clear	認証情報の状態とセットアップガイダンス、リセット、再解決、キャッシュのクリア
help	-	任意のツールのドキュメント全文を取得

MCP リソース

URI	説明
email://docs/messages	メッセージ操作リファレンス
email://docs/folders	フォルダー操作リファレンス
email://docs/attachments	添付ファイル操作リファレンス
email://docs/help	ドキュメント全文
email://docs/config	認証情報のセットアップと実行時設定のリファレンス

比較

各分野で、メール機能を直接の競合製品と比較します：

機能	email	email-mcp	Gmail-MCP-Server	mcp-mail-server
IMAP/SMTP（プロバイダー非依存）	対応	対応	非対応（Gmail API のみ）	対応
複数アカウント	対応（カンマ区切りの認証情報）	対応	非対応（単一のグローバル認証情報）	非対応（インスタンスごとに単一アカウント）
アプリパスワード	対応（OAuth のセットアップ不要）	対応	非対応（OAuth2 のみ）	対応
メールアドレスからの自動検出	対応	対応（8 プロバイダー）	該当なし（Gmail のみ）	非対応（ホスト／ポートの手動設定）
Outlook OAuth を同梱（ユーザーの Azure アプリ不要）	対応（デバイスコード、Thunderbird パターンのクライアント）	一部対応（OAuth2 XOAUTH2、実験的）	非対応（ユーザー提供の Google OAuth）	非対応
添付ファイル（一覧表示＋ダウンロード）	対応	対応	対応	対応
HTTP モード（単一ユーザー、ベアラートークン、セルフホスト可能）	対応	非対応（stdio のみ）	非対応（stdio のみ）	非対応（stdio のみ）

リモート（HTTP モード）

共有ベアラートークンで認証する、単一ユーザー向け HTTP サーバーとして実行します：

{
  "mcpServers": {
    "email": {
      "type": "http",
      "headers": { "Authorization": "Bearer <your-token>" },
      "url": "https://<your-host>/mcp"
    }
  }
}

セルフホスティング（HTTP モード）

単一ユーザーモード：共有ベアラートークンを 1 つ使用します。アカウントは環境変数または email auth outlook <address> で設定します：

export EMAIL_MCP_TOKEN_HASH='scrypt$...'  # required: the container binds 0.0.0.0 and refuses to start without it
export EMAIL_CREDENTIALS='[email protected]:app-password'
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e EMAIL_MCP_TOKEN_HASH \
  -e EMAIL_CREDENTIALS \
  -e HOME=/data \
  -v email-data:/data \
  n24q02m/email:latest

ハッシュは printf '%s' "$TOKEN" | email token hash で生成します。トークンは stdin から読み込まれ、argv に渡されることはありません。クライアントは生のトークンを Authorization: Bearer <token> として送信します。保存された Outlook トークンは /data/.better-email-mcp/ に格納され、/data ボリュームを保持すれば維持されます。

Docker Compose でのセルフホスト

このリポジトリには docker-compose.http.yml が含まれており、http イメージターゲットをビルドし、ホストのループバックインターフェースのみ（127.0.0.1:8082）で公開します。

export EMAIL_MCP_TOKEN_HASH='scrypt$...'   # required; see the note above
export EMAIL_CREDENTIALS='[email protected]:app-password'
docker compose -f docker-compose.http.yml up

サーバーには http://localhost:8082 からアクセスできます。他のマシンにもサービスを提供するには、同じホスト上でループバックポートの前に独自の TLS リバースプロキシを配置してください。ビルド済みのマルチアーキテクチャイメージは Docker Hub（n24q02m/email）と GHCR（ghcr.io/n24q02m/email）で公開されています。

Outlook OAuth デバイスコード

Outlook／Hotmail／Live アカウントでは OAuth2 デバイスコードを使用します。email auth outlook <address> を一度実行してください。初回使用時の手順は次のとおりです。

1. CLI にデバイスコードと Microsoft のログイン URL が表示されます
2. ブラウザーで URL を開き、コードを入力します
3. サインインしてアプリを承認します
4. トークンは ~/.better-email-mcp/tokens.json に保存されます（POSIX ではモード 0600 で作成されます）。Docker ではこのパスは /data/.better-email-mcp/tokens.json です。

OAuth ではバンドルされた Azure のパブリッククライアント（d56f8c71-9f7c-43f4-9934-be29cb6e77b0、Thunderbird パターン）を使用します。ユーザー側で Azure に登録する必要はありません。

stdio モードでは、Outlook アカウントには代わりにアプリパスワードを使用します（Outlook のアカウント設定 → セキュリティ → 高度なセキュリティ オプション → アプリ パスワード）。

設定

mise の設定を自動的に信頼するには、ユーザーレベルの設定ファイル ~/.config/mise/config.toml で trusted_config_paths を設定してください。このプロジェクトの .mise.toml には追加しないでください。

変数	必須	デフォルト	説明
EMAIL_CREDENTIALS	はい（stdio）	-	メール認証情報。アカウントごとに email:app-password を指定し、複数アカウントの場合はカンマで区切ります。IMAP ホスト／ポートのカスタム指定も可能です：email:password:imap_host:imap_port
EMAIL_USER	代替（stdio、単一アカウント）	-	メールアドレス。EMAIL_APP_PASSWORD とともに、EMAIL_CREDENTIALS のフィールド単位の代替として使用され、起動時に EMAIL_CREDENTIALS に統合されます
EMAIL_APP_PASSWORD	代替（stdio、単一アカウント）	-	アプリパスワード（Gmail／Yahoo／iCloud）または Outlook アプリパスワード。EMAIL_USER とともに使用します
PORT	いいえ	0（OS による割り当て）	サーバーポート（http モード）。固定ポートにバインドするには、明示的に設定します（例：8080）
HOST	いいえ	-	バインドアドレス（http モード）
EMAIL_MCP_TOKEN_HASH	いいえ（http。ループバックにバインドしない場合は必須）	-	共有ベアラートークンの scrypt ハッシュ。email token hash で生成します。これがない場合、HTTP はループバック上でのみ、認証なしで実行されます
OUTLOOK_CLIENT_ID	いいえ	d56f8c71-9f7c-43f4-9934-be29cb6e77b0（バンドルされたパブリッククライアント）	セルフホストの Outlook OAuth2 用に、バンドルされた Azure AD パブリッククライアントを上書きします（または auth で --client-id=<id> を指定すると、この環境変数より優先されます）
OUTLOOK_EMAIL	いいえ	-	Microsoft のデバイスコード応答にメールフィールドが含まれない場合の回避策
OUTLOOK_TENANT	いいえ	consumers（stdio／CLI）、common（http デバイスコード）	サインイン先の Microsoft ディレクトリ。デバイスコードとトークン更新の両方のエンドポイントに使用されます。職場または学校のメールボックス（Entra ID）には common を設定するか、テナント GUID／検証済みドメインを指定してディレクトリを固定します
OUTLOOK_SCOPES	いいえ	https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/SMTP.Send offline_access	スペース区切りのスコープ一覧です。読み取り専用でデプロイする場合は範囲を狭めます（例：SMTP.Send を削除）。少ないスコープで同意された許可は、完全な一覧に対して更新できません
OUTLOOK_EXTRA_DOMAINS	いいえ	-	outlook.com／hotmail.com／live.com に加えて、OAuth に振り分けるドメインをカンマ区切りで指定します。独自ドメインの Microsoft 365 メールボックスに必要です。指定しない場合、パスワードアカウントとして扱われます

複数アカウント

[email protected]:pass1,[email protected]:pass2,[email protected]:pass3

カスタム IMAP ホスト

# Custom hostname (default port 993, implicit TLS)
[email protected]:password:imap.custom.com

# Custom hostname with a custom port
[email protected]:password:imap.custom.com:1993

# Local IMAP proxy -- "localhost" is accepted as a host, even without a dot
[email protected]:password:localhost:1993

アカウントごとに独自のホストとポートを使用できます。993 以外のポートは、平文／STARTTLS として扱われます。これはローカル IMAP プロキシ（たとえば email-oauth2-proxy）で一般的な構成です。

Microsoft 365 の職場／学校アカウント

独自ドメインのアカウントを含め、Microsoft 365 組織のメールボックスは、コンシューマーディレクトリではなく Entra ID を通じてサインインします。また、Microsoft は 2024 年に Exchange Online の基本認証を無効にしたため、アプリパスワードは使用できません。次の 2 つの設定を行うと利用できます。

# Sign in against the directory that owns the mailbox
OUTLOOK_TENANT=common                      # or a tenant GUID / verified domain

# Route your own domain to OAuth instead of asking for a password
OUTLOOK_EXTRA_DOMAINS=company.com

OUTLOOK_TENANT は初回のサインインだけでなく、トークンの更新にも適用されます。職場／学校アカウントのトークンをコンシューマーディレクトリに対して更新すると、AADSTS7000012: The grant was obtained for a different tenant というエラーが発生します。

メールボックスに付与された権限が限定的な場合（たとえば、IMAP は許可されているが SMTP は許可されていない場合）は、OUTLOOK_SCOPES を合わせて設定してください。そうすれば、更新時に許可済みの範囲を超える権限が要求されません。

検索クエリ言語

クエリ	説明
UNREAD	未読メール
FLAGGED	スター付きメール
SINCE 2024-01-01	指定日以降のメール
FROM [email protected]	指定した送信者からのメール
SUBJECT meeting	件名に一致するメール
UNREAD SINCE 2024-06-01	複合フィルター

対応プロバイダー

プロバイダー	認証	送信済みへの保存
Gmail	アプリパスワード	自動（スキップ）
Yahoo	アプリパスワード	自動（スキップ）
iCloud/Me.com	アプリ固有のパスワード	自動（スキップ）
Outlook/Hotmail/Live	OAuth2（デバイスコード）	IMAP APPEND
Zoho	アプリパスワード	IMAP APPEND
ProtonMail	ProtonMail Bridge	IMAP APPEND
カスタム	email:pass:imap.host 経由	IMAP APPEND

セキュリティ

• 認証情報のサニタイズ — エラーメッセージにパスワードが漏れることはありません
• アプリパスワード — 通常のパスワードではなく、アプリ固有のパスワードを使用します
• トークンの保存 — Outlook OAuth トークンは POSIX ではモード 0600 で書き込まれます（Windows では適用されません）
• IMAP の検証 — 検索クエリは実行前に検証されます

ソースからビルドする

git clone https://github.com/n24q02m/email.git
cd email
bun install
bun run dev

信頼モデル

認証情報は単一ユーザー用です。サーバーを実行するユーザー（stdio の場合は OS ユーザー）が認証情報を読み取れます。保存方法はデプロイモードによって異なります。

モード	保存場所	暗号化	データを読み取れるユーザー
HTTP（Docker）	環境変数（EMAIL_CREDENTIALS）および $HOME/.better-email-mcp/tokens.json に保存された Outlook トークン（/data ボリューム）	トークン：プレーンな JSON、POSIX ファイルモード 0600	サーバーの運用者
stdio	環境変数、~/.better-email-mcp/tokens.json に保存された Outlook トークン。以前のリリースのレガシーな config.enc も引き続き読み込まれます	トークン：プレーンな JSON、POSIX ファイルモード 0600	自分の OS ユーザーのみ

ライセンス

Apache-2.0 — LICENSE を参照してください。