mail-mcp

セルフホスト型、プロバイダ非依存のメールサービス。任意のメールボックスのIMAP/SMTP認証情報を指定するだけで、以下の機能を提供します：

• REST API：一般的なメールボックス操作をミラーリング：フォルダ一覧、メッセージの一覧/取得/検索、送信、フラグ設定、移動、削除、クォータ（ベストエフォート）。

• Webhook（message.received）：永続的なIMAP IDLEウォッチャー経由で、新着メールが到着するたびにHTTP POST（WebhookごとのBearerシークレット付き）を発行。受信エンドポイントが失敗した場合、指数バックオフ（最大6回試行）でリトライします。

• MCPサーバー（Streamable HTTP、POST /mcp）：同じ操作をツールとして公開するため、MCP互換のエージェントが直接利用可能。

最初からマルチメールボックス対応：config/accounts.jsonに必要なだけアカウントを追加できます。

REST APIのリクエストボディはZod（lib/schemas.js）で検証され、無効なペイロードはメール層に到達する前にフィールドレベルのエラーとともに422 ERR_VALIDATION_FAILEDを返します。Webhookの購読はフラットなJSONファイルではなくSQLite（config/webhooks.sqlite、better-sqlite3経由）に永続化されます。MAIL_MCP_MAX_MESSAGE_SIZE（デフォルト25MB）より大きなメッセージは、メモリに巨大なメッセージを読み込まないよう、bodyTruncated: trueでパースされた本文/添付ファイルなしで返されます。

セットアップ

npm install
cp .env.example .env   # fill in MAIL_MCP_API_TOKEN and one MAILMCP_PASS_<ID> per account

config/accounts.json.exampleをconfig/accounts.jsonにコピーします（gitignore対象 – このファイルにもパスワードは含まれず、パスワードは.envのみに存在します）：

[
  {
    "id": "example",
    "user": "user@example.com",
    "imap": { "host": "imap.example.com", "port": 993, "secure": true },
    "smtp": { "host": "smtp.example.com", "port": 465, "secure": true }
  }
]

アカウントid: "example"のパスワードはMAILMCP_PASS_EXAMPLEから読み取られます。

node index.js

デフォルトでは127.0.0.1:4900で動作します（MAIL_MCP_PORTを参照）。ホスト外からアクセスする必要がある場合は、TLSを使用したリバースプロキシの背後に配置してください。

Related MCP server: Agent Email

systemd

サンプルユニットがdeploy/mail-mcp.serviceにあります。これを/etc/systemd/system/にコピーし、パスを調整すると、EnvironmentFile経由で/root/mail-mcp/.envからシークレットを読み込みます。

認証

すべてのRESTおよびMCPリクエストには、Authorization: Bearer <MAIL_MCP_API_TOKEN>が必要です。

テスト

npm test              # run once
npm run test:coverage # run with coverage report

カバレッジは純粋な/ロジックモジュール（lib/schemas.js、lib/accounts.js、lib/webhooks-store.js）を対象としています。lib/mailclient.jsとlib/idle-watcher.jsは実際のIMAP/SMTPサーバーと通信するため、ユニットテストではなく手動のエンドツーエンドテストで検証されています。これらはカバレッジバッジから除外されているため、誤解を招くことはありません。