imap-mcp-server

IMAP MCP サーバー

安全なアカウント管理とコネクションプーリングにより、シームレスな IMAP メール連携を実現する、強力な Model Context Protocol（MCP）サーバーです。

機能

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

インストール

Node.js 22.12 以降が必要です。 Node 18 と 20 はどちらも サポート終了となっており、このパッケージの依存関係の一部は すでに対応を終了しています。node --version でバージョンを確認してください。

npx で実行（インストール不要）

npm で公開された後は、リポジトリのクローンやビルドを行わずにサーバーを直接実行できます。npx がビルド済みパッケージをダウンロードして実行します。

npx -y imap-mcp-server

MCP クライアントでサーバーを使う最も簡単な方法です（すぐに貼り付けて使える npx の設定については、設定を参照してください）。

クイックインストール（推奨）

macOS/Linux：

curl -fsSL https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.sh | bash

Windows（管理者として PowerShell を実行）：

iwr -useb https://raw.githubusercontent.com/nikolausm/imap-mcp-server/main/install.ps1 | iex

手動インストール

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

git clone https://github.com/nikolausm/imap-mcp-server.git
cd imap-mcp-server

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

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

アカウントは ~/.imap-mcp/accounts.json に暗号化して保存されます。このファイルはすべての実行モードで共有されます。npx、グローバルインストール、ローカルクローンのいずれからサーバーを起動しても、同じアカウントファイルを読み込みます。そのため、アカウントのセットアップは一度だけで済みます。

npx モードでのアカウント設定

サーバーを npx で実行する場合（クローンなし）、アカウントを追加する方法は 2 つあります。

方法 A — セットアップウィザードを npx で直接実行（インストール不要）：

npx -p imap-mcp-server imap-setup

以下で説明するものと同じウェブベースのウィザードが起動し、~/.imap-mcp/accounts.json に設定が書き込まれます。その後、npx で設定した MCP サーバーが自動的にその内容を読み込みます。

方法 B — AI クライアントからアカウントを直接追加：

MCP サーバーを設定したら、アシスタントにアカウントを追加するよう依頼するだけです。imap_add_account ツールが使用されます。例：

「IMAP アカウントを追加してください：ホスト imap.gmail.com、ポート 993、ユーザー [email protected]、パスワード …」

別途セットアップする必要はありません。

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

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

npm run setup

グローバルインストールした場合：

imap-setup

または、インストールせずに npx から直接実行します：

npx -p imap-mcp-server imap-setup

実行すると、次の処理が行われます：

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

ウィザードは 127.0.0.1 のみで待ち受けるため、ネットワーク上の他の機器からアクセスされることはありません。

別のマシン（サーバー、NAS、VM）でウィザードを実行する

推奨：SSH トンネル。 ウィザードはループバック上で動作し、接続は暗号化されます。

ssh -L 3000:localhost:3000 my-server      # then, on the server:
imap-setup --no-open

ローカルのブラウザーで http://localhost:3000 を開きます。

別の方法：ネットワークにバインドする。 --host を渡すか、IMAP_MCP_BIND を設定します。

imap-setup --host 0.0.0.0 --no-open

この場合、ウィザードではアクセス トークンが必要になり、トークンを含む URL が出力されます。例： http://my-server:3000/?token=…。その URL を開くと、トークンはセッション Cookie と交換され、アドレスバーから削除されます。トークンのないリクエストと、クロスオリジンのリクエストは拒否されます。スクリプトでは、代わりに Authorization: Bearer <token> を送信できます。起動ごとにランダムなトークンを使うのではなく固定トークンを使うには、IMAP_MCP_WIZARD_TOKEN を設定します（16 文字以上）。その場合、トークンは出力されません。

接続は通常の HTTP であるため、ネットワークトラフィックを読み取れる人は誰でも、トークンと入力したパスワードを確認できます。信頼できるネットワークでのみ使用し、それ以外の場合は SSH トンネルを優先してください。

変数	デフォルト	意味
IMAP_MCP_BIND	127.0.0.1	ウィザードがバインドするアドレス（--host が優先されます）
IMAP_MCP_WIZARD_TOKEN	起動ごとにランダム	ループバック以外にバインドする場合のアクセストークン
PORT	3000	npm run web のポート（imap-setup では --port を使用します）

環境変数による認証情報の上書き

環境変数を使って、設定済みアカウントのユーザー名とパスワードを実行時に上書きできます。accounts.json に保存する代わりに、パスワードマネージャーや CI システムからシークレットを渡す場合に便利です。

変数名にはアカウントの名前を使用し、大文字に変換したうえで、英数字以外の文字をすべて _ に置き換えます。アカウント名が Work Gmail の場合（キーは WORK_GMAIL）：

変数	上書きする項目
IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_USERNAME	IMAP ユーザー名（user）
IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD	IMAP パスワード
IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_USERNAME	SMTP ユーザー名（smtp.user）
IMAP_MCP_ACCOUNT_WORK_GMAIL_SMTP_PASSWORD	SMTP パスワード

注意：

• 上書きが適用されるのは既存のアカウントのみです。正規化された名前が一致するアカウントがない場合、変数は無視されます。
• 上書きはメモリ内でのみ適用されます。accounts.json に書き戻されず、値はそのまま使用されます（再暗号化されません）。
• 変数は起動時に読み込まれます。サーバーの起動時に値が取得され、AES-256 で暗号化されたインメモリーキャッシュに保存された後、process.env から削除されます。これにより、平文のシークレットが環境内に残り（子プロセスや診断情報から漏えいする可能性があり）続けるのを防ぎます。サーバーを起動する前に設定してください。

セットアップウィザードにもこの機能が統合されています。各認証情報の入力欄（IMAP パスワード、IMAP ユーザー名、SMTP ユーザー名、SMTP パスワード）には、**「設定に保存せず、後で環境変数を使用して設定する」**チェックボックスがあります。チェックを入れても、入力した値は接続テストに使用されますが、accounts.json には書き込まれません。ウィザードにはエクスポートする正確な変数名が表示され、アカウントは実行時にその変数から認証情報を取得します。

• SMTP の変数が有効になるのは、アカウントに SMTP 設定がすでにある場合のみです。
• 各変数は個別に有効になります。必要なものだけを設定してください。

変数が設定されていない場合、アカウントにはウィザードが書き込んだ空のプレースホルダーが残ります。空の認証情報で接続を試みると、プロバイダーから誤ったパスワードの場合とまったく同じ一般的な認証エラーが返されるため、サーバーは接続を拒否し、設定すべき変数名を示します。

Account "Work Gmail" has IMAP credentials marked as environment-managed, but
this variable was not set when the server started:
IMAP_MCP_ACCOUNT_WORK_GMAIL_IMAP_PASSWORD. Set it and restart the server, or
store the credentials on the account via imap_update_account.

変数は起動時に一度だけ読み込まれるため、すでに実行中のシェルで設定しても、サーバーを再起動するまでは反映されません。

対応メールプロバイダー

セットアップウィザードには、以下の事前設定が含まれています。

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

設定

Claude Code（CLI）

オプション A — npx を使用する（クローン／ビルド不要）

claude mcp add imap -- npx -y imap-mcp-server

公開されている最新バージョンが常に実行され、ローカルでのビルドは不要です。

オプション B — ローカルのクローンから実行する

ターミナルで Claude Code を使用している場合は、1 つのコマンドで MCP サーバーを追加できます。

手順 1： まず、プロジェクトをビルドしてください（手動インストールを参照）。

手順 2： ターミナルで次のコマンドを実行します。

claude mcp add imap -- node /absolute/path/to/imap-mcp-server/dist/index.js

重要： /absolute/path/to/imap-mcp-server を、リポジトリをクローンした実際のパスに置き換えてください。例：

# macOS/Linux の例：
claude mcp add imap -- node /Users/yourname/imap-mcp-server/dist/index.js

# Windows の例：
claude mcp add imap -- node C:\Users\yourname\imap-mcp-server\dist\index.js

手順 3： 追加されたことを確認します。

claude mcp list

設定済み MCP サーバーの一覧に imap が表示されます。これで完了です。IMAP ツールが Claude Code のセッションで利用できるようになりました。

ヒント： 後でサーバーを削除する場合は、次を実行します。

claude mcp remove imap

Claude Desktop（GUI アプリ）

Claude Desktop の設定ファイルに IMAP MCP サーバーを追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

オプション A — npx を使用する（推奨、クローン／ビルド不要）：

{
  "mcpServers": {
    "imap": {
      "command": "npx",
      "args": ["-y", "imap-mcp-server"],
      "env": {}
    }
  }
}

オプション B — ローカルのクローンから実行する：

{
  "mcpServers": {
    "imap": {
      "command": "node",
      "args": ["/path/to/imap-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

ツールへのアクセスを制限する（読み取り専用モード／許可リスト）

デフォルトでは、すべてのツールが公開されます。MCP 設定の env キーで設定する 2 つの環境変数を使って、エージェントに表示するツールを制限できます。メールボックスへの読み取り専用アクセスをアシスタントに許可する場合や、選択したツールだけを公開する場合に便利です。

変数	効果
IMAP_MCP_READ_ONLY	真偽値として有効な値（1、true、yes、on）が設定されている場合、安全な読み取り専用ツールのみが登録されます。検索、メールの読み取り、フォルダーの一覧表示、未読件数の確認、スパム分析が含まれます。メールの送信、メッセージの削除／移動、フラグの変更、アカウントの編集を行うツールは公開されません。
IMAP_MCP_ENABLED_TOOLS	ツール名をカンマ区切りで指定する許可リストです。指定したツールのみが登録されます。名前の大文字と小文字は区別されず、imap_ プレフィックスは省略できます（search_emails ≡ imap_search_emails）。設定されている場合、IMAP_MCP_READ_ONLY より優先されます。

例 — 読み取り専用アクセス：

{
  "mcpServers": {
    "imap": {
      "command": "npx",
      "args": ["-y", "imap-mcp-server"],
      "env": { "IMAP_MCP_READ_ONLY": "true" }
    }
  }
}

例 — 明示的な許可リスト：

{
  "mcpServers": {
    "imap": {
      "command": "npx",
      "args": ["-y", "imap-mcp-server"],
      "env": { "IMAP_MCP_ENABLED_TOOLS": "imap_search_emails,imap_get_email,imap_get_latest_emails" }
    }
  }
}

読み取り専用のツールは次のとおりです：imap_list_accounts、imap_connect、imap_disconnect、 imap_test_account、imap_search_emails、imap_get_email、 imap_get_latest_emails、imap_download_attachment、imap_find_thread_messages、 imap_find_email_by_message_id、imap_list_folders、imap_folder_status、 imap_get_unread_count、imap_check_spam、imap_domain_stats、 imap_list_spam_domains。

使用方法

設定が完了すると、IMAP MCP サーバーから次のツールを Claude で利用できます。

アカウントの選択。 メールおよびフォルダーツールでは、accountId は省略可能で、後方互換性があります。代わりに accountName を渡すこともできます。また、設定済みのアカウントが1 つだけの場合は、どちらも省略できます。そのアカウントがデフォルトで使用されます。複数のアカウントがあり、選択指定がない場合、ツールは選択肢を列挙した明確なエラーを返します（imap_list_accounts）。

アカウント管理

• 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)
  - allowStartTLS: When tls is false, set to false to also disable the
      opportunistic STARTTLS upgrade imapflow otherwise attempts whenever the
      server advertises it (validating the cert against `host` regardless of
      `tls`). Needed for providers that advertise STARTTLS on a hostname
      covered only by a shared/wildcard cert. Defaults to true.
  - sentFolder: Explicit Sent-folder name for sent-mail copies, e.g. "Gesendet"
      (optional — only needed when the server has no \Sent SPECIAL-USE folder
      and auto-detection fails)
  - defaultBcc: Optional BCC address(es) applied automatically to every
      outbound send, reply, forward, and draft for this account. Merged with
      any per-call `bcc` (duplicates removed case-insensitively)
  - allowedFrom: Optional list of additional sender identities permitted in
      outbound `From` headers. The account email and login are always allowed
  

• imap_update_account：既存のアカウントを更新します（SMTP 設定の修正、名前の変更など）

  Parameters:
  - accountId: ID of the account to update
  - name, host, port, user, password, tls, allowStartTLS, email: IMAP fields (all optional)
  - smtpHost, smtpPort, smtpSecure, smtpUser, smtpPassword: SMTP fields (optional)
  - saveToSent: Save sent emails to the Sent folder (optional)
  - sentFolder: Explicit Sent-folder override (optional). Pass an empty string
      to clear the override and re-enable auto-detection
  - defaultBcc: Optional default BCC address(es) (optional). Pass an empty
      string to clear
  - allowedFrom: Optional list of additional sender identities. Pass an empty
      array to clear
  

allowedFrom はアプリケーションレベルのガードレールであり、強固なセキュリティ境界ではありません。 imap_update_account にアクセスできるエージェントは、許可される送信元 ID を変更できます。 実際の送信者認可ポリシーは SMTP サーバーで適用する必要があります。送信者の メールボックスアドレスは大文字と小文字を区別せずに照合されます。指定された表示名と アドレスの大文字・小文字は、送信される From ヘッダーにそのまま保持されます。これは 送信、下書き、返信、転送に適用されます。

• 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; ignored when searchAllFolders is true)
  - searchAllFolders: Search across ALL folders at once (default: false).
      Skips Trash/Spam/Drafts and non-selectable folders by default. Use when a
      message may have been filed/moved/archived and you don't know its folder.
  - includeTrash, includeSpam, includeDrafts: Opt those noisy folders back into
      a searchAllFolders run (default: false each)
  - from, to, subject, body: Search criteria
  - since, before: Date filters
  - seen, flagged: Status filters
  - keywords: Match messages with ANY of these custom keywords (server-side OR).
      Read a mailbox's available custom keywords from `imap_folder_status`'s
      `customKeywords` field first.
  - unKeywords: Exclude messages with ANY of these custom keywords (result has
      NONE of them). Same keyword source as `keywords`.
  - limit: Max results (default: 50)
  - includeBody: Include parsed message body in the response (default: false).
      Fetches the RFC822 source once and parses it with mailparser, so you get
      uid + body in a single tool call instead of paying the N+1 cost of one
      `imap_get_email` per match. Body is rendered per `bodyFormat` and capped
      at `bodyMaxLength` per field.
  - bodyFormat: How to render the body when `includeBody` is true — `markdown`
      (default, clean Markdown via Turndown), `text`, `html`, or `auto`.
  - bodyMaxLength: Per-field cap when `includeBody` is true (default: 10000).
  

  searchAllFolders を指定すると、結果にはメッセージごとの folder フィールドと foldersSearched が含まれます。また、開けなかったフォルダーは foldersErrored に報告されます（そのため、検索結果が 0 件でも、不完全な結果が 気付かれないまま返されることはありません）。

  includeBody が適用されるのは、単一フォルダーを対象とする場合のみです。 複数フォルダーを横断して検索する場合は、設計上、軽量なヘッダー形式が維持されます。 多数のフォルダーで一致したすべてのメールの RFC822 ソースを取得すると、 帯域幅と解析コストが大幅に増加するためです。本文が必要な UID については、 imap_get_email を呼び出して取得してください。

  一部のサーバーでは、「フラグ付き」／スター付きのメッセージに \Flagged システムフラグの 代わりに、またはそれに加えて、カスタムキーワード（Open-Xchange のカラーラベルや Apple の $MailFlagBit* など）が付与されます。フラグ付きメールを検索した後は、 メッセージがフラグ付きかどうかを判断する前に、各結果の customKeywords フィールドを 確認してください。

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

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID
  - maxContentLength: Max characters for text/html body (default: 10000)
  - includeAttachmentText: Include text attachment previews (default: true)
  - maxAttachmentTextChars: Max characters per text attachment (default: 100000)
  

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

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - count: Number of emails (default: 10)
  - includeBody: Include parsed message body (default: false). Same semantics
      as the `includeBody` option on `imap_search_emails` — one round-trip
      instead of N×`imap_get_email`.
  - bodyFormat: `markdown` (default), `text`, `html`, or `auto`.
  - bodyMaxLength: Per-field cap (default: 10000).
  

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

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID, OR an array of UIDs to flag in one call. Batch uses a
      single IMAP STORE so the operation is atomic at the server level — all
      UIDs are flagged, or none. Useful when triaging many messages at once.
  

• imap_flag_email/unflag_email：メールにスターを付ける／外します（IMAP の \Flagged システムフラグを設定または解除します。Gmail や Apple Mail では「スター」として表示されます）。一部のサーバー／クライアント（Open-Xchange、Apple Mail）では、フラグを付ける際に別のカスタムキーワード（$cl_N、$MailFlagBit* など）も設定されます。フラグ解除でクリアされるのは \Flagged のみです。そのため、メッセージが引き続きフラグ付きと表示される場合は、imap_get_email で customKeywords を確認し、imap_remove_keyword でそのキーワードをクリアしてください。

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

• imap_add_keyword/remove_keyword：メールの任意の カスタム（システム以外の）IMAP キーワード／ラベルを、指定したとおりに設定または解除します（Open-Xchange の $cl_1～$cl_10 や Apple Mail の $MailFlagBit0～$MailFlagBit2 などのプロバイダーのカラーラベル、その他のカスタムキーワードを指定できます）。バックスラッシュで始まるシステムフラグ（\Flagged、\Seen、\Deleted など）は拒否されます。これらには専用のフラグ／既読状態変更ツールを使用してください。すべてのサーバーがカスタムキーワードの変更を許可するわけではありません（メールボックスの PERMANENTFLAGS を参照）。サーバーが変更を拒否するか、変更を無視した場合、この呼び出しは成功を報告せず失敗します。

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  - uid: Email UID
  - keyword: IMAP keyword to set/remove (e.g. "$cl_3")
  

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

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

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

  Parameters:
  - accountId: Account ID
  - folder: Source folder name (default: INBOX)
  - uid: Email UID, OR an array of UIDs to move in one call. Batch moves are
      attributed per-uid in the response (`results[]` with per-uid `uidMap`
      and any errors). Single-uid calls return the legacy response shape.
  - targetFolder: Destination folder name
  - createDestinationIfMissing: Create the destination folder if it does not exist (default: false)
  

• imap_find_thread_messages：別のフォルダーにすでに振り分けられたメッセージと同じ会話スレッドに属する、受信トレイのメッセージを検索します。In-Reply-To と References に対する RFC 3501 HEADER 検索を使用するため、あらゆる IMAP サーバーで動作します。

  Parameters:
  - accountId: Account ID
  - sourceFolder: Folder containing the already-sorted thread messages
  - searchFolder: Folder to search for related messages (default: INBOX)
  - searchReferences: Also match the References header for multi-level threads (default: true)
  - includeBody: Include parsed message body for each found thread message
      (default: false). Same semantics as the `includeBody` option on
      `imap_search_emails` — one round-trip instead of N×`imap_get_email`.
  - bodyFormat: `markdown` (default), `text`, `html`, or `auto`.
  - bodyMaxLength: Per-field cap (default: 10000).
  

• imap_download_attachment：メールの添付ファイルをダウンロードします（画像はインラインで返し、PDF からはテキストを抽出するか、ダウンロードディレクトリに保存します）

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uid: Email UID
  - filename: Attachment filename or contentId (as listed by imap_get_email; NFC/NFD
      spellings of accented characters are treated as equal, and a contentId may
      be passed with or without angle brackets)
  - savePath: Optional file path to save the attachment to
  - extractText: For PDFs, extract and return text content inline (default: true)
  

• imap_bulk_delete：チャンク処理と自動再接続により、複数のメールを一度に削除します

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - uids: Array of email UIDs to delete
  - chunkSize: Emails to delete per batch (default: 50)
  

• imap_bulk_delete_by_search：条件に一致するメールを検索してすべて削除します

  Parameters:
  - accountId: Account ID
  - folder: Folder name (default: INBOX)
  - from, to, subject: Search criteria (optional)
  - before, since: Date filters (optional)
  - chunkSize: Emails to delete per batch (default: 50)
  - dryRun: Preview what would be deleted without deleting (default: false)
  

  少なくとも1つの具体的な条件（from、to、subject、before、since）が 必要です。条件のない呼び出しは拒否されるため、フォルダー全体に一致して 削除されることはありません。SEARCH が正常に機能しないサーバーでは（ 「トラブルシューティング → 検索結果が返されない」を参照）、このツール、 imap_delete_spam、imap_delete_by_domain はクライアント側で一致する メールを削除する代わりにエラーを返します。

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

  Parameters:
  - accountId: Account ID to send from
  - from: Sender identity (optional). Must match the account email/login or an
      address configured in `allowedFrom`
  - to: Recipient email address(es) — an array, or a single comma-separated string
  - 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; provide exactly one of `content` or `path`
    - path: Readable local file path to attach; provide exactly one of `path` or `content`
    - contentType: MIME type (optional; detected from the filename extension when omitted)
    - contentDisposition: "attachment" (default) or "inline" — use "inline" for images shown in the HTML body via cid:
    - cid: Content-ID for inline attachments; must match the `cid:` value used in an `<img src="cid:...">` tag in `html`
  - dryRun: Validate attachments and compose MIME without sending or saving to Sent (optional, default: false)
  

  SMTP への接続前に添付ファイルを検証します。無効な base64、読み取れない パス、ファイル名の欠落、あいまいなソース、cid のないインライン添付 ファイルは、すぐにエラーになります。送信が成功した場合とドライランの場合、 attachmentCount と安全な attachmentDiagnostics（ファイル名、MIME タイプ、 サイズ、ソース、コンテンツの配置、cid）が返されます。診断情報にバイト列、 生の MIME、ローカルファイルパスは含まれません。

  大きなファイルの場合は、先に imap_upload_file でアップロードし、返された ローカルの path を指定します。インライン画像の場合は、 contentDisposition: "inline" と対応する cid を設定します。

  送信後、アカウントの Sent フォルダーにコピーが保存されます（アカウントで saveToSent が無効になっている場合を除く）。フォルダーは、アカウントの sentFolder による上書き → サーバーの \Sent SPECIAL-USE フラグ → 既知のローカライズされた名前の一覧（"Sent"、"Gesendet"、"Éléments envoyés"、…） の順に解決されます。応答には結果が報告されます。savedToSent（ブール値）、 sentFolder（使用されたフォルダー）、および保存に失敗した場合は、その理由を 説明する sentSaveError が含まれ、エラーが黙って無視されることはありません。 同様の動作は imap_reply_to_email と imap_forward_email にも適用されます。

  アカウントに defaultBcc が設定されている場合、送信、返信、転送、下書きの すべてで、指定されたアドレスが常に BCC に追加されます（呼び出しごとの bcc と統合され、大文字と小文字を区別せずに重複が削除されます）。メール クライアントに表示されるよう、下書きおよび Sent フォルダー内のコピーに 保存される MIME には Bcc ヘッダーが保持されます。

• imap_save_draft：メールを下書きとして保存します（送信はしません）。imap_send_email と同じフィールドに加えて、inReplyTo、references、および Drafts フォルダーを上書きするオプションの folder を指定できます。

• 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)
  - bcc: BCC recipients (optional; merged with account defaultBcc)
  - attachments: Array of attachments (optional, same shape as imap_send_email, including contentDisposition/cid for inline images)
  

• 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)
  - bcc: BCC recipients (optional; merged with account defaultBcc)
  - includeAttachments: Include original attachments (default: true)
  

フォルダー操作

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

  Parameters:
  - accountId: Account ID
  

  各フォルダーには attributes（生の IMAP LIST フラグ）が含まれます。また、 サーバーが通知する場合は specialUse も含まれます。これは、フォルダーを ローカライズされた表示名とは独立して識別する RFC 6154 の役割 （\Sent、\Drafts、\Trash、\Junk、\Archive）です（例："Gesendet" は specialUse: "\Sent" を持ちます）。

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

  Parameters:
  - accountId: Account ID
  - folder: Folder name
  
  Returns:
  - messages: { total, new, unseen } — from IMAP STATUS
  - uidvalidity, uidnext
  - flags, permanentFlags: string arrays
  - customKeywords: the mailbox's non-system keywords, usable as the
      `keywords` / `unKeywords` input of imap_search_emails
  

• imap_create_folder：新しい IMAP フォルダー／メールボックスを作成します。ほとんどのサーバーでは、不足している親フォルダーも作成されます。フォルダーがすでに存在する場合も成功を返します。

  Parameters:
  - accountId: Account ID
  - folder: Full folder path to create (e.g. "Archives/2026/2026-05" or "INBOX.Archive")
  

• imap_get_unread_count：未読メールの件数を取得します

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

セキュリティ

• 認証情報は AES-256-CBC 暗号化を使用して暗号化されます
• 暗号化キーは ~/.imap-mcp/.key に別途保存されます
• アカウント設定は ~/.imap-mcp/accounts.json に保存されます
• ストアディレクトリ、.key、accounts.json は所有者のみがアクセスできる権限（0700／0600）で書き込まれるため、ほかのローカルユーザーがキーや認証情報を読み取ることはできません
• ウェブ設定ウィザードの HTTP API は、保存されたパスワードをブラウザーに返しません
• ダウンロードした添付ファイルはダウンロードディレクトリ内に限定されます。送信者が指定したファイル名によって、ディレクトリ外に書き込まれることはありません
• 暗号化キーやアカウント設定をコミットしたり共有したりしないでください

開発

開発モードでの実行

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
│   └── account-manager.ts # Account configuration
├── 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. メールを送信する： 「[email protected] に件名『Project Update』でメールを送信して」

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

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

7. メールを移動する： 「INBOX にある請求書のメールを Taxes フォルダーに移動して」

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

トラブルシューティング

接続の問題

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

宛先が ["[email protected]","[email protected]"] として届く場合

to、cc、bcc、references、uid は、単一の値または 配列を受け付けます。JSON Schema ではこれは anyOf ですが、一部の MCP クライアントは モデルにスキーマを表示する前に anyOf を取り除くため、フィールドが型なし、または 文字列型に見え、クライアントがモデルの配列を文字列としてシリアライズします。 以前のサーバーはこの文字列をそのまま nodemailer に渡していたため、文字どおりの [ と ] が最初と最後のアドレスに含まれ、受信側のメールサーバーによって すべての宛先が拒否されていました（issue #127）。

現在、サーバーは文字列化された配列を検出し、ツール入力の検証時と メッセージの作成直前の両方で元に戻し、フィールド名を示す警告を stderr に 記録します。こちらで変更する必要はありません。クライアントの動作を完全に回避するには、 宛先をカンマ区切りの文字列として渡してください：「Alice [email protected], Bob [email protected]」。

フォルダーにメールがあるのに検索結果が返らない場合（Strato）

2026年半ば以降、Strato の IMAP サーバー（imap.strato.com）はすべての SEARCH コマンドに空の結果を返しますが、FETCH は引き続き動作します（issue #138）。サーバーはこの状態を 検出します。空でないフォルダーに対する SEARCH の結果が空で、SEARCH ALL も空の場合、 エンベロープを取得して条件を独自に適用します。imap_search_emails、imap_find_thread_messages、未読件数、および スパム分析は引き続き動作します。imap_get_latest_emails はもともと SEARCH を必要としません。

フォールバックの制限：

• 処理が遅くなります。検索のたびにフォルダー内のすべてのエンベロープがダウンロードされます。
• body 検索では、残りの候補を1件ずつダウンロードして解析するため、候補が2000件を超えると 拒否されます。since／from／subject を指定して絞り込んでください。
• 削除ツール（imap_bulk_delete_by_search、imap_delete_spam、 imap_delete_by_domain）ではこのフォールバックを使用せず、代わりにエラーを返します。対象の メッセージを imap_search_emails で検索し、その UID を imap_bulk_delete で削除してください。

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
  • アプリ専用パスワードが必要です

ライセンス

MIT

コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信してください。