IMAP MCP Pro

IMAP MCP Pro

高度な信頼性機能、包括的な監視、安全なアカウント管理を備え、本番環境に対応した IMAP メール統合を提供する、エンタープライズグレードの Model Context Protocol（MCP）サーバーです。

プロフェッショナル版 — 商用および大規模なデプロイ向けに、レベル 1～3 の信頼性機能、サーキットブレーカーパターン、メトリクス、一括操作を追加したフォークです。

📜 ライセンスの概要

個人、教育、非営利目的での利用は無料です。 ビジネス、SaaS、収益を生み出すデプロイ、またはマルチテナントのデプロイには、有料の商用ライセンスが必要です。

商用ライセンスについてのお問い合わせ先：[email protected] 全条項：LICENSE · 以下のライセンスセクション

機能

メール／フォルダー／アカウント／カテゴリ／スコアリング／サブスクリプション／dns-firewall／usercheck／ステージング／キャッシュ／診断にわたる 100 以上の MCP ツールを提供します。使用する IMAP4rev2（RFC 9051）のすべての操作を公開しています。正確な件数を含むカテゴリ別の一覧はdocs/TOOL_CATALOG.md（ビルドごとにマニフェストから生成）を参照するか、実行時の最新カタログを確認するには imap_list_tools を実行してください。

主な機能

• 🔐 安全なアカウント管理：AES-256 暗号化による認証情報の暗号化保存
• 🚀 コネクションプーリング：効率的な IMAP 接続管理
• 📧 包括的なメール操作：メールの検索、閲覧、マーク、削除
• ✉️ メール送信：SMTP 経由でメールの送信、返信、転送
• 📁 フォルダー管理：フォルダーの一覧表示、ステータスの確認、未読数の取得
• 🔄 複数アカウント対応：複数の IMAP アカウントを同時に管理
• 🛡️ 型安全：信頼性を高める TypeScript による実装
• 🌐 ウェブベースのセットアップウィザード：プロバイダープリセットによる簡単なアカウント設定
• 📱 15 以上のメールプロバイダー：Gmail、Outlook、Yahoo などの事前設定
• 🔗 SMTP 設定の自動構成：IMAP プロバイダーに基づく SMTP 設定の自動化

ローカルメッセージキャッシュ＋スキルの自動インストール（v2.17.0+）

• 高速な送信者一覧取得を実現するローカル SQLite ヘッダーキャッシュです。imap_sync_folder_cache がフォルダーごとのキャッシュを作成し、imap_search_cache はそのキャッシュに対して group_by_sender／by_domain／by_address クエリを数ミリ秒で実行します。1500 件のメッセージがある INBOX でエンドツーエンドの動作を検証済みです。初回同期は 1.7 秒、ウォーム状態での送信者別グループ化は 4 ミリ秒でした。
• UIDVALIDITY を考慮した差分同期：2 回目以降の同期では、新しい UID のみを取得します。メールボックスの番号振り直しを自動検出し、全件再同期を実行します。
• キャッシュミスを明示：フォルダーが同期されていない場合、imap_search_cache は構造化された cache_miss エラーを返します。暗黙的に IMAP へフォールバックすることはありません。実行順序はスキルが調整します。
• スキルの自動インストール：同梱の Claude スキル（v2.17.0 の unsubscribe-cleanup）は、サーバー起動時に ~/.claude/skills/imap-mcp-pro/ へコピーされます。冪等性を備えており、バージョンが一致する場合はスキップし、同梱版のほうが新しい場合は更新し、ディスク上のコンテンツのほうがバージョンが高い場合は保持します。IMAP_MCP_SKIP_SKILLS_INSTALL=1 で無効にできます。
• 公開 GitHub からのスキル更新（v2.17.4+）：新しい 2 つのツール imap_check_skill_updates と imap_update_skills を使うと、.mcpb を再インストールせずに、このリポジトリから新しいバージョンのスキルを取得できます。PAT は不要です。デフォルトのソースは MCP 自身の公開リポジトリです。信頼モデルを含む詳しいガイドは docs/SKILLS.md を参照してください。

v2.0 の信頼性と添付ファイル（v2.15.0+）

• 送信済みフォルダーへの自動保存：imap_send_email は、プロバイダー（Gmail／Outlook／iCloud／Fastmail／Yahoo／Hostinger／Zoho／GMX／ProtonMail）に応じて、適切な送信済みフォルダーにメールを保存します。アーカイブコピーでは RFC 5322 §3.6.3 に従って Bcc が保持されます。失敗した場合は失われず、バックグラウンドで再試行するためにキューに追加されます。
• 分類された再試行機能を備えた SMTP プーリング：nodemailer のプールを使用し、一時的な障害には指数バックオフで再試行します。認証エラーは再試行せず、プロバイダー固有の案内（例：「Gmail ではアプリパスワードが必要です。こちらで生成してください…」）とともに即座に通知します。
• パスベースの添付ファイル（attachmentPaths）：base64 の代わりに絶対ファイルパスを渡します。サーバーは許可ディレクトリのホワイトリスト（ユーザーごとの上書き設定あり）に照らして検証し、realpath とシンボリックリンクのリンク先を確認して、サイズ上限を適用し、RFC 2183 に準拠してファイル名をサニタイズします。
• 分割アップロードによる添付ファイルの送信：サーバーのファイルシステムにアクセスできないクライアント向けです。4 ツールのワークフロー（stage_init → stage_append × N → stage_finalize → imap_send_email stagedAttachmentIds=[...]）です。順不同のチャンクも再構成され、重複した chunkIndex は冪等に処理されます。finalize 時に SHA-256 検証を行います。
• 診断ツール：imap_test_smtp、imap_test_sent_folder、imap_get_smtp_metrics、imap_list_unarchived_sends、imap_list_staged_attachments

エンタープライズ機能（Pro エディション）

レベル 1：接続性の強化

• ⚡ キープアライブの強化：RFC 2177 に準拠した NOOP コマンドを 29 分ごとに実行
• 🔌 接続の監視：接続の状態をリアルタイムで追跡
• ✅ 接続の検証：接続状態を事前に確認

レベル 2：信頼性の向上

• 🔄 自動再接続：指数バックオフ（1 秒 → 2 秒 → 4 秒 → 8 秒 → 最大 60 秒）
• ♻️ 再試行ロジック：すべての操作に透過的な再試行ラッパーを適用（最大 5 回）
• 🏥 ヘルスチェック：タイムアウト防止のため、29 分ごとに NOOP を実行
• 📊 接続状態マシン：DISCONNECTED → CONNECTING → CONNECTED → RECONNECTING → ERROR
• ⚡ 一括操作：削除、既読、マーク操作を効率的に一括処理

レベル 3：本番環境向けの高い回復性

• 🛡️ サーキットブレーカー：障害の連鎖を防止（5 回失敗で開き、2 回成功で閉じる）
• 📦 操作キュー：停止中は操作をキューに追加し、再接続後に再実行（最大 1000 件）
• 📈 包括的なメトリクス：接続ごと、操作ごとのメトリクス（操作数、成功率、レイテンシ、稼働率％）
• 🎯 段階的な機能縮退：読み取り専用モード、結果のキャッシュ（TTL 5 分）、最後に正常取得したデータへのフォールバック
• 🔍 強化された監視：MCP ツール（imap_get_metrics、imap_get_operation_metrics）でメトリクスをリアルタイムに取得

マルチテナント／MSP 環境へのデプロイ

🏢 MSP 向け商用ライセンスを提供しています

IMAP MCP Pro は、商用ライセンスのもとで、マネージドサービスプロバイダー（MSP）向けのマルチユーザー構成をサポートします。

• 👥 ユーザーの分離：顧客間のデータを完全に分離
• 🔐 顧客ごとの認証：テナントごとに個別の認証情報を使用
• 🛡️ ロールベースのアクセス制御：管理者とユーザーのロールに、きめ細かな権限を設定
• 📊 使用状況の追跡：顧客ごとの API 使用状況とメトリクス
• 🎛️ 一元管理：単一のインストールから複数の顧客環境を管理

設定：

{
  "mcpServers": {
    "imap-customer-a": {
      "env": {
        "MCP_USER_ID": "customer-a"
      }
    },
    "imap-customer-b": {
      "env": {
        "MCP_USER_ID": "customer-b"
      }
    }
  }
}

商用ライセンスに関するお問い合わせ先：

• メール：[email protected]
• MSP／マルチテナント環境へのデプロイには商用ライセンスが必要です
• 非商用利用は PolyForm Noncommercial License 1.0.0 のもとで無料です

インストール

Claude Desktop 拡張機能（.mcpb）— エンドユーザーに推奨

最も手早くセットアップするには、IMAP MCP Pro を Claude Desktop 拡張機能（.mcpb）としてインストールします。すべて（Node ランタイム、依存関係、ネイティブモジュール）が1つのアーカイブにまとめられ、Claude Desktop にネイティブの設定パネルが表示されるため、ターミナル操作や JSON の編集は必要ありません。

1. Releases ページから、お使いのプラットフォーム用の最新の .mcpb をダウンロードします（例：imap-mcp-pro-2.14.0-macos-arm64.mcpb）。
2. Claude Desktop で 設定 → 拡張機能 → 拡張機能をインストール… を開き、ダウンロードしたファイルを選択します。
3. 表示された設定パネルに入力します。
   • データディレクトリ — データベースとキャッシュの保存先（デフォルト：~/.imap-mcp-pro）
   • ログレベル — 日常的な使用には INFO、トラブルシューティングには DEBUG が適しています
   • 添付ファイルの最大サイズ — デフォルトは 25 MiB
   • 許可する添付ファイルのディレクトリ — 任意。パスを指定して添付ファイルを送信する場合にのみ必要です
   • 暗号化キー — ファイルベースのキーを自動生成する場合は空欄のままにします（~/.imap-mcp/.encryption-key に保存され、モードは 600）。認証情報は AES-256-GCM で暗号化されます（推奨）
   • ユーザー ID — 単一ユーザーのインストールでは default
4. 有効にする をクリックします。Claude に What IMAP accounts do I have? と尋ねて、簡単なテストを実行します。

インストール後にアカウントを追加するには、Claude に imap_add_account_auto（プロバイダーの自動検出機能付き）を使うよう依頼するか、Web UI を使用します。コマンドラインから imap-setup を実行してください。

アップグレードするには、新しい .mcpb をダウンロードして再インストールします。データディレクトリはそのまま保持されます。

macOS — パッケージインストーラー（推奨）

Releases ページから最新の .dmg をダウンロードします。

1. IMAP-MCP-Pro-x.x.x.dmg を開きます
2. 中にある .pkg をダブルクリックします
3. インストーラーの手順に従います。インストーラーは次の処理を行います。
   • Web UI のポート番号を尋ねます（デフォルト：4500）
   • Claude Desktop を自動的に設定するか確認します（インストール済みの場合）
   • メニューバーアプリ ImapMCPControl をインストールします
   • バックグラウンドサービスを登録して起動します

インストール後、メニューバーに封筒のアイコンが表示されます。設定を変更するには、いつでも 環境設定…（⌘,）を使用できます。

インストールされるもの：

パス	内容
~/.local/share/imap-mcp-pro/	サーバーファイル、バンドルされた Node.js ランタイム
~/Applications/ImapMCPControl.app	メニューバーのステータス／コントロールアプリ
~/Library/LaunchAgents/com.templeofepiphany.imap-mcp-pro.plist	バックグラウンドサービスの定義
~/.imap-mcp/	データベースと暗号化キー（初回実行時に作成）

macOS — アップグレード

既存のインストールに同じ .pkg インストーラーを実行します。インストーラーは以前のバージョンを検出し、次の処理を行います。

• ポート設定と Claude Desktop の設定を保持します
• サービスを停止し、サーバーファイルを置き換えた後、自動的に再起動します
• ~/.imap-mcp/（アカウントとデータ）には触れません

Linux／手動インストール

1. リポジトリをクローンします。

git clone https://github.com/Temple-of-Epiphany/imap-mcp-pro.git
cd imap-mcp-pro

2. 依存関係をインストールしてビルドします。

npm install
npm run build

3. サービスをインストールして起動します。

make install

アカウントのセットアップ

Web ベースのセットアップウィザード（推奨）

インストール後、セットアップウィザードを実行します。

npm run setup

グローバルにインストールした場合は、次のコマンドを実行します。

imap-setup

次の処理が行われます。

1. ローカルの Web サーバーを起動します
2. セットアップウィザードをブラウザーで開きます
3. 事前設定済みの設定を使ってメールアカウントを追加できるよう案内します

対応メールプロバイダー

セットアップウィザードには、次のプロバイダーの事前設定済みの設定が含まれています。

• Gmail／Google Workspace
• Microsoft Outlook／Hotmail／Live
• Yahoo Mail
• Apple iCloud Mail
• GMX
• WEB.DE
• IONOS (1&1)
• ProtonMail（Bridge を使用）
• Fastmail
• Hostinger
• Zoho Mail
• AOL Mail
• mailbox.org
• Posteo
• カスタム IMAP サーバー

設定

Claude Desktop の設定

macOS pkg インストーラー： Claude Desktop はインストール時に自動で設定されます。メニューバーアプリの Preferences… → Claude Desktop Integration から管理することもできます。

手動設定 — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "imap-mcp-pro": {
      "command": "/Users/YOUR_USERNAME/.local/share/imap-mcp-pro/runtime/node/bin/node",
      "args": ["/Users/YOUR_USERNAME/.local/share/imap-mcp-pro/dist/index.js"],
      "env": {
        "MCP_USER_ID": "YOUR_USERNAME"
      }
    }
  }
}

設定を変更したら、Claude Desktop を再起動してください。

環境変数

以下の環境変数は、Claude Desktop の設定で指定できます。

変数	説明	デフォルト	必須
MCP_USER_ID	マルチテナント環境で使用するユーザー識別子です。ユーザーごとにアカウントとデータを分離します。	default	いいえ
PORT	Web UI サーバーのポート番号	4500	いいえ
NODE_ENV	Node の環境モードです。詳細なエラースタックトレースを表示するには、development に設定します。	production	いいえ
IMAP_MCP_VERSION	バージョン識別子（インストーラーによって自動設定）	（パッケージのバージョン）	いいえ
IMAP_MCP_TOOL_PROFILE	サーバーが公開するツールを指定します。full（すべてのツール）または core（ツールの数が多いと対応できないホスト向けの、日常的に使う約29個のツール）を指定します。Claude Desktop 拡張機能では Tool Profile オプションです。ツールプロファイルを参照してください。	full	いいえ

ツールプロファイル

サーバーは約130個の MCP ツールを登録します。一部のホストではすべてのツールが通知されるものの、セッションには一つも表示されないことがあります（Claude Desktop Cowork ブリッジで確認されています、#293）。公開するツールの数は、拡張機能の Tool Profile オプション（または IMAP_MCP_TOOL_PROFILE）で選択します。

プロファイル	登録される内容
full（デフォルト）	すべてのツール。
core	日常的に使うツール（約29個）：ユーザー／アカウントの一覧表示とアカウントのテスト、検索、読み取り、最新メール、未読数、添付ファイル、送信、返信、転送、送信トレイのディレクトリ、フォルダー一覧とフォルダーのステータス、既読／未読への変更、移動、コピー、削除（単一および一括）、さらに imap_list_tools、imap_help、imap_about、imap_open_web_ui。

imap_list_tools は、常に有効なプロファイルと非表示のツール名を報告します。不明な値が指定された場合は、サーバーログに警告を記録して full にフォールバックします。オプションを変更したら、Claude Desktop を再起動してください。.mcpb マニフェストには、プロファイルに関係なく常に完全なカタログが記載されます。

複数ユーザー設定の例：

{
  "mcpServers": {
    "imap-work": {
      "command": "node",
      "args": ["/path/to/imap-mcp-pro/dist/index.js"],
      "env": {
        "MCP_USER_ID": "work",
        "PORT": "4500"
      }
    },
    "imap-personal": {
      "command": "node",
      "args": ["/path/to/imap-mcp-pro/dist/index.js"],
      "env": {
        "MCP_USER_ID": "personal",
        "PORT": "3001"
      }
    }
  }
}

注： 各 MCP_USER_ID に対して、以下が個別に作成されます。

• アカウントのストレージ（データベース）
• CleanTalk API キーの設定
• Web UI インスタンス（指定された PORT 上）
• セッションデータと認証情報

使用方法

設定すると、IMAP MCP サーバーは Claude で以下のツールを利用できるようになります。

アカウント管理

• imap_add_account：新しい IMAP アカウントを追加します

  Parameters:
  - name: Friendly name for the account
  - host: IMAP server hostname
  - port: Server port (default: 993)
  - user: Username
  - password: Password
  - tls: Use TLS/SSL (default: true)
  

• imap_list_accounts：設定済みのすべてのアカウントを一覧表示します

• imap_remove_account：アカウントを削除します

  Parameters:
  - accountId: ID of the account to remove
  

• imap_connect：アカウントに接続します

  Parameters:
  - accountId OR accountName: Account identifier
  

• imap_disconnect：アカウントとの接続を切断します

  Parameters:
  - accountId: Account to disconnect
  

メール操作

• imap_search_emails：メールを検索します

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - from, to, subject, body: Search criteria
  - since, before: Date filters
  - seen, flagged: Status filters
  - limit: Max results (default: 50)
  

• imap_get_email：メールの全文を取得します

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID
  

• imap_get_latest_emails：最近のメールを取得します

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - count: Number of emails (default: 10)
  

• imap_mark_as_read/unread：メールの既読状態を変更します

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID
  

• imap_delete_email：メールを削除します

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID
  

• imap_send_email：新しいメールを送信します

  Parameters:
  - accountId: Account ID to send from
  - to: Recipient email address(es)
  - subject: Email subject
  - text: Plain text content (optional)
  - html: HTML content (optional)
  - cc: CC recipients (optional)
  - bcc: BCC recipients (optional)
  - replyTo: Reply-to address (optional)
  - attachments: Array of attachments (optional)
    - filename: Attachment filename
    - content: Base64 encoded content
    - path: File path to attach
    - contentType: MIME type
  

• imap_reply_to_email：既存のメールに返信します

  Parameters:
  - accountId: Account ID
  - folder: Folder containing the original email
  - uid: UID of the email to reply to
  - text: Plain text reply content (optional)
  - html: HTML reply content (optional)
  - replyAll: Reply to all recipients (default: false)
  - attachments: Array of attachments (optional)
  

• imap_forward_email：既存のメールを転送します

  Parameters:
  - accountId: Account ID
  - folder: Folder containing the original email
  - uid: UID of the email to forward
  - to: Forward to email address(es)
  - text: Additional text to include (optional)
  - includeAttachments: Include original attachments (default: true)
  

• imap_copy_email：メールを別のフォルダーにコピーします

  Parameters:
  - accountId: Account ID
  - sourceFolder: Source folder name (default: INBOX)
  - uid: Email UID to copy
  - targetFolder: Target folder name
  

• imap_bulk_copy_emails：複数のメールを別のフォルダーに一括コピーします

  Parameters:
  - accountId: Account ID
  - sourceFolder: Source folder name (default: INBOX)
  - uids: Array of email UIDs to copy
  - targetFolder: Target folder name
  

• imap_move_email：メールを別のフォルダーに移動します

  Parameters:
  - accountId: Account ID
  - sourceFolder: Source folder name (default: INBOX)
  - uid: Email UID to move
  - targetFolder: Target folder name
  

• imap_bulk_move_emails：複数のメールを別のフォルダーに一括移動します

  Parameters:
  - accountId: Account ID
  - sourceFolder: Source folder name (default: INBOX)
  - uids: Array of email UIDs to move
  - targetFolder: Target folder name
  

自動チャンク処理（スマートな一括操作）

すべての一括操作で、UID が 50 件を超える場合は自動的にチャンク処理が使用されるようになりました！ 通常のツールとチャンク処理ツールのどちらを使うか選ぶ必要はありません。システムが状況に応じて自動的に処理します。

仕組み：

• UID が 50 件以下：高速な単一バッチ処理
• UID が 50 件を超える場合：自動チャンク処理（1 チャンクあたり UID 100 件）
• 進行状況の追跡：サーバーログにリアルタイムで記録
• エラーからの回復：個々のチャンクが失敗しても処理を続行

チャンク処理による一括操作（大規模処理）

チャンク処理の動作を明示的に制御する場合：

• imap_bulk_mark_emails_chunked：大規模な操作でメールをチャンク単位でマーク

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uids: Array of email UIDs to mark (supports 1000+ UIDs)
  - operation: Mark operation (read, unread, flagged, unflagged, answered, unanswered, draft, not-draft, deleted, undeleted)
  - chunkSize: Number of emails per chunk (default: 100)
  
  Returns:
  - processed: Number of successfully processed emails
  - failed: Number of failed emails
  - errors: Array of error details for failed chunks
  

• imap_bulk_delete_emails_chunked：大規模な操作でメールをチャンク単位で削除

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uids: Array of email UIDs to delete (supports 1000+ UIDs)
  - expunge: Permanently expunge deleted emails (default: false)
  - chunkSize: Number of emails per chunk (default: 100)
  
  Returns:
  - processed: Number of successfully deleted emails
  - failed: Number of failed emails
  - errors: Array of error details for failed chunks
  

• imap_bulk_get_emails_chunked：大規模な操作でメールをチャンク単位で取得

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uids: Array of email UIDs to fetch (supports 1000+ UIDs)
  - fields: Fields to fetch (headers, body, or full)
  - chunkSize: Number of emails per chunk (default: 100)
  
  Returns:
  - count: Number of successfully fetched emails
  - totalRequested: Total number of UIDs requested
  - emails: Array of fetched email objects
  

ユースケースの例： 未読メール 1700 件を処理し、一括マーケティングメッセージに削除マークを付ける場合：

1. 未読メールを検索します：imap_search_emails で seen: false を指定
2. ヘッダーをチャンク単位で取得します：UID 1700 件と chunkSize: 100 を指定して imap_bulk_get_emails_chunked を実行
3. アプリケーションのロジックでマーケティングメールをフィルタリングします
4. チャンク単位で削除します：フィルタリング済みの UID を指定して imap_bulk_delete_emails_chunked を実行

メリット：

• 小さなバッチで処理するため、サーキットブレーカーの作動を防止します
• 個々のチャンクが失敗しても処理を続行します
• 進行状況を追跡し、エラーを報告します
• チャンク間に 100ms の遅延を設けることで、サーバーの過負荷を防ぎます

フォルダー操作

• imap_list_folders：すべてのフォルダーを一覧表示

  Parameters:
  - accountId: Account ID
  

• imap_folder_status：フォルダー情報を取得

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  

• imap_get_unread_count：未読メール数をカウント

  Parameters:
  - accountId: Account ID
  - folders: Specific folders (optional)
  

削除

macOS

メニューバーアプリを使用するか、プロジェクトディレクトリから実行します：

# Interactive uninstall (prompts before removing data)
make uninstall

# Or run the script directly
distributions/osx/scripts/uninstall.sh

アンインストーラーは次の処理を行います：

• LaunchAgent を停止して削除します
• ~/Applications/ImapMCPControl.app を削除します
• ~/.local/share/imap-mcp-pro/ を削除します
• pkgutil のレシートを削除します
• ~/.imap-mcp/（アカウントとデータ）を削除する前に確認します
• Claude Desktop の MCP エントリを削除する前に確認します

Linux

make uninstall

---

バックアップと復元

データは ~/.imap-mcp/ に保存され、次のファイルで構成されます：

ファイル	内容
data.db	SQLite データベース — すべてのアカウント、設定、履歴
.encryption-key	保存されたパスワードを暗号化する AES-256 暗号化キー
.key	予備のキーファイル

重要： キーファイルがないバックアップでは、保存されたパスワードを復号できません。必ず ~/.imap-mcp/ ディレクトリ全体をまとめてバックアップしてください。

WAL モード（v2.34.0+）： データベースは SQLite WAL ジャーナリングを使用しているため、複数のサーバーで共有できます（Claude Desktop はホストごとに 1 つのサーバーを実行します）。最近の書き込みはチェックポイント処理まで data.db-wal に残ることがあるため、cp で data.db をコピーしてバックアップしないでください。以下のバックアップ機能を使うか、sqlite3 ~/.imap-mcp/data.db ".backup '/path/to/copy.db'" を実行してください。

バックアップ

メニューバーアプリ： 「環境設定…」→「データベース」→「バックアップ」
データベースと 2 つのキーファイルを含む .zip ファイルを保存します。

コマンドライン：

# Save to ~/imap-mcp-pro-backup-YYYY-MM-DD.zip
make backup

# Save to a specific path
scripts/backup.sh /path/to/backup.zip

スクリプトは sqlite3 .backup を使って一貫性のあるスナップショットを取得するため（サーバーの実行中でも安全です）、sqlite3 コマンドラインツールをインストールしておく必要があります。

復元

メニューバーアプリ： 「環境設定…」→「データベース」→「復元」
.zip バックアップを選択すると、サービスが停止し、データが置き換えられてからサービスが再起動します。

コマンドライン：

make restore FILE=/path/to/backup.zip

# Or directly
scripts/restore.sh /path/to/backup.zip

復元スクリプトは、ファイルを置き換える前にサービスを停止し、完了後に自動的に再起動します。

---

セキュリティ

• 認証情報は AES-256-GCM 暗号化を使用して暗号化されます
• 暗号化キーは ~/.imap-mcp/ に別途保存されます
• データベースは ~/.imap-mcp/data.db に保存されます
• 暗号化キーやデータベースをコミットしたり共有したりしないでください

プライバシーポリシー

IMAP MCP Pro はすべてお使いのデバイス上で動作し、発行元にデータを送信することはありません。テレメトリはなく、当社が運営するサーバーもありません。処理するのは、お客様が設定したメールアカウントのみです。認証情報は保存時に暗号化され（AES-256-GCM）、すべてのローカルファイルは所有者のみがアクセスできます。データがお使いのマシンから外部に送信されるのは、お客様の指示による場合に限られます。送信先は、お客様自身の IMAP/SMTP サーバー、有効にしたオプションの連携（スパムチェック用の UserCheck、ファイアウォールチェック用の DNS-over-HTTPS プロバイダー）、および使用する Claude クライアントです。データはお客様が削除するまで（アカウントの削除、キャッシュの消去、または ~/.imap-mcp/ の削除）ローカルにのみ保存されます。

データの収集、保存、第三者との共有、保持期間、お問い合わせ先を含むポリシー全文：PRIVACY.md。

開発

開発モードでの実行

npm run dev

ビルド

npm run build

プロジェクト構成

src/
├── index.ts           # MCP server entry point
├── services/
│   ├── imap-service.ts    # IMAP connection management
│   ├── smtp-service.ts    # SMTP service for sending emails
│   └── database-service.ts # Encrypted account/user storage (SQLite)
├── tools/
│   ├── index.ts          # Tool registration
│   ├── account-tools.ts  # Account management tools
│   ├── email-tools.ts    # Email operation tools (including send/reply/forward)
│   └── folder-tools.ts   # Folder operation tools
└── types/
    └── index.ts          # TypeScript type definitions

Claude での使用例

1. アカウントを追加する： 「ユーザー名 [email protected] で Gmail アカウントを追加して」

2. 新着メールを確認する： 「Gmail アカウントの最新のメールを 5 件表示して」

3. メールを検索する： 「過去 1 週間に [email protected] から届いたメールを検索して」

4. メールを送信する： 「件名を『Project Update』にして、[email protected] にメールを送信して」

5. メールに返信する： 「上司から届いた最新のメールに返信して」

6. メールを転送する： 「件名が『Meeting Notes』のメールを [email protected] に転送して」

7. フォルダーを管理する： 「メールアカウント内のすべてのフォルダーを一覧表示し、未読件数も表示して」

トラブルシューティング

接続の問題

• IMAP サーバーの設定が正しいことを確認してください
• メールプロバイダーでアプリ専用パスワードが必要かどうか確認してください
• メールアカウントの設定で IMAP が有効になっていることを確認してください
• メールを送信する場合は、アカウントで SMTP アクセスが有効になっていることを確認してください

SMTP の設定

サーバーは IMAP プロバイダーに基づいて SMTP の設定を自動的に構成します。独自の SMTP 設定が必要な場合は、アカウントの追加時に指定できます。

{
  "smtp": {
    "host": "smtp.example.com",
    "port": 587,
    "secure": false
  }
}

一般的な IMAP 設定

• Gmail：

  • ホスト：imap.gmail.com
  • ポート：993
  • アプリ専用パスワードが必要です

• Outlook/Hotmail：

  • ホスト：outlook.office365.com
  • ポート：993

• Yahoo：

  • ホスト：imap.mail.yahoo.com
  • ポート：993
  • アプリ専用パスワードが必要です

トラブルシューティング

ログの保存先はどこですか？

Claude Desktop は、サーバーの stderr をサーバーごとのログファイルに記録します。

プラットフォーム	パス
macOS	~/Library/Logs/Claude/mcp-server-imap-mcp-pro.log
Windows	%APPDATA%\Claude\logs\mcp-server-imap-mcp-pro.log
Linux	~/.local/state/Claude/logs/mcp-server-imap-mcp-pro.log

[startup] stage=pre-handshake outcome=ok duration_ms=12 のような行を確認し、サーバーが正常に起動していることを確かめてください。pre-handshake が 2 秒を超えると、outcome=warning の行が表示されます。

よくある問題

「設定は有効」と表示されるのに、実行時にツールが失敗する node /path/to/server/dist/index.js --validate-config を実行します（または .mcpb 拡張機能にバンドルされたサーバー経由で実行します）。解決されたすべての値が出力され、ファイルシステムの権限に関する問題はスキーマエラーとは別に示されます。

起動時のデータベースエラー（終了コード 2） 通常はデータディレクトリの権限が原因です。--validate-config で database.path を確認してください。親ディレクトリに書き込み権限が必要です。

初回呼び出し時にツールが「準備中」と応答する バックグラウンドサービスの初期化がまだ完了していません（ハンドシェイク後の段階です）。数秒待ってから再試行してください。解消しない場合は、ログに outcome=error の行がないか確認してください。

Claude Desktop でサーバーが応答しないように見える 多くの場合、ハンドシェイク前のタイムアウトが原因です。まず --validate-config で確認してください。問題がなければ、ログのハンドシェイク前の duration_ms を確認します。2000 を超えるとタイムアウトします。

環境変数が設定に反映されない --validate-config を実行し、フィールドの横にある [source] タグを確認してください。優先順位の高い順に、ソースは cli > env > file > default です。[env] を期待していたのに [default] と表示される場合は、環境変数名が間違っている可能性があります。正規の対応表については src/config/server-config.ts:ENV_VAR_MAPPING を参照してください。

設定スキーマの確認

node dist/index.js --print-config-schema | jq .

ServerConfig の完全な JSON Schema を返します。各フィールドの型、デフォルト値、説明、検証範囲を確認できます。

ツールカタログの確認

node dist/index.js --print-tools-manifest | jq '.tools | length'

ドキュメント

• EXAMPLES.md — 一般的なワークフローでの Claude との会話例
• docs/SKILLS.md — バンドルされたスキル、自動インストールの動作、GitHub 更新ツール、コントリビューターガイド
• docs/ARCHITECTURE.md — コードベースの構成、起動段階、応答形式の方針、コントリビューターガイド
• docs/sdk_audit_2026-04-29.md — MCP SDK 準拠状況の監査
• RFC 9051（IMAP4rev2）の全文は rfc/rfc9051.txt にあります

ライセンス

個人利用は無料です。商用利用は有料です。

このソフトウェアはデュアルライセンスモデルで配布されています。非商用利用向けの PolyForm Noncommercial License 1.0.0 と、それ以外のすべての用途向けの別途商用ライセンスです。適用されるライセンスは、ソフトウェアの利用方法によって決まります。

✅ 非商用利用 — 無料（PolyForm Noncommercial License 1.0.0）

PolyForm Noncommercial License に基づく許可された（非商用の）目的で利用する場合、このソフトウェアを無償で使用、複製、変更、配布できます。対象には以下が含まれます。

• 自身のアカウントでの個人的なメール管理
• 教育目的での利用（学生、講師、教室）
• 学術研究プロジェクト
• 条件を満たす非営利団体の内部業務
• オープンソースプロジェクトの開発
• 評価、テスト、概念実証の作業

許可された（非商用の）目的であれば、変更や新しい著作物を作成できます。（PolyForm Noncommercial は、同一条件での共有やコピーレフトの義務を課しません。）

💼 商用ライセンス — 有料（必須）

以下のいずれかに該当する用途では、このソフトウェアを使用する前に有料の商用ライセンスを取得する必要があります。

• 営利企業の業務でのメール運用
• SaaS 製品、ホステッドサービス、有料サービス
• マルチテナントまたは MSP（マネージドサービスプロバイダー）での導入
• 収益を生み出すサービスの本番環境への導入
• 商用製品の一部としての再配布
• 収益を得ている組織による利用（条件を満たす非営利団体の内部業務を除く）

上記の無料利用の一覧に該当しない場合は、ユーザーにメール機能の料金を直接請求していなくても、商用ライセンスが必要です。

商用ライセンスの取得

連絡先： [email protected] 組織： Temple of Epiphany

商用ライセンスには、サポートとメンテナンス、優先的なバグ修正、本番環境への導入権、法的補償が含まれます。永続ライセンスとサブスクリプションの両方を選択できます。

どちらに該当するかわからない場合

ご利用目的が非商用の一覧に明確に当てはまらない場合は、商用ライセンスが必要であると想定し、メールでお問い合わせください。喜んでご案内します。

法的条項の全文：LICENSE。

帰属表示

このプロジェクトは、Michael Nikolaus が作成したオリジナルの IMAP MCP Server を基に、エンタープライズ向けに強化したフォークです。

オリジナルプロジェクト： https://github.com/nikolausm/imap-mcp-server オリジナルの作者： Michael Nikolaus オリジナルのライセンス： MIT License（ベースコードのみに適用）

Temple of Epiphany では、上記のデュアルライセンスモデルの対象となるエンタープライズ機能（レベル 1～3）を大幅に追加しています。

貢献

皆さまからの貢献を歓迎します。商用利用に関する貢献について、貢献者は自身の貢献がプロジェクトのデュアルライセンスモデルの対象となることに同意するものとします。

以下について、プルリクエストをお気軽にお送りください。

• バグ修正
• ドキュメントの改善
• 新機能
• パフォーマンスの向上

大規模な変更については、まず issue を作成し、変更内容についてご相談ください。