email-mcp

Email MCP Server

IMAP と SMTP を介して包括的なメール機能を提供する、MCP（Model Context Protocol）サーバーです。

AI アシスタントが複数のアカウントにわたってメールの閲覧、検索、送信、管理、スケジュール設定、分析を行えるようにします。OAuth2 対応（実験的）、メールのスケジュール設定、カレンダー情報の抽出、分析、プロバイダーに応じたラベル管理、AI による振り分け機能を備えたリアルタイム IMAP IDLE ウォッチャー、クリップボードへのコピー機能を備えた即時認証コード取得、カスタマイズ可能なプリセットと静的ルール、ガイド付きセットアップウィザードを備え、MCP プロトコル経由で 52 個のツール、7 個のプロンプト、6 個のリソースを提供します。

MCP TypeScript SDK v2（仕様リビジョン 2026-07-28）を基盤とし、ローカルクライアント向けには stdio、ネットワーク経由のアクセスには Streamable HTTP で動作します。既存の stdio 設定は変更せずに引き続き使用できます。

主な機能

目次

• 主な機能
• セキュリティ
• 背景
• インストール
• 使用方法
• API
• ロードマップ
• メンテナー
• コントリビューション
• ライセンス

セキュリティ

• すべての接続で TLS/STARTTLS 暗号化を使用します
• パスワードがログに記録されることはありません。監査証跡には認証情報を含めずに操作を記録します
• トークンバケット方式のレートリミッターで不正利用を防止します（アカウントごとに 1 つのバケットを使用し、グローバルな rate_limit を共有します）
• Gmail および Microsoft 365 向けの OAuth2 XOAUTH2 認証に対応しています（実験的）
• 添付ファイルのダウンロードは、base64 エンコードを含めて 5 MB に制限されています

背景

ほとんどの MCP メール実装が提供するのは、基本的な閲覧と送信のみです。このサーバーは、AI アシスタント向けのフル機能のメールクライアントを目指し、メールの閲覧、作成、管理、スケジュール設定、分析というライフサイクル全体を、単一の MCP サーバーから扱えるようにします。

主な設計上の決定事項：

• XDG 準拠の設定 — TOML を ~/.config/email-mcp/config.toml に保存
• 複数アカウント — 複数の IMAP/SMTP アカウントを同時に操作
• 階層化されたサービス — テスト容易性のため、ビジネスロジックを MCP の接続処理から分離
• プロバイダーの自動検出 — Gmail、Outlook、Yahoo、iCloud、Fastmail、ProtonMail、Zoho、GMX

インストール

Node.js ≥ 24 が必要です。

# Run directly (no install needed)
npx @codefuturist/email-mcp setup
# or
pnpm dlx @codefuturist/email-mcp setup

# Or install globally
npm install -g @codefuturist/email-mcp
# or
pnpm add -g @codefuturist/email-mcp

npm のグローバルプレフィックスが root 所有のディレクトリ（システムの Node インストールでよく見られます）の場合、npm install -g は EACCES エラーで失敗します。上記の npx／pnpm dlx 形式なら、グローバルに何もインストールしないため、この問題を完全に回避できます。永続的なグローバルインストールを行う場合は、sudo に頼るのではなく npm のプレフィックスを修正してください（npm config set prefix ~/.npm-global を実行して PATH に追加するか、nvm／fnm／volta などの Node バージョンマネージャーを使用してください）。root として npm install -g を実行すると、ユーザー所有の node_modules ツリーに root 所有のファイルが混在することが多く、次回のグローバルインストールで、さらに原因を特定しにくい権限エラーが発生します。

Homebrew（ネイティブバイナリ）

Node.js の実行時依存がない、ビルド済みの依存関係不要バイナリです。codefuturist tap から入手できます。

brew install codefuturist/tap/email-mcp

安定版リリースごとに cask として公開されます。macOS（arm64 + x64）および Linuxbrew ≥ 4.3（バイナリ専用 cask）で動作します。

ネイティブバイナリ（Bun）

依存関係不要の単一バイナリ（最小化済み、バイトコード事前コンパイル済み、コールドスタート約 32 ms、実行時に Node.js 不要）は、Bun でコンパイルできます。

bun run build:binary          # native binary → build/email-mcp
cp build/email-mcp ~/.local/bin/

bun run build:binaries        # release matrix: darwin-arm64/x64, linux-x64/arm64,
                              # windows-x64 → build/release/*.{tar.gz,zip} + sha256 checksums

各リリースのビルド済みバイナリは、一般的なすべてのプラットフォーム向けに GoReleaser Pro（.goreleaser.yaml）を使って CI でビルドされます。Linux glibc + musl、macOS、Windows に対応し、Bun がサポートする場合はそれぞれ x64 + arm64 も対象です。来歴証明 attestation 付きで（gh attestation verify <asset> --repo codefuturist/email-mcp で検証できます）、GitHub リリースとともに公開されます。mise からインストールできます：mise use -g ubi:codefuturist/email-mcp。

公開済みの npm パッケージから、同じバイナリをローカルでビルドすることもできます（チェックアウトは不要です。実行時の imapflow TLS 修正を含む ≥ 0.5.1 が必要です。旧バージョンではリポジトリの pnpm パッチが必要です）。通常の bun add -g シムは、シバンに従って dist/main.js を node で実行するため、約 11 ms のコールドスタートを実現するにはコンパイル手順が必要です。

bun add -g @codefuturist/email-mcp
bun build --compile --minify --bytecode \
  "${BUN_INSTALL:-$HOME/.bun}/install/global/node_modules/@codefuturist/email-mcp/dist/main.js" \
  --outfile ~/.local/bin/email-mcp

インストール済みのバイナリは自動的に最新状態を保ちます：email-mcp update は最新リリースを確認し、確認操作、リリースのチェックサムファイルとの sha256 検証、および（gh CLI がある場合は）来歴証明 attestation の検証を行った後、バイナリをアトミックに置き換えます。--check は確認のみを行います（終了コード 1 = 更新あり）。--yes を指定すると、スクリプトでプロンプトを省略できます。npm および mise で管理されているインストールは識別され、上書きされる代わりに npm install -g …@latest／mise upgrade を案内します。

バイナリから server install を実行すると、launchd のログイン項目がそのバイナリを参照するようになります。バンドルされた imapflow パッチ（patches/）が必要です。IP ホストの場合、imapflow は tls.connect に servername: false を渡しますが、Bun の厳格な node:tls はこれを拒否します。

Docker

Node.js は不要で、Docker のみで動作します。

# Latest stable release
docker pull ghcr.io/codefuturist/email-mcp:latest

# Pin to an exact version (immutable)
docker pull ghcr.io/codefuturist/email-mcp:0.2.3

# Auto-update patches within a minor version
docker pull ghcr.io/codefuturist/email-mcp:0.2

# Track a major version (won't cross breaking-change boundary)
docker pull ghcr.io/codefuturist/email-mcp:0

# Pin to an exact git commit (immutable, CI traceability)
docker pull ghcr.io/codefuturist/email-mcp:sha-abc1234

# Or build from source
docker build -t ghcr.io/codefuturist/email-mcp .

タグの規則： タグには Docker エコシステムの標準に合わせて、プレフィックス v のないセマンティックバージョンを使用します（例：node:24、nginx:1.25）。latest タグは安定版リリースでのみ更新され、プレリリースでは更新されません。

注意： デフォルトでは、サーバーは stdio トランスポートを使用します。設定はあらかじめホスト上で作成し（npx @codefuturist/email-mcp setup を実行するか、手動で作成してください）、コンテナにマウントする必要があります。

使用方法

セットアップ

# Add an email account interactively (recommended)
# On macOS and Linux this offers to store the password in the OS keychain,
# so config.toml only carries a `keychain:<account>` reference.
email-mcp account add

# Or use the legacy alias
email-mcp setup

# Or create a template config manually
email-mcp config init

セットアップウィザードはサーバー設定を自動検出し、接続をテストして設定を保存し、MCP クライアント設定スニペットを出力します。

接続テスト

email-mcp test            # all accounts
email-mcp test personal   # specific account

MCP クライアントの設定

以下のスニペットでは、ローカルのデスクトップクライアントに最適なデフォルトの stdio トランスポートを使用します。Streamable HTTP を使ったネットワーク経由またはリモートアクセスについては、下記の Streamable HTTP（ネットワーク経由） をご覧ください。

推奨 — ガイド付きインストーラーを使用する（Claude Desktop、Cursor、Windsurfを自動検出します。VS Codeでは、下記の手動設定用スニペットを使用してください）：

email-mcp install

または、以下のスニペットを使って手動で追加します。

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"]
    }
  }
}

{
  "servers": {
    "email": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "email": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@codefuturist/email-mcp", "stdio"]
      }
    }
  }
}

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"]
    }
  }
}

{
  "context_servers": {
    "email": {
      "command": {
        "path": "npx",
        "args": ["-y", "@codefuturist/email-mcp", "stdio"]
      }
    }
  }
}

[[mcp_servers]]
name = "email-mcp"
transport = "stdio"
command = "npx"
args = ["-y", "@codefuturist/email-mcp", "stdio"]

[[mcp_servers]]
name = "email-mcp"
transport = "stdio"
command = "npx"
args = ["-y", "@codefuturist/email-mcp", "stdio"]
env = { "EMAIL_ACCOUNTS" = "<your-accounts-json>" }

docker run --rm -i \
  -v ~/.config/email-mcp:/home/node/.config/email-mcp:ro \
  -v email-mcp-state:/home/node/.local/state/email-mcp \
  -v email-mcp-cache:/home/node/.cache/email-mcp \
  ghcr.io/codefuturist/email-mcp

{
  "mcpServers": {
    "email": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "~/.config/email-mcp:/home/node/.config/email-mcp:ro",
        "-v", "email-mcp-state:/home/node/.local/state/email-mcp",
        "-v", "email-mcp-cache:/home/node/.cache/email-mcp",
        "ghcr.io/codefuturist/email-mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@codefuturist/email-mcp", "stdio"],
      "env": {
        "MCP_EMAIL_ADDRESS": "[email protected]",
        "MCP_EMAIL_PASSWORD": "your-app-password",
        "MCP_EMAIL_IMAP_HOST": "imap.gmail.com",
        "MCP_EMAIL_SMTP_HOST": "smtp.gmail.com"
      }
    }
  }
}

stdio トランスポートは、MCP クライアントが接続を維持している間だけ動作します。つまり、IMAP ウォッチャー（および検証キャッチ）も接続が切れると停止します。email-mcp server を実行すると、iMCP と同様に、Streamable HTTP サーバーがバックグラウンドサービスとして動作します。

email-mcp server start              # detached on http://127.0.0.1:8080/mcp
email-mcp server start --port 3199  # any http flags pass through (--host, --token, …)
email-mcp server start --attach     # foreground instead (Ctrl-C stops)
email-mcp server status             # pid, address, /healthz, uptime
email-mcp server logs -n 50         # tail the daemon log
email-mcp server restart            # reuses the previous flags
email-mcp server stop               # graceful SIGTERM (add --force for SIGKILL)

バインド設定は設定ファイルに保存されるため、通常の server start は常に同じように動作します。

[settings.server]
host = "127.0.0.1"
port = 8080
path = "/mcp"
token = ""            # bearer token; empty = no auth (loopback only)
allowed_hosts = []    # Host-header allowlist for reverse proxies

優先順位は、CLI フラグ → EMAIL_MCP_HTTP_* 環境変数 → [settings.server] → デフォルトです。これは email-mcp http、server start、launchd のログイン項目のいずれにも適用されます。config edit server で対話形式で編集できます（トークンはマスクされて表示されます）。--insecure は意図的にフラグのみで指定でき、設定ファイルには保存できません。

ログイン時に起動（macOS）： email-mcp server install を実行すると、email-mcp http をフラグなしで実行する launchd ログイン項目（com.email-mcp.server、RunAtLoad + KeepAlive）が作成されます。再起動やクラッシュ後も、設定ファイルが唯一の設定元になります。server status は launchd モードを認識し、server uninstall はその項目を削除します。

状態は $XDG_STATE_HOME/email-mcp/daemon.json に保存され、ログはその隣の server.log に保存されます（5 MB でローテーション）。stop がシグナルを送るのは、コマンドラインからこのサーバーであることを確実に確認できたプロセスのみです（PID の再利用にも安全です）。HTTP 対応の MCP クライアントは http://127.0.0.1:8080/mcp に接続してください。ループバック以外のホストにバインドする場合は、引き続きトークンが必要です。

Streamable HTTP（ネットワーク接続）

デフォルトでは、サーバーは stdio 経由で MCP を通信します。ローカルのデスクトップクライアントに最適です（上記のスニペットを参照）。ネットワーク経由またはリモートからアクセスする場合は、代わりに Streamable HTTP サーバーとして実行してください。

email-mcp http --port 8080

MCP は http://127.0.0.1:8080/mcp で提供され、GET /healthz でヘルスチェックを実行できます。

フラグと環境変数

セキュリティ

• トークン認証 — トークンが設定されている場合、すべてのリクエストで Authorization: Bearer <token> を送信する必要があります。
• ループバック以外へのバインド制限 — ループバック以外のホスト（例：0.0.0.0）にバインドする場合、--insecure を指定しない限り、トークンなしでのバインドは拒否されます。--insecure は、上流のリバースプロキシで TLS と認証を終端する場合にのみ使用してください。
• DNS リバインディング対策 — Host ヘッダーは許可リスト（デフォルトではループバック名とバインドホスト）に照らして検証されます。公開ドメインを指定するには EMAIL_MCP_HTTP_ALLOWED_HOSTS を設定してください。プロキシ側ですでにチェックしている場合は、* を指定してチェックを無効にできます。

クライアントの設定

Streamable HTTP トランスポートに対応したクライアントの場合：

{
  "mcpServers": {
    "email": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

トークンを設定している場合、クライアントがカスタムヘッダーに対応していれば、Authorization: Bearer <token> ヘッダーを追加してください。

Docker

docker compose --profile http up

EMAIL_MCP_HTTP_TOKEN の設定が必要です。イメージではポート 8080 が EXPOSE されています。

CLI コマンド

email-mcp [command]

Commands:
  stdio                     Run as MCP server over stdio (default)
  http                      Run as MCP server over Streamable HTTP (networked)
  server start [--attach]   Start an always-on HTTP server (detached by default)
  server stop [--force]     Stop the detached server
  server status             Show pid, address, health, uptime (exit 1 if stopped)
  server restart            Stop and start again (reuses previous flags)
  server logs [-n N]        Show the last N daemon log lines
  server install            Install as macOS login item (launchd, survives reboots)
  server uninstall          Remove the login item and stop the server
  account list              List all configured accounts
  account add               Add a new email account interactively
  account edit [name]       Edit an existing account
  account delete [name]     Remove an account
  setup                     Alias for 'account add'
  test                      Test connections for all or a specific account
  open <id> [--print]       Open an email in the native mail client via its message: link
                            (macOS; --print or other platforms print the URL instead)
  install                   Register email-mcp with MCP clients interactively
  install status            Show registration status for detected clients
  install remove            Unregister email-mcp from MCP clients
  config show               Show config (passwords masked)
  config edit [section]     Interactive settings editor (general, server, send, attachments,
                            scheduler, watcher, verification, cache, hooks, alerts)
  config validate           Check syntax, schema, typo'd keys, and cross-setting consistency
  completion zsh|bash|fish  Print shell completion script (accounts and sections complete dynamically)
  config path               Print config file path
  config init               Create template config
  scheduler check           Process pending scheduled emails
  scheduler list            Show all scheduled emails
  scheduler install         Install OS-level scheduler (launchd/crontab)
  scheduler uninstall       Remove OS-level scheduler
  scheduler status          Show scheduler installation status
  cache status [--json]     Show cache size, contents, coverage and freshness
  cache clear [--account N] Delete cached mail/attachments and free the disk space
                            (--json supported by status, clear and verify)
  cache verify              Check the cache for corruption and reclaim orphaned files
  update [--check|--yes]    Self-update the binary to the latest GitHub release
  help                      Show help

シェル補完

# zsh (one line in ~/.zshrc)
source <(email-mcp completion zsh)

# bash
source <(email-mcp completion bash)

# fish
email-mcp completion fish > ~/.config/fish/completions/email-mcp.fish

すべてのコマンド、サブコマンド、フラグを補完できます。また、設定に登録されているアカウント名（email-mcp test <TAB>、account edit <TAB>）と、設定セクション（config edit <TAB>）も動的に補完されます。

ログの確認

バックグラウンドデーモンのログは $XDG_STATE_HOME/email-mcp/server.log に保存されます。ファイルを探す必要はなく、tail／追跡／フィルター表示に対応したビューアーで確認できます。

email-mcp logs                 # last 40 lines (colored by level)
email-mcp logs -n 200          # more lines
email-mcp logs -f              # live follow (Ctrl-C to stop)
email-mcp logs --level warn    # only WARN and ERROR (continuation lines kept)
email-mcp logs --grep imap     # only lines matching a substring
email-mcp logs -f --level error  # watch for errors as they happen

email-mcp server logs は同じオプションを使用するエイリアスです。パイプ出力時または NO_COLOR が設定されている場合、色は自動的に無効になります。systemd ホストでは journalctl --user -u email-mcp も利用できます。

CLI でのメールの読み取りと送信

MCP サーバーとして実行できるだけでなく、email-mcp は単独でも使えるメールクライアントです。MCP クライアントもコーディングも必要ありません。コマンドはデフォルトで最初に設定されたアカウントを使用します（別のアカウントを選ぶには --account <name> を渡します）。見やすく色付きのテーブルを表示し（パイプに渡す場合や NO_COLOR が設定されている場合は色が自動的に無効になります）、タブ補完にも対応しています（シェル補完を参照）。

email-mcp list                       # recent INBOX messages (● unread, ★ flagged, 📎 attachment)
email-mcp list --unread --limit 50   # filters
email-mcp list --mailbox Archive --search invoice
email-mcp read 42                    # full message (headers, body, attachment names + sizes)
email-mcp read 42 --mark-read
email-mcp search "from bank"         # IMAP search
email-mcp mailboxes                  # folders with unread/total counts
email-mcp flag 42                    # flag / --off to unflag
email-mcp attach 42 report.pdf ~/Downloads   # save an attachment
email-mcp delete 42 --yes            # delete (asks to confirm without --yes)

email-mcp reply 42 --body "on it" --all
email-mcp send --to [email protected],[email protected] --subject "Hi" --body "..." --attach ./file.pdf

すべてのコマンドで --help を使用できます。読み取りコマンド（list、read、search、mailboxes）では、jq にパイプで渡せる機械可読形式の出力を得るために --json を使用できます。

email-mcp list --json | jq '.items[] | {id, subject, from: .from.address}'
email-mcp read 42 --json | jq .attachments

送信／返信時の添付ファイルのサイズは、データがマシンの外部に送信される前に、設定された上限と照合して確認されます（認証情報を平文で保存しない方法については、アカウントのシークレットの保存を参照してください）。

設定

設定ファイルは $XDG_CONFIG_HOME/email-mcp/config.toml にあります（デフォルトは ~/.config/email-mcp/config.toml）。email-mcp config validate で検証できます（TOML の構文、スキーマ、入力ミスのあるキーと候補の提示、設定間の整合性を確認します。エラーがある場合は終了コード 1 を返すため、CI でも使いやすくなっています）。また、email-mcp config edit [section] で対話形式で編集できます。保存のたびに検証が行われ、以前のファイルは config.toml.bak にバックアップされます。注：プログラムによる保存では TOML のコメントが削除されます（バックアップにはコメントが残ります）。

[settings]
rate_limit = 10  # max emails per minute per account

[settings.send]
max_attachment_mb = 25  # global cap on the base64-encoded attachment total
save_to_sent = false    # file a copy of each sent message in the IMAP Sent folder

[settings.attachments]
auto_download = true  # save attachments locally when calendar events are created from emails

[settings.attachment_download]
# dir = "/data/attachments"  # unset (default) disables download_attachment's saveToDownloadDir
allowed_extensions = ["pdf", "png", "jpg", "jpeg", "webp", "tiff", "txt", "md", "doc", "docx", "odt", "xls", "xlsx", "csv"]
max_bytes = 26214400  # 25 MB

[[accounts]]
name = "personal"
email = "[email protected]"
full_name = "Your Name"
password = "keychain:personal"  # or "env:VAR", or a plaintext app password
# max_attachment_mb = 25  # optional per-account override (beats global + provider limits)
# sent_mailbox = "INBOX.Sent Messages"  # optional, see "Sent-folder copies" below
# save_to_sent = true                    # optional per-account override of the Gmail-skip guess

[accounts.imap]
host = "imap.gmail.com"
port = 993
tls = true

[accounts.smtp]
host = "smtp.gmail.com"
port = 465
tls = true
starttls = false
verify_ssl = true

[accounts.smtp.pool]
enabled = true
max_connections = 1
max_messages = 100

アカウントのシークレットの保存

password フィールド（および OAuth2 の client_secret／refresh_token）では、認証情報をファイルに平文で保存せずに済むよう、間接参照を指定できます。

設定ファイル自体は常に 0600（所有者のみ読み書き可能）で書き込まれ、.bak も同様です。

macOS Keychain（複数アカウント）： 各アカウントのシークレットを一度だけ保存します。

email-mcp account set-secret personal      # store a NEW secret (prompts; nothing echoed or in argv)
email-mcp account migrate-secret personal  # move an EXISTING plaintext password into the keychain

set-secret は値の入力を求めて保存します。migrate-secret は config.toml からアカウントの現在の平文パスワードを読み取り、キーチェーンに保存して検証した後、該当行を password = "keychain:personal" に書き換えます。どちらの方法でも、最終的に password = "keychain:personal" となります。各アカウントは共有の email-mcp サービスの下に個別の Keychain 項目として保存されるため、複数のアカウントを共存させられます。シークレットは起動時に security CLI を介して読み取られます。引数として渡されるのはサービス名とアカウント名だけで、シークレット自体は標準出力経由でのみ渡されます。

保存時、シークレットは ログインキーチェーン に格納され、暗号化されて macOS へのログインによってロック解除されます（Touch ID はログイン時に使用します）。実行中の email-mcp デーモンは起動時に一度だけシークレットを読み取ります。IMAP の再接続のたびに Touch ID を求めることはありません。無人で動作するバックグラウンドサービスでは、アクセスごとの生体認証プロンプトは意図的に使用していません。（アクセスのたびに Touch ID を求めるには、データ保護キーチェーンとネイティブヘルパーが必要です。）

OAuth2 (実験的)

注： OAuth2 のサポートは実験的です。トークンの更新やプロバイダー固有のフローについては、お使いの環境で追加のテストが必要になる場合があります。

[[accounts]]
name = "work"
email = "[email protected]"
full_name = "Your Name"

[accounts.oauth2]
provider = "google"            # or "microsoft"
client_id = "your-client-id"
client_secret = "your-client-secret"
refresh_token = "your-refresh-token"

[accounts.imap]
host = "imap.gmail.com"
port = 993
tls = true

[accounts.smtp]
host = "smtp.gmail.com"
port = 465
tls = true

[accounts.smtp.pool]
enabled = true
max_connections = 1
max_messages = 100

環境変数

単一アカウントの設定では、設定ファイルの値を上書きします。

ローカルキャッシュ

メールのローカル SQLite ミラー（および添付ファイル用のコンテンツアドレス方式ストア）から読み取りを提供します。保存先は ${XDG_CACHE_HOME:-~/.cache}/email-mcp/ です。メールの一覧表示、検索、再読み込みが高速になり、メールサーバーに接続できない場合でもメールを読めます。デフォルトで有効です。

キャッシュが正本になることはありません。 すべての行は IMAP から再取得できるため、削除しても再同期が必要になるだけで、メールが失われることはありません。XDG キャッシュの慣例に従い、いつでもディレクトリを削除できます。

キャッシュの内容の確認と容量の解放

email-mcp cache status          # size vs budget, per-mailbox coverage, last sync
email-mcp cache status --json   # same, for scripts
email-mcp cache clear           # free the space (asks first; mail is re-fetched)
email-mcp cache clear --account work --yes
email-mcp cache verify          # integrity check + reclaim orphaned files

cache status は、インデックスのサイズと添付ファイルのバイト数を個別に報告します。また、全文がキャッシュされているメッセージの数と、各メールボックスの照合からどれだけ時間が経過したかも示します。 check_health は同じ数値を AI クライアントに公開し、読み取りヒット率も示します。

鮮度の判定方法

まず正確性を優先します。「新着メールはある？」という質問に古い情報で答えるのは誤った回答だからです。 キャッシュからメールボックスを提供する前に、サーバーは直近 10 秒以内の照合結果を信頼するか、STATUS の往復通信を 1 回行い、サーバーの UIDVALIDITY／UIDNEXT／HIGHESTMODSEQ／MESSAGES とミラーに記録された値を比較します。これは条件付きリクエストに相当する IMAP の処理です。変更があれば、回答する前に再同期します（上限があり、上限を超えた場合はキャッシュの回答に stale と表示されます）。サーバーに接続できない場合は、キャッシュの回答に offline と表示されます。

メッセージ本文と添付ファイルは、同じ UIDVALIDITY／UID に対して不変です。そのため、一度保存すれば再検証せずに提供されます。このサーバー経由で行った書き込み（フラグの設定、移動、削除）は、影響を受けるメールボックスをただちに再同期します。これは CONDSTORE に対応していないサーバーでは特に重要です。対応していないサーバーでは、フラグの変更がそれ以外の方法では認識されないためです。

設定

容量の上限を超えると、再構築コストの低いものから順に削除されます。まず添付ファイル（最後に読み込まれたものから）、次にメール本文、最後に window_days より古いエンベロープの順です。一覧表示や検索に必要なため、エンベロープは可能な限り保持されます。

最新性だけでなく、網羅性も重要です。 キャッシュが一覧表示に応答できるのは、そのメールボックスについてサーバーが報告するすべてのメールがキャッシュに含まれている場合に限られます。window_days を 0 以外に設定すると、ミラーは一部の期間に限定されます。その場合、正確な total を報告したり、次のページがあるかを把握したりできないため、追いつくまで読み込みはライブパスにフォールバックします。そのため、エンベロープを削除するとメールボックスの同期ウォーターマークもクリアされます。次回の同期では網羅性が再構築され、目に見えない欠落が恒久的に残ることはありません。

保存データの保護

キャッシュされたメール（メール本文と添付ファイルの内容を含む）は、ユーザーのみが読み取り可能なディレクトリとファイル（0700／0600）に暗号化されずに保存されます。これはデスクトップメールクライアントの動作に準じています。推奨される保護方法は、ディスク全体の暗号化（FileVault、LUKS）です。本文や添付ファイルをディスクに一切保存したくない場合は、body_messages = 0 に設定すると、キャッシュにはメタデータのみが保存されます。

Gmail に関する注意：[Gmail]/All Mail を mailboxes に追加しないでください。Gmail では同じメールがすべてのラベルフォルダーに表示されるため、INBOX とともに All Mail をミラーリングすると、同じメールが二重に保存されます。

メールのスケジュール設定

スケジューラーは、階層型アーキテクチャでメールの予約配信を実現します。

1. MCP の自動チェック — サーバー起動時、および MCP サーバーの稼働中は 60 秒ごとにキューを処理します
2. CLI — email-mcp scheduler check で手動または cron ベースの処理を実行します
3. OS レベルのデーモン — email-mcp scheduler install で launchd（macOS）または crontab（Linux）を設定し、MCP サーバーとは独立して毎分実行します

重要 — 安定した配信にはデーモンのインストールが必要です。 デーモンがない場合、予約メールは AI クライアントがアクティブに接続している間のみ送信されます。 予約時刻にマシンが稼働している必要もあります。スリープ中または電源がオフの場合、 デーモンは次回の復帰または起動時に期限を過ぎたメールを処理します。送信に失敗した場合は、 failed としてマークされるまでに最大 3 回 再試行されます。

デーモンの設定

# Install (macOS launchd / Linux crontab — runs every minute)
email-mcp scheduler install

# Verify it's running
email-mcp scheduler status

# View pending / sent / failed scheduled emails
email-mcp scheduler list

# Trigger a manual check immediately
email-mcp scheduler check

# Remove the daemon
email-mcp scheduler uninstall

予約メールは ~/.local/state/email-mcp/scheduled/ に JSON ファイルとして保存され、ステータスベースのロック機構で管理されます。各エントリーには試行回数（最大 3 回）と最後に発生したエラーが記録されるため、scheduler list で失敗を確認できます。

リアルタイム監視と AI フック

IMAP IDLE ウォッチャーは、ツール接続とは別の永続的な IDLE 接続を使用して、設定済みのメールボックスをリアルタイムで監視します。新着メールが届くと、次の処理が行われます。

1. 静的ルール — 送信元／宛先／件名をパターン照合し、ラベルの適用、フラグ付け、既読化を即座に行います（AI は使用しません）
2. AI トリアージ — 残りのメールを、カスタマイズ可能なプリセットプロンプトを使った MCP サンプリングで分析します
3. 通知モード — AI トリアージが無効の場合は、ログ記録に切り替わります

config.toml で設定します。

[settings.watcher]
enabled = true
folders = ["INBOX"]
idle_timeout = 1740     # 29 minutes (IMAP spec max is 30)

[settings.hooks]
on_new_email = "triage" # "triage" | "notify" | "none"
preset = "inbox-zero"   # "inbox-zero" | "gtd" | "priority-focus" | "notification-only" | "custom"
auto_label = true       # apply AI-suggested labels
auto_flag = true        # flag urgent emails
batch_delay = 5         # seconds to batch before triage

# User context — appended to preset's AI prompt
custom_instructions = """
I'm a software engineer. Emails from @mycompany.com are always high priority.
Newsletters I read: TL;DR, Hacker Newsletter.
"""

# Static rules — run BEFORE AI, skip AI if matched
[[settings.hooks.rules]]
name = "GitHub Notifications"
match = { from = "*@github.com" }
actions = { labels = ["Dev"], mark_read = true }

[[settings.hooks.rules]]
name = "Newsletter Archive"
match = { from = "*@substack.com|*@buttondown.email" }
actions = { labels = ["Newsletter"] }

[[settings.hooks.rules]]
name = "VIP Contacts"
match = { from = "[email protected]|[email protected]" }
actions = { flag = true, labels = ["VIP"] }

プリセット

静的ルール

静的ルールでは、| を OR 区切り文字として使う glob 形式のパターン（*@github.com|*@gitlab.com）を使用します。match 内のすべての条件は AND で評価されます。最初に一致したルールが適用されます。

使用可能なアクション：labels（文字列配列）、flag（ブール値）、mark_read（ブール値）、alert（ブール値 — デスクトップ通知を強制します）。

アラート

緊急度に基づいて複数のチャネルに通知を振り分けます。チャットを見ていないときでも、重要なメールに注意を向けられます。すべてのチャネルはオプトイン方式で、デフォルトでは無効です。

[settings.hooks.alerts]
desktop = true              # OS-level notifications (macOS/Linux/Windows)
sound = true                # play sound for urgent emails
urgency_threshold = "high"  # minimum priority to trigger desktop alert
webhook_url = "https://ntfy.sh/my-email-alerts"  # optional: Slack, Discord, ntfy.sh, etc.
webhook_events = ["urgent", "high"]

対応プラットフォーム： macOS（osascript を介した通知センター）、Linux（notify-send）、Windows（PowerShell トースト通知）。npm 依存関係は不要で、OS 標準のコマンドを使用します。

プラットフォーム別の通知設定：

# Ubuntu / Debian
sudo apt install libnotify-bin pulseaudio-utils

# Fedora
sudo dnf install libnotify pulseaudio-utils

# Arch
sudo pacman -S libnotify

AI による設定： AI は実行時に通知の確認、テスト、設定を行えます。

• check_notification_setup — プラットフォームの対応状況を診断し、設定手順を表示します
• test_notification — テスト通知を送信して、すべてが動作することを確認します
• configure_alerts — デスクトップ通知、サウンド、しきい値、Webhook の有効／無効を切り替えます（設定ファイルへの保存は任意です）

Webhook ペイロード：

{
  "event": "email.urgent",
  "account": "work",
  "sender": { "name": "John CEO", "address": "[email protected]" },
  "subject": "Q4 Review Due Today",
  "priority": "urgent",
  "labels": ["VIP"],
  "rule": "VIP Contacts",
  "timestamp": "2026-02-18T11:30:00Z"
}

静的ルールでは、緊急度のしきい値に関係なく、alert = true によってデスクトップ通知を強制できます。

[[settings.hooks.rules]]
name = "VIP Contacts"
match = { from = "[email protected]" }
actions = { flag = true, alert = true, labels = ["VIP"] }

機能：

• 自動再接続 — 接続失敗時に指数バックオフ（1 秒 → 60 秒）を適用します
• バッチ処理 — 設定可能な遅延時間内に届いたメールをまとめ、AI 呼び出しを削減します
• レート制限 — サンプリング呼び出しは最大で毎分 10 回です
• グレースフルデグラデーション — クライアントがサンプリングに対応していない場合は、通知モードにフォールバックします
• リソースのサブスクリプション — 未読数について notifications/resources/updated をプッシュします

認証コード（OTP の即時取得）

認証コード（OTP／2FA）やサインイン用マジックリンクが記載されたメールが届くと、email-mcp は約 1～2 秒以内にコードをクリップボードにコピーし、通知を表示します —
「✅ GitHub からのコード 482913 — クリップボードにコピーしました。60 秒後に消去されます」。⌘V／Ctrl+V を押せば完了です。

検出は単なる数字の正規表現ではなく、スコアリング方式です（英語＋ドイツ語）。キーワードが近くにある場合（verification、Bestätigungscode、expires など）は加点し、否定的な文脈（注文番号、請求書、追跡番号、Zoom のパスコード、電話番号、価格、日付など）は減点します。クリップボードに誤ったコードが入るより、検出漏れのほうが安全です。

[settings.watcher]
enabled = true              # REQUIRED for ambient catching (IMAP IDLE push)

[settings.verification]
enabled = true              # on by default
auto_copy = true            # copy caught codes/links to the clipboard
confirm_copy = false        # ask (native dialog) before touching the clipboard
notify = true               # desktop notification on catch
copy_links = true           # also catch magic links (only when no code found)
link_action = "open"        # "open" = offer to open links in the browser, "copy" = clipboard
clear_after_seconds = 60    # conditional auto-clear (0 = never)
max_age_minutes = 10        # ignore stale messages (IDLE replays)
accounts = []               # limit to specific accounts (empty = all)
sender_allowlist = []       # e.g. ["*@github.com", "*@google.com"]
sender_denylist = []

確認優先モード： confirm_copy = true にすると、クリップボードに何かが書き込まれる前に、macOS のネイティブダイアログ（「GitHub からのコード 482913 — クリップボードにコピーしますか？」）が表示されます。サインインリンクには、デフォルトで 3 つのボタンがあるダイアログ（link_action = "open"）が表示されます。開くを選ぶとデフォルトのブラウザーでリンクが開き、コピーを選ぶとクリップボードにコピーされ、キャンセルを選ぶと何も起こりません。メールの内容からブラウザーを自動起動するとフィッシングの危険があるため、リンクを開く操作は必ず確認を求めます。通知なしでクリップボードにコピーするには、link_action = "copy" を設定してください。ダイアログは macOS 専用です（カレンダーの確認と同じ仕組みです）。それ以外の環境では、これらのモードは通知のみになります。

クリップボードの安全管理（macOS）： コードは JXA の osascript を使って org.nspasteboard.ConcealedType マーカー付きで書き込まれます。これは 1Password／Bitwarden が使用するものと同じ方式で、適切に動作するクリップボードマネージャー（Maccy、Paste など）には記録されません。自動消去は条件付きで行われます。クリップボードに取得した値が残っている場合に限り消去するため、その間にコピーした内容が上書きされることはありません。Linux では wl-copy／xclip を、Windows では PowerShell の Set-Clipboard を使用します（Windows には隠すための方式はありません）。npm 依存関係はありません。

エージェント向け： get_verification_code を呼び出すと、最新のコードをその場で取得できます。自動サインアップ中は wait_seconds = 30 を指定して呼び出すと、メールが届いてから数秒後にコードが返されます（監視機能を使う場合はイベント駆動、使わない場合は 5 秒間隔でポーリングします）。時間内に届かなかった場合は、ヒントとともに found: false が返されます — 再度呼び出してください。

セキュリティに関する注意： クリップボードは OS 内で共有される状態のため、コードが保存されている間は、どのアプリからも読み取ることができます（その時間は clear_after_seconds によって制限されます）。コード自体がサーバーログや監査ログに書き込まれることはありません。get_verification_code の結果には表示されますが、これはこのツールの目的です。緊急停止スイッチ：enabled = false（機能を無効化）または auto_copy = false（通知のみ）。環境変数による上書き：MCP_EMAIL_VERIFICATION_*（_ENABLED、_AUTO_COPY、_CONFIRM_COPY、_NOTIFY、_COPY_LINKS、_LINK_ACTION、_CLEAR_AFTER_SECONDS、_MAX_AGE_MINUTES、_ACCOUNTS、_SENDER_ALLOWLIST、_SENDER_DENYLIST）。

check_clipboard_setup を使うと、一連の処理を診断できます（安全なコピー → 読み戻し → 消去の一連のテストを行うには、test_write = true を追加してください）。

API

ツール（52）

構造化出力： list_emails、search_emails、get_email_status、list_mailboxes、get_verification_code は、人間が読めるテキストに加え、機械可読な結果（outputSchema と structuredContent）も返します。型付きツール出力を利用するクライアント向けです。

メール本文：HTML およびその他の形式

実際のメールのほぼすべては HTML です — あるメールボックスをサンプリングしたところ、169 件中 165 件が単一パートの text/html でした — そのため、読み取りツールはマークアップをそのまま返さず、変換します。

get_email、get_emails、get_thread では format を指定できます：

その他の形式は次のように処理されます。

• multipart/alternative — 両方のパートを取得するため、bodyText と bodyHtml の両方を利用できます。HTML側と同じ内容を保持するには小さすぎるプレーンテキストのパートは、「HTMLリーダーで表示してください」というプレースホルダーとみなされ、スキップされます。
• 複数のテキストパートを含む multipart/mixed — 順番に連結されるため、インライン画像の前後に分割されたメモ（Apple Mail）や、メッセージごとのダイジェストセクションが最初のパートだけに切り詰められることはありません。
• text/plain; format=flowed（RFC 3676）— ソフトな行折り返しが元に戻されるため、段落は72桁で強制改行された状態ではなく、段落として読めます。DelSp とスペーススタッフィングにも対応しています。
• インライン画像（cid:） — partId、contentId、inline を持つ添付ファイルとして一覧表示され、download_attachment の partId でダウンロードできます。送信時に埋め込むには、attachments に {path, cid, contentType} を渡し、<img src="cid:…"> として参照してください。
• バウンス（multipart/report）— 機械可読な message/delivery-status パートは、本文とは別に表示されます。
• カレンダー招待 — パートで宣言された文字セットを尊重し、extract_calendar / add_to_calendar で処理されます。
• 暗号化メール（S/MIME、PGP/MIME）— 復号されません。本文が空に見えるのではなく、その旨が明示されます。
• 添付メッセージ（message/rfc822）— 本文と誤認されることはありませんが、メッセージにほかのテキストが含まれない場合は本文として使われます（添付として転送したメール、ダイジェスト）。

添付ファイルのダウンロード先ディレクトリ。 download_attachment は通常、ファイルをBase64エンコードして返します（≤5 MB）。[settings.attachment_download] dir（または MCP_EMAIL_ATTACHMENT_DOWNLOAD_DIR）にディレクトリを設定し、saveToDownloadDir: true を渡すと、代わりにファイルをそのディレクトリに書き込み、そのパスを返します。大きなファイルや、添付ファイルを会話にインラインで含めず、ディスク上に保存したい場合に便利です。dir を設定するまではこのオプションは使用できず（呼び出しは失敗します）、デフォルトの保存先はありません。書き込まれるのは allowed_extensions に含まれるファイルのみです（デフォルトは一般的なドキュメント／画像形式です。上記の設定例を参照してください）。max_bytes でサイズ上限を設定できます。この上限はBase64の5 MB上限とは独立しています。書き込むファイル名を指定するには saveAs を渡してください（パス区切り文字を含まないファイル名のみ指定できます）。指定しない場合は、添付ファイル本来のファイル名がサニタイズされて使用されます。Dockerで実行する場合は、docker-compose.yml で次のように、ファイルを読み取る側と共有するマウント済みボリュームを dir に指定してください。

services:
  email-mcp:
    environment:
      MCP_EMAIL_ATTACHMENT_DOWNLOAD_DIR: /data/attachments
    volumes:
      - attachments:/data/attachments
  other-service:
    volumes:
      - attachments:/data/attachments:ro
volumes:
  attachments:

送信済みフォルダーへのコピー。 SMTPはメールを配信しますが、フォルダーへの保存は行いません。[settings.send] save_to_sent のデフォルトは false です。送信メールを自動保存しないIMAPホストでは有効にしてください。Gmailはサーバー側で送信メールを保存するため、IMAPサーバーが X-GM-EXT-1 機能を通知するアカウントでは、設定が有効でも自動的にスキップされます。コピーを保存すると、同じメールが二重に保存されるためです。アカウントごとの save_to_sent を設定すると、どちらの場合もこの判断を強制できます（true は常に保存、false はグローバル設定やGmailかどうかの推測にかかわらず保存しません）。

コピーにはサーバーが受け付けたものと同じ Message-ID が付き、\Seen フラグが設定されます。また、サーバーが \Sent としてマークしたフォルダーに保存されます（該当フォルダーがない場合は Sent という名前のフォルダーが作成されます）。送信済みと思われるフォルダーが複数あるメールボックスでは、実際に使われているフォルダーの横に残った Sent など、空のフォルダーが選ばれる場合があります。その場合は、list_mailboxes で報告される完全なパスをアカウントの sent_mailbox に設定してください。コピーからは Bcc が除外されます。MIMEコンポーザーが無条件に削除するためです。 ファイルへの保存に失敗しても、送信が失敗することはありません。メールはすでに送信されており、そうでないと伝えると重複送信を招くためです。ただし、その場合 send_draft はメッセージの唯一の残存コピーを削除せず、下書きを保持します。send_email、reply_email、forward_email、send_draft はすべて、結果の sentCopy フィールドで処理結果を報告します。値は {kind: "filed", path}、{kind: "skipped"}（設定がオフの場合、または Gmail 自身が保存する場合）、または {kind: "failed", error} です。

送信する HTML（html: true）は、生成されたプレーンテキスト版を含む multipart/alternative として送信されます。転送では元のメールを変換したテキストとして引用します。元の HTML も含めるには、forward_email に html: true を渡してください。

読み取り（14）

一括メールの分類

list_emails、search_emails、get_email、get_emails、get_thread は、 メーリングリストのメールや自動生成メールにマークを付けます。これにより、本文を読まずに 受信トレイを振り分けられます。

ニュースレターには、送信者が配信停止 URI を提供している場合、その URI も表示されます。また、RFC 8058 のワンクリック配信停止に対応している場合は 1-click が付与されます。ヘッダーは一覧取得の一部としてリクエストされるため、ページ全体を分類するための追加の往復通信は不要です。

分類はヘッダーに基づくため決定的であり、モデル呼び出しも件名テキストに対するヒューリスティックもありません。ヘッダーを省略している送信者のメールは、推測で分類せず、個人メールとして報告されます。これらは送信者が申告したヘッダーであり、検証済みではありません。マーカーは従うべき事実ではなく、判断材料の一つとして扱ってください。

本文のプレビュー

list_emails と search_emails は、preview: true を指定すると、各メッセージ本文の約200文字を含めます。デフォルトではオフです。有効にするとメッセージごとに追加で1500バイトを取得してツール出力が長くなるため、このコストを負担するかどうかは呼び出し元が選択するべきです。

プレビューはメッセージのソースではなく、1つの本文パートからデコードされます。IMAP セクション 1、またはセクション 1 自体がマルチパートの場合は 1.1 が対象です。取得はエンコーディングの境界ではなくバイト数で停止するため、デコードでは途中で切れた入力を許容します。base64 は完全なグループまでに切り詰め、途中まで書かれた quoted-printable のエスケープは破棄し、分断された UTF-8 シーケンスによって残った置換文字は末尾から削除します。UTF-8 以外の文字セットにも対応しています。実際のメールでは今でも iso-8859-1 が使われています。

送信者が宣言しているかどうかにかかわらず、マークアップは除去されます。大量配信の送信者は、HTML やスタイルシートを text/plain とラベル付けされたパートに入れることがよくあるためです。エンティティとゼロ幅のプリヘッダー用パディングはデコードされ、マークアップの残骸だけになったプレビューは省略されます。誤解を招くプレビューより、プレビューなしのほうがよいからです。

書き込み（9）

管理（7）

ラベル（5）

監視とアラート（6）

認証情報の確認（3）

カレンダーとリマインダー（8）

プロンプト（7）

リソース（6）

プロバイダーの自動検出

アーキテクチャ

src/
├── main.ts                — Entry point and subcommand routing
├── server.ts              — MCP server factory
├── logging.ts             — MCP protocol logging bridge
├── cli/                   — Interactive CLI commands
│   ├── account-commands.ts — Account CRUD (list, add, edit, delete)
│   ├── setup.ts           — Legacy setup alias → account add
│   ├── test.ts            — Connection tester
│   ├── config-commands.ts — Config management (show, edit, path, init)
│   ├── install-commands.ts — MCP client registration (install, status, remove)
│   ├── cache-commands.ts  — Local-mirror CLI (status, clear, verify)
│   └── scheduler.ts       — Scheduler CLI
├── config/                — Configuration layer
│   ├── xdg.ts             — XDG Base Directory paths
│   ├── schema.ts          — Zod validation schemas
│   ├── providers.ts       — Provider auto-detection + OAuth2 endpoints (experimental)
│   └── loader.ts          — Config loader (TOML + env vars)
├── cache/                 — Local SQLite mirror
│   ├── schema.ts          — Mirror schema + migrations
│   ├── store.ts           — Read/write API over the mirror
│   └── sync-engine.ts     — Background reconcile + body backfill
├── connections/
│   └── manager.ts         — Lazy persistent IMAP/SMTP with OAuth2 (experimental)
├── services/              — Business logic
│   ├── imap.service.ts    — IMAP operations
│   ├── label-strategy.ts  — Provider-aware label strategy (ProtonMail/Gmail/IMAP keywords)
│   ├── smtp.service.ts    — SMTP operations
│   ├── template.service.ts — Email template engine
│   ├── oauth.service.ts   — OAuth2 token management (experimental)
│   ├── calendar.service.ts — ICS/iCalendar parsing
│   ├── scheduler.service.ts — Email scheduling queue
│   ├── watcher.service.ts — IMAP IDLE real-time watcher with auto-reconnect
│   ├── hooks.service.ts   — AI triage via MCP sampling + static rules + auto-labeling/flagging
│   ├── notifier.service.ts — Multi-channel notification dispatcher (desktop/sound/webhook)
│   ├── clipboard.service.ts — Concealed clipboard writes for caught codes (zero deps)
│   ├── dialog.service.ts   — Native confirm dialogs + browser hand-off (macOS)
│   ├── verification-catcher.service.ts — Instant OTP/magic-link catch on new mail
│   ├── presets.ts         — Built-in hook presets (inbox-zero, gtd, priority-focus, etc.)
│   └── event-bus.ts       — Typed EventEmitter for internal email events
├── tools/                 — MCP tool definitions (52)
├── prompts/               — MCP prompt definitions (7)
├── resources/             — MCP resource definitions (6)
├── safety/                — Audit trail and rate limiter
└── types/                 — Shared TypeScript types

ロードマップ

提案されたものの、意図的にまだ実装していないアイデアです。忘れたり、 気付かないうちに再提案されたりしないよう、ここに記載しています。

• 代替プロバイダーとしてのAgentMail。 AgentMail は、APIキーのみで利用できるプログラム作成可能な@agentmail.toの受信トレイを提供します。IMAP/SMTPの ホスト、ポート、TLS、認証情報を設定する必要がなく、一時的な エージェント所有のアドレスをすぐに用意する場合に便利です。これは、実際のIMAP/SMTPアカウントを 置き換えるものではなく、それらに加わる第2のプロバイダーとして追加することになります。ただし、これは バグ修正や不足分の補完ではなく、新たなベンダー依存関係とツール群を伴う 製品・アーキテクチャ上の判断であるため、自動実装せず、ここに保留しています。既存の メールボックスへのアクセスではなく、エージェントが用意した受信トレイに対する 実際の需要があれば、再検討します。

メンテナー

@codefuturist

リリースの前提条件

release.yml は公開前にこれらを確認します。いずれかが欠けていると、公開が中途半端に行われるのではなく、すぐに失敗する実行になります。

Homebrew の cask には署名なしの Bun バイナリが含まれるため、postflight で macOS の隔離属性を解除します。これは macOS のみを対象とします。Linux には xattr(1) がなく、cask DSL の system_command は終了コードが 0 以外の場合にエラーになるためです。brew uninstall --zap は設定、状態、キャッシュ、データの各ディレクトリに加え、2 つの launch agent も削除します。

貢献

PR を歓迎します。この README を編集する際は、standard-readme の仕様に準拠してください。

# Development workflow
pnpm install
pnpm typecheck   # type check
pnpm check       # lint and format
pnpm build       # build
pnpm start       # run

テスト

pnpm test              # unit tests
pnpm test:integration  # against a throwaway GreenMail server (Docker required)
pnpm smoke             # most MCP tools against a real configured account (see caveats below)

統合テストスイートでは、各ツールを使い捨ての GreenMail サーバー（Testcontainers で起動）に対して実行します。添付ファイルのテスト（email-attachments.integration.test.ts）では、実際の MCP ツール層を通して、サイズ認識に関する契約を検証します。送信ごとに各ファイルのサイズと raw≈base64 の合計が報告されること、上限は（実際に送信される）エンコード後の合計に適用されること、上限を超える送信は安全側に倒して失敗し、何も配信されないこと、また includeAttachments: false が指定されていない場合、転送時に元の添付ファイルが引き継がれることを確認します。有効な上限はアカウントごとに解決されます。アカウント単位で max_attachment_mb が明示されていれば、その値が優先されます。そうでない場合は、グローバルな [settings.send] の上限とプロバイダーの公表上限のうち、より厳しい方が適用されます（Gmail、Yahoo、Proton は 25 MB、Outlook.com、iCloud、GMX は 20 MB、Fastmail は 50 MB）。

pnpm smoke は、クライアントと同じ方法で stdio 経由ですべてのツールを実行します。これにより、GreenMail では検証できないプロバイダー固有の動作、実環境の MIME、macOS の Calendar ブリッジを確認できます。動作するアカウントが必要なため、CI には含まれていません。書き込み先はスクラッチフォルダーと、このテスト自体が作成した下書きに限られます。Calendar、Reminders、通知、実際の相手にメールを送信する reply_email には触れません。アカウントを選択するには E2E_ACCOUNT=<name> を指定してください。指定しない場合は、設定済みの最初のアカウントが使われます。

ライセンス

LGPL-3.0-or-later