mailoo

Mailoo

Mailoo（@bitfloo/mailoo）は、Bitfloo が開発・保守する、メール（IMAP/SMTP）、カレンダー、リマインダー、ManageSieve 自動化向けの Model Context Protocol（MCP）サーバーです。

複数のアカウントにわたって、AI アシスタントや自律型エージェントがメール、カレンダー、リマインダー、ManageSieve フィルタースクリプトの閲覧、検索、送信、管理、スケジュール設定、分析を行えるようにします。full、core、minimal のツールセットプロファイルに対応し、最大57個のツール、最大7個のプロンプト、6個のリソースを公開します。また、outputSchema / structuredContent を備えた MCP 2025/2026 プロトコル、OAuth2 サポート（実験的）、メールのスケジュール設定、カレンダー情報の抽出、分析、プロバイダーに応じたラベル管理、AI を活用したトリアージ機能付きのリアルタイム IMAP IDLE ウォッチャー、カスタマイズ可能なプリセットと静的ルール、ManageSieve フィルター、ガイド付きセットアップウィザードも提供します。

送信済みメールのコピー、IMAP4rev2、Sieve、添付ファイルの savePath、読み取り専用操作による副作用、再接続時のバックオフの動作については、docs/configuration.md と docs/tools.md に記載されています。

主な機能

目次

• 主な機能
• セキュリティとサンドボックスのアーキテクチャ
• LLM の使いやすさとツールセットプロファイル
• ドキュメント
• 背景
• インストール
• 使い方
• 機能とデータフロー
• API
• メンテナー
• コントリビューション
• 謝辞とライセンス

セキュリティとサンドボックスのアーキテクチャ

ポリシーおよび脆弱性の報告方法については、SECURITY.md をご覧ください。

Mailoo は、多層防御によるサンドボックス化を採用しており、AI エージェントが信頼できないメールや外部サーバーと安全にやり取りできるよう設計されています。

• シェル実行ゼロ（execFile のみ） — ネイティブ OS 連携（EventKit／リマインダー／通知用の macOS osascript、Linux の notify-send、Windows の powershell、および crontab のインストール）では、厳密な引数配列（shell: false）を指定して child_process.execFile を呼び出し、コマンドインジェクションの攻撃経路を排除します。
• SSRF と DNS リバインディングの防止（net.BlockList） — 外部アラート用の Webhook では、IPv4／IPv6 の net.BlockList を使用して URL を検証します。このリストは、ループバック、RFC 1918 のプライベート範囲、リンクローカル／クラウドメタデータ（169.254.169.254、100.100.100.200）、CGNAT、NAT64、6to4、および予約済みプレフィックスを対象とし、設定時とソケット接続時（createWebhookConnectLookup）の両方で検証することで、DNS リバインディング攻撃を防ぎます（src/safety/validation.ts）。
• シンボリックリンクを使用しない書き込み制限（savePath） — savePath による添付ファイルと .eml のエクスポートは、作業ディレクトリ内に厳密に制限されます。すべてのパス要素を lstat で順に確認し、隠しドットファイルと OS の永続化用ディレクトリ（Library/LaunchAgents、.ssh、.gnupg）を拒否します。また、ファイルサイズの上限を 50 MiB（インライン base64 の上限は 5 MiB）として、O_CREAT | O_EXCL | O_NOFOLLOW を指定して対象ファイルを開きます。
• プロンプトインジェクションの隔離（<<<UNTRUSTED_EXTERNAL_CONTENT>>>） — 信頼できないメールの件名、送信者ヘッダー、本文、プレビュー、認証結果は、<<<UNTRUSTED_EXTERNAL_CONTENT>>> と <<<END_UNTRUSTED_EXTERNAL_CONTENT>>> の区切りで囲まれます（ペイロード内の偽装されたマーカーは削除されます）。これにより、LLM は外部メールを指示ではなくデータとして扱います。
• 認証情報ファイルの厳格なアクセス権限（0600） — config.toml は、0700 の設定ディレクトリ（$XDG_CONFIG_HOME/mailoo/config.toml）内にモード 0600 で書き込まれ、検証されます。パスワードとメッセージ本文は JSONL 書き込み監査ログから秘匿されます（src/safety/audit.ts）。
• TLS と STARTTLS の検証 — tls は証明書検証を伴う暗黙的な TLS 接続を適用します（デフォルトで verify_ssl = true）。サーバーが STARTTLS を通知しない場合、starttls は接続を拒否します。両方を無効にできるのは、ループバックホストの場合に限られます。ManageSieve は、STARTTLS を使わない暗号化されていないソケット経由の AUTHENTICATE PLAIN を拒否します。
• 運用上のガードレール（MCP_EMAIL_READ_ONLY、MCP_EMAIL_TOOLSET、dryRun） —
  • 起動時に MCP_EMAIL_READ_ONLY=true を設定すると、すべての書き込みツール、バックグラウンド監視、フック、スケジューラーが無効になり、読み取り専用の 31 個のツールのみが公開されます。
  • MCP_EMAIL_TOOLSET=full|core|minimal を設定すると、エージェントの機能レベルとコンテキストの予算に合わせて、登録されるツールの範囲が制限されます。
  • 高リスクのツール（send_email、reply_email、forward_email、send_draft、delete_email、bulk_action、delete_mailbox、sieve_put_script、sieve_delete_script）で dryRun: true を指定すると、すべてのパラメーターとアカウントの解決を検証し、サーバーの状態を変更せずに [DRY RUN] プレビューを返します。
• アカウントごとのレート制限 — rate_limit（デフォルトは 1 分あたり 10 件の送信）により、アカウントごとに独立したトークンバケットが適用されます（src/safety/rate-limiter.ts）。バケットはメモリ内に保持されるため、各サーバープロセスと各 mailoo scheduler check の実行は、それぞれ個別にカウントされます。

LLM の使いやすさとツールセットプロファイル

Mailoo は、最先端モデル（Claude、GPT、Gemini）とローカルの小規模な 3B～8B パラメーターのモデル（llama.cpp の GBNF 文法、Ollama、vLLM）の両方で動作するように設計されています。

• ツールセットプロファイル（MCP_EMAIL_TOOLSET / settings.toolset）：
  • full (デフォルト) — カレンダー、リマインダー、ManageSieve、Watcher、Scheduler、Templates、Contacts、Analytics を含む 57 個のツール（read_only モードでは 31 個）。
  • core — メールの主要なワークフロー（accounts、mailboxes、emails、threads、send、drafts、manage、bulk、attachments、health）をカバーする 19 個のツール（read_only モードでは 10 個）。
  • minimal — コンテキスト予算が限られた 3B～4B モデル向けに調整された 14 個のツール（read_only モードでは 8 個）（accounts、mailboxes、emails、send、manage、health）。
• 省略可能な account とスマートなアカウント解決 — 設定されているアカウントが 1 つだけの場合、または default_account（MCP_EMAIL_DEFAULT_ACCOUNT）が設定されている場合、すべてのツールで account パラメーターを完全に省略できます。アカウントの検索では、プロファイル名またはメールアドレスの大文字と小文字を区別せずに照合します（例："[email protected]" を渡すと、一致するアカウントが解決されます）。あいまいな場合は、有効なアカウントを name (email) のペアで列挙した、次に取るべき行動が分かるエラーメッセージを返します。
• 情報を損なわないパラメーター正規化と GBNF 互換性 — 単一メッセージ用ツールでは、emailId、id、email_id を文字列または整数（42 または "42"）として受け付けます。バッチツール（get_emails、bulk_action）では、文字列または数値の ID 配列（["42", "43"] または [42, 43]）を受け付けます。list_emails と search_emails では、hasAttachment と has_attachment の両方を受け付けます。すべての Zod スキーマでは正規表現の先読みを避けているため、llama.cpp の GBNF 文法コンパイルがエラーなく成功します。
• コンテキストウィンドウの保護 — get_email と get_thread はデフォルトで format="text" を使用し、デフォルトの最大長を 20000 文字に制限します（超過時は明確な切り捨て通知を付加します）。これにより、大きな HTML ニュースレターが小さなコンテキストウィンドウからあふれるのを防ぎます。
• MCP 2025/2026 の outputSchema と structuredContent — ツールは構造化された outputSchema の契約を宣言し、人間が読めるテキストブロックとともに、機械可読な structuredContent を返します。
• 送信する添付ファイルのパスは、作業ディレクトリまたはホームディレクトリ内の通常ファイルを指定する必要があります — セキュリティに関する考慮事項

ドキュメント

背景

多くの MCP メール実装が提供するのは、基本的な読み取りと送信機能のみです。このサーバーは、メールの読み取り、作成、管理、スケジュール設定、分析まで、ライフサイクル全体を 1 つの MCP サーバーから扱える、フル機能の AI アシスタント向けメールクライアントを目指しています。

主な設計上の決定事項：

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

インストール

Node.js ≥ 24 が必要です。

npx -y @bitfloo/mailoo account add

これによりローカル設定が書き込まれ、MCP クライアント用のスニペットが表示されます。同じパッケージでサーバーとその他のコマンドを実行できます。

npx -y @bitfloo/mailoo
npx -y @bitfloo/mailoo test

サブコマンドなしで npx -y @bitfloo/mailoo を実行すると、stdio 経由で MCP サーバーが起動します。または、mailoo コマンドをインストールします。

npm install -g @bitfloo/mailoo
# or
pnpm add -g @bitfloo/mailoo
# or, without a global install:
pnpm dlx @bitfloo/mailoo account add

クローンからのインストール

このリポジトリのビルドには、pnpm 12（package.json の packageManager に記載されたバージョン）が必要です。

git clone https://github.com/Bitfloo/mailoo.git
cd mailoo
pnpm install && pnpm build
node dist/main.js account add

Docker

実行イメージには、ホスト上の Node ではなく Docker が必要です。まず npx -y @bitfloo/mailoo account add で設定を作成するか、TOML を手動で記述してから、そのディレクトリをコンテナにマウントします。

イメージは ghcr.io/bitfloo/mailoo で、linux/amd64 および linux/arm64 向けにビルドされています。タグはバージョン番号のみ（v プレフィックスなし）です。0.3 タグは、最新の 0.3.x リリースを追跡します。本番環境では、リリースの完全なバージョン（npm のバージョンと一致します）またはイメージダイジェストを指定してください。

docker pull ghcr.io/bitfloo/mailoo:0.3

クローンからビルドする場合（docker-compose.yml は build: . を使用します）：

docker build -t ghcr.io/bitfloo/mailoo .

注： サーバーは stdio トランスポートを使用します。設定はホスト上で作成し （npx -y @bitfloo/mailoo account add を実行するか、TOML を手動で記述します）、コンテナにマウントします。

使用方法

以下のコマンドでは npx -y @bitfloo/mailoo を使用します。グローバルインストールの場合も、同じサブコマンドを mailoo で実行できます。クローンから使用する場合は、pnpm build の実行後、各サブコマンドを node dist/main.js で実行します（クローンからの使用を参照）。

セットアップ

# Add an email account interactively (recommended)
npx -y @bitfloo/mailoo account add

# Or use the deprecated alias (same wizard)
npx -y @bitfloo/mailoo setup

# Or create a template config manually
npx -y @bitfloo/mailoo config init

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

接続テスト

npx -y @bitfloo/mailoo test            # all accounts
npx -y @bitfloo/mailoo test personal   # specific account

npx -y @bitfloo/mailoo test / mailoo test は、実際のアカウントへの接続プローブであり、Vitest ではありません。ユニットテストと統合テストには pnpm test / pnpm test:integration を使用します（コントリビューションを参照）。OAuth2 アカウントでは、設定済みのリフレッシュトークンから更新したアクセストークンを使ってログインします。

MCP クライアントの設定

ガイド付きインストーラーを実行するか、以下のスニペットを貼り付けてください。VS Code / MCP ギャラリーには掲載されていません。

npx -y @bitfloo/mailoo install

インストーラーでは、npx、pnpm dlx、またはグローバルにインストールした mailoo の起動を登録できます。すでに PATH 上に mailoo バイナリがある場合は、"command": "mailoo" と "args": ["stdio"] を使用できます。

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo", "stdio"]
    }
  }
}

{
  "servers": {
    "mailoo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo", "stdio"]
    }
  }
}

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

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "mailoo": {
      "command": "npx",
      "args": ["-y", "@bitfloo/mailoo", "stdio"]
    }
  }
}

{
  "context_servers": {
    "mailoo": {
      "command": {
        "path": "npx",
        "args": ["-y", "@bitfloo/mailoo", "stdio"]
      }
    }
  }
}

[[mcp_servers]]
name = "mailoo"
transport = "stdio"
command = "npx"
args = ["-y", "@bitfloo/mailoo", "stdio"]

[[mcp_servers]]
name = "mailoo"
transport = "stdio"
command = "npx"
args = ["-y", "@bitfloo/mailoo", "stdio"]
env = { MCP_EMAIL_ADDRESS = "[email protected]", MCP_EMAIL_PASSWORD = "your-app-password", MCP_EMAIL_IMAP_HOST = "imap.example.com", MCP_EMAIL_SMTP_HOST = "smtp.example.com" }

docker run --rm -i \
  -v ~/.config/mailoo:/home/node/.config/mailoo:ro \
  ghcr.io/bitfloo/mailoo:0.3

{
  "mcpServers": {
    "mailoo": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "~/.config/mailoo:/home/node/.config/mailoo:ro",
        "ghcr.io/bitfloo/mailoo:0.3"
      ]
    }
  }
}

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

CLI コマンド

npx -y @bitfloo/mailoo [command]

Commands:
  stdio                     Run as MCP server over stdio (default)
  http [port] [host]        Streamable HTTP (default: port 8080 on 127.0.0.1 and ::1)
  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                     Deprecated alias for 'account add'
  test                      Test connections for all or a specific account
  install                   Register mailoo with MCP clients interactively
  install status            Show registration status for detected clients
  install remove            Unregister mailoo from MCP clients
  config show               Show config (passwords masked)
  config edit               Edit global settings (rate limit, read-only)
  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
  notify test               Send a test desktop notification
  notify status             Check platform notification support
  --version, -v             Print the package version
  help                      Show help

HTTP

http は 127.0.0.1 および ::1 でリッスンします（ポートは、別のポートを指定しない限り 8080 です）。ループバック以外のアドレス、または MCP_EMAIL_HTTP_ALLOWED_HOSTS 内のループバック以外の名前を使用する場合は、MCP_EMAIL_HTTP_TOKEN が必要です。0.0.0.0 / :: や 8 MiB の本文サイズ制限などの詳細は、docs/configuration.mdを参照してください。

npx -y @bitfloo/mailoo http
MCP_EMAIL_HTTP_TOKEN='replace-with-a-long-random-secret' npx -y @bitfloo/mailoo http 8080 192.0.2.10

トークンが設定されている場合、クライアントは Authorization: Bearer <token> を送信します。

設定

$XDG_CONFIG_HOME/mailoo/config.toml にあります（デフォルト：~/.config/mailoo/config.toml）。

[settings]
rate_limit = 10  # max emails per minute per account
read_only = false
toolset = "full"  # "full" | "core" | "minimal"
default_account = "personal"  # optional when only one account is configured
save_to_sent = true  # see docs/configuration.md — Gmail already files Sent

[[accounts]]
name = "personal"
email = "[email protected]"
full_name = "Your Name"
password = "your-app-password"

[accounts.imap]
host = "imap.example.com"
port = 993
tls = true
# disable_imap4rev2 = true  # Strato and similar SEARCH bugs
# sieve_host = "imap.example.com"
# sieve_port = 4190

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

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

ファイル内または MCP_EMAIL_* で、tls = false かつ starttls = false に設定された IMAP または SMTP ブロックは、localhost、完全な形式で記述された 127.0.0.0/8 内のアドレス（127.0.0.1 など）、または ::1 の場合にのみ読み込まれます。それ以外のホストは設定の読み込み時に拒否されます。

OAuth2 (実験的)

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

トークンの更新とコード交換は 15 秒でタイムアウトするため、応答を停止したプロバイダーは接続をハングさせず、OAuth2 token refresh timed out after 15s エラーで失敗します。同時に新しいトークンを必要とする呼び出し元は、1 つの更新リクエストを共有します。IDLE ウォッチャーは同じアクセストークンでログインします。

[[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.example.com"
port = 993
tls = true

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

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

環境変数

単一アカウントのセットアップ用（設定ファイルより優先されます）：

アドレス、両方のホスト、パスワードまたはプロバイダーが指定されていない場合、環境変数はアカウントを定義しません。その場合、Mailoo は設定ファイルを読み込むか、設定ファイルがない場合は No configuration found. で失敗します。

送信済みコピー、IMAP4rev2、Sieve のホスト／ポート、read_only 環境変数については、docs/configuration.md を参照してください。

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

スケジューラーは、階層化されたアーキテクチャを使用して、将来のメール配信を可能にします。

1. MCP による自動チェック — サーバー起動時（ウォッチャーの接続前）と、MCP サーバーの実行中は 60 秒ごとにキューを処理します。複数の stdio サーバーがある場合は、ウォッチャーとフックを実行しているサーバーだけがチェックします。次のチェック時刻になっても処理中の場合、そのチェックはスキップされ、送信に失敗すると、接続中の MCP クライアントに warning として記録されます
2. CLI — 手動または cron による処理には npx -y @bitfloo/mailoo scheduler check を使用します。OAuth2 や save_to_sent を含む、サーバーと同じアカウント設定で送信し、終了前に IMAP／SMTP 接続を閉じます
3. OS レベルのデーモン — npx -y @bitfloo/mailoo scheduler install を実行すると、MCP サーバーとは独立して毎分実行するよう、launchd（macOS）または crontab（Linux）を設定します

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

デーモンの設定

# Install (macOS launchd / Linux crontab — runs every minute)
npx -y @bitfloo/mailoo scheduler install

# Verify it's running
npx -y @bitfloo/mailoo scheduler status

# View pending / sent / failed scheduled emails
npx -y @bitfloo/mailoo scheduler list

# Trigger a manual check immediately
npx -y @bitfloo/mailoo scheduler check

# Remove the daemon
npx -y @bitfloo/mailoo scheduler uninstall

スケジュール済みメールは ~/.local/state/mailoo/scheduled/ 内の JSON ファイルです。送信前に、チェック処理はそのファイルの隣にロックファイルを作成してエントリを確保し、SMTP の実行中もその確保状態を更新します。これにより、プロセス内タイマー、mailoo scheduler check、他のサーバープロセスが同じメールを二重に送信するのを防ぎます。サーバーがメッセージを受け付けた後、送信済みとして記録する前にプロセスが終了した場合、確保状態が期限切れになった後でエントリが再送信されることがあります（少なくとも 1 回の配信であり、厳密に 1 回の配信ではありません）。1 つのエントリに対するすべての試行では、同じ Message-ID（<schedule id@account domain>）が使用されるため、受信サーバーまたはクライアントは 2 通目を破棄できます。SMTP がメッセージを受け付けた後にキューファイルの更新に失敗した場合は、その旨が報告されます。また、送信済みの記録または sent/ への移動のいずれかが成功していれば、エントリは再送信されません。両方とも失敗した場合、すべての試行を使い切っていない限り、次回のチェックで再送信されます。試行回数を使い切っている場合は、failed としてマークされます。各エントリには試行回数（最大 3 回）と最後のエラーが記録されます。list_scheduled はその両方を返し、scheduler list は失敗したエントリのエラーを表示します。レート制限によって保留されたエントリは、次回のチェックまで保留状態のままとなり、試行回数には加算されません。

リアルタイムウォッチャーと AI フック

IMAP IDLE ウォッチャーは、永続的な IDLE 接続（ツール接続とは別）を使用して、設定済みのメールボックスをリアルタイムで監視します。各フォルダーはフェッチの合間も IDLE 状態を保ち、フェッチのたびに約 1 秒後に IDLE が再開されます。idle_timeout は IDLE の再起動間隔を設定します。同じマシン上で複数の stdio サーバー（MCP クライアントのウィンドウごとに 1 つ）を実行している場合、ウォッチャー、フック、スケジューラーを実行するのはそのうち 1 つだけです。詳しくは設定を参照してください。新着メールが届くと、次の処理を行います。

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 @example.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 = "*@example.com" }
actions = { labels = ["Dev"], mark_read = true }

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

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

バッチは一度に 1 つずつ実行されます。次のバッチを待つ新着メールは最大 500 件です。 それを超えるメールは、ログに警告を記録してスキップされ、メールボックス内で変更されずに残ります。

プリセット

静的ルール

静的ルールでは、| を OR 区切り文字とする glob 形式のパターン（*@example.com|*@example.test）を使用します。一致条件内の条件はすべて AND で評価されます。to パターンは、いずれかの受信者が一致すると一致します。空のパターンは条件なしとして扱われ、条件のないルールは何にも一致しません。最初に一致したルールが適用されます。

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

アラート

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

記載されたレベルで出力される MCP ログエントリーには、アカウント、フォルダー、UID、ラベル、ルールが記録されます。アラートのエントリーでは、送信者と件名は debug にのみ表示されます。別のエントリーに記録されるか、low の場合は単一のエントリーに記録されます。

[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"]
allow_private_webhooks = false  # default; true allows a LAN, VPN, or tailnet target

詳細：docs/configuration.md。

対応プラットフォーム： 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"] }

機能：

• 自動再接続 — 再接続のバックオフスケジュールに従って、切断または失敗したフォルダー接続を再試行します。接続が停止している間に届いたメールは、再接続後に通知されます。ただし、サーバー側でフォルダーの UIDVALIDITY が変更された場合を除きます。まだ一度も接続していないフォルダーについては、初回の接続が成功した後に届いたメールのみ通知されます
• バッチ処理 — 設定可能な遅延時間内に届いたメールをまとめて、AI の呼び出しを減らします
• レート制限 — サンプリング呼び出しは最大で毎分 10 回です
• 適切な縮退 — クライアントがサンプリングに対応していない場合は、通知モードに切り替えます

System One（オプトイン式の振り分け）

静的ルール適用後に残ったメールを対象とする、任意の TypeSafe System One 分類機能です。デフォルトではオフです。 settings.watcher.enabled と settings.system_one.enabled の両方をオンにする必要があります。環境変数に TYPESAFE_API_KEY を設定してください（TOML には決して設定しないでください）。

source_folders（デフォルトは INBOX）内の新着メールのうち、静的ルールで処理されなかったものだけが分類されます。そのようなメッセージごとに、Mailoo は api.typesafe.ai（または TYPESAFE_BASE_URL）にリクエストを1回送信します。リクエストには次の情報が含まれます（src/services/mail-arrival/state.ts、src/services/mail-arrival/questions.ts）。

送信されない情報：To、Cc、Bcc のアドレス、Message-ID、その他の生ヘッダー、添付ファイルの内容、および include_body が false の場合の本文。

Mailoo は分類した直近5000件のメッセージを記憶し、再送信しません。2つのアカウントに届いたメッセージは、各アカウントで1回ずつ分類されます。リクエストまたはヘッダーの読み取りに失敗したメッセージは記憶されないため、次回通知されたときに再試行されます。

auto_move と auto_flag は別々の切り替え項目で、デフォルトでは false です。振り分け先は folders[].path から取得され（IMAP LIST に対して検証されます）、すべてのメールボックスをライブ一覧表示して取得するわけではありません。

[settings.system_one]
enabled = false
include_body = false
auto_move = false
auto_flag = false

[[settings.system_one.folders]]
path = "Receipts"
description = "Invoices, receipts, and payment confirmations."

on_new_email = "notify" と "triage" は、System One がオンの場合、どちらも System One にメールを渡します。none の場合はオフのままです。

機能とデータフロー

以下に示す送信呼び出し、子プロセス、ファイル、環境変数は、src/ が使用するものです。MCP サンプリングを使用するフックのトリアージは、接続されたクライアント内で完結します。この経路では、Mailoo が別のモデルホストに接続することはありません。

ネットワーク

mailoo http はリッスンします。送信先は追加されません。src/cli/providers.ts のプロバイダープリセットは、ウィザードで保存する IMAP ホストと SMTP ホストを設定します。

プロセス

ファイル

XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME が設定されていない場合、パスには src/config/xdg.ts の XDG デフォルト値が使用されます。

$XDG_CONFIG_HOME/mailoo/templates/ 内のテンプレートは読み込まれますが、サーバーによって書き込まれることはありません。

環境

単一アカウントの設定では、MCP_EMAIL_* を読み込みます（src/config/loader.ts）。HTTP リッスンでは、MCP_EMAIL_HTTP_HOST、MCP_EMAIL_HTTP_TOKEN、MCP_EMAIL_HTTP_ALLOWED_HOSTS を読み込みます（src/safety/http-transport.ts）。同じ名前が、Smithery の設定キーおよび server.json の packages[].environmentVariables リストでも使われます。

API

ツール（57）

読み取り（19）

書き込み（12）

管理（7）

ラベル（5）

注： ラベルを IMAP キーワードとして保存するサーバーでは、キーワードは IMAP atom （RFC 9051）でなければなりません。空白、制御文字、非 ASCII 文字、および ( ) { % * " \ ] は使用できません。 これ以外のラベルは、何も送信される前にエラーとして拒否されるため、Receipts (2024) は失敗します（以前のリリースでは受け入れられていました）。既存の atom ではないキーワードの削除については、add_label / remove_label を参照してください。

ウォッチャーとアラート（6）

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

上記ツールのパラメーターに関する注記：docs/tools.md。

プロンプト（7）

プロンプトは、呼び出すツールがツールセットに登録されている場合にのみ一覧表示されます。summarize_thread には core または full が、summarize_meetings には full が必要です。送信、下書き、または一括処理ツールがない場合（minimal、read_only）、プロンプトではその手順を省略します。

リソース（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)
│   ├── providers.ts       — Provider auto-detection (IMAP/SMTP presets)
│   └── scheduler.ts       — Scheduler CLI
├── config/                — Configuration layer
│   ├── xdg.ts             — XDG Base Directory paths
│   ├── schema.ts          — Zod validation schemas
│   └── loader.ts          — Config loader (TOML + env vars)
├── connections/
│   ├── auth.ts            — IMAP/SMTP credentials (password or OAuth2)
│   ├── backoff.ts         — Reconnect delays with jitter after a failed connect
│   ├── manager.ts         — Lazy persistent IMAP/SMTP with OAuth2 (experimental)
│   └── probe.ts           — One-shot IMAP/SMTP login checks (setup wizard, mailoo test)
├── services/              — Business logic
│   ├── imap.service.ts    — IMAP operations
│   ├── label-strategy.ts  — Provider-aware label strategy (ProtonMail/Gmail/IMAP keywords)
│   ├── smtp.service.ts    — SMTP operations + optional \\Sent APPEND
│   ├── sieve.service.ts   — ManageSieve (RFC 5804)
│   ├── template.service.ts — Email template engine
│   ├── oauth.service.ts   — OAuth2 token management (experimental)
│   ├── mail-services.ts   — IMAP/SMTP services from the config, for the servers and the scheduler CLI
│   ├── 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)
│   ├── 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 (57)
├── prompts/               — MCP prompt definitions (7)
├── resources/             — MCP resource definitions (6)
├── safety/                — Audit trail, rate limiter, stdio lifecycle, shutdown, writer lease
│   └── http-transport.ts  — Streamable HTTP listen policy
├── utils/                 — RFC 2047 compose, MIME body, auth headers
└── types/                 — Shared TypeScript types

メンテナー

Bitfloo

コントリビューション

PR は develop（GitHub のデフォルトブランチ）宛てに受け付けています。develop はリリースブランチであり、ここから v* のタグを付けてリリースします。この README を編集する際は、standard-readme の仕様に準拠してください。CONTRIBUTING.md を参照してください。

# Development workflow
pnpm install
pnpm typecheck          # type check
pnpm check              # lint and format
pnpm ci:local           # lint, typecheck, unit; GreenMail if Docker is up
pnpm test               # unit tests (Vitest; no mail server)
pnpm test:integration   # GreenMail IMAP/SMTP (needs Docker)
pnpm test:all           # unit plus GreenMail
pnpm build              # build
pnpm start              # run

pnpm test:integration と pnpm test:all には Docker が必要です。Docker が停止している場合、pnpm ci:local は GreenMail をスキップします。プルリクエストで GitHub が実行する内容は、CONTRIBUTING.md に記載されています。mailoo test／npx -y @bitfloo/mailoo test は実際のアカウントへの接続確認であり、Vitest ではありません。

帰属表示とライセンス

これは、codefuturistによるemail-mcpのLGPL-3.0-or-later の公開フォークです。 codefuturist の公式プロジェクトではありません。原著作権は引き続き原著作者に帰属します。 Mailoo のブランディング、Bitfloo の商標、および新しいコードの著作権は、Copyright (c) 2026 Bitfloo に帰属します。

LGPL-3.0-or-laterの下でライセンスされています。LGPL-3 で必要とされる GNU GPL-3 のテキストはCOPYINGにあります。 帰属表示はNOTICEに記載されています。