Imap Mini MCP

🚀 IMAP Mini MCP

IMAPメールを読み取り、下書き返信を作成するための軽量MCP（Model Context Protocol）サーバーです。任意の標準IMAPサーバー（Gmail、Outlook、Fastmailなど）やProtonMail Bridgeのようなローカルブリッジと連携します。

エージェントは、メールの読み取り、検索、移動、スター付け、整理、および下書き作成ができますが、メールの送信や削除はできません。

最近追加された機能については、CHANGELOG.mdを参照してください。

🚀 クイックスタート

✨ 主な機能

• AIで作成され、人間によって検証された信頼性の高いサーバーです。
• 任意の標準IMAPサーバーやローカルブリッジと連携可能です。
• エージェントがメールの読み取り、検索、移動、スター付け、整理、下書き作成ができます。

📦 インストール

エージェントの設定

MCPクライアントの設定ファイル（例：claude_desktop_config.json）に以下を追加します。

{
  "mcpServers": {
    "imap-mini-mcp": {
      "command": "node",
      "args": ["/path/to/imap-mini-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "imap.example.com",
        "IMAP_USER": "you@example.com",
        "IMAP_PASS": "your-password"
      }
    }
  }
}

argsのパスは、ビルドされたdist/index.jsを指す必要があります。必要に応じて、envブロックに任意の変数を追加してください。

環境変数

ほとんどのプロバイダー（Gmail、Outlook、Fastmail）では、デフォルト設定で動作します。ホスト、ユーザー、パスワードを設定するだけです。

ProtonMail Bridgeの場合は、以下の5つの設定がすべて必要です（ブリッジはTLSなしでlocalhostで待機し、自己署名証明書を使用し、STARTTLSをサポートしていません）。

IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_SECURE=false
IMAP_STARTTLS=false
IMAP_TLS_REJECT_UNAUTHORIZED=false

または、MCPクライアントの設定として：

{
  "mcpServers": {
    "imap-mini-mcp": {
      "command": "node",
      "args": ["/path/to/imap-mini-mcp/dist/index.js"],
      "env": {
        "IMAP_HOST": "127.0.0.1",
        "IMAP_PORT": "1143",
        "IMAP_SECURE": "false",
        "IMAP_STARTTLS": "false",
        "IMAP_TLS_REJECT_UNAUTHORIZED": "false",
        "IMAP_USER": "you@proton.me",
        "IMAP_PASS": "your-bridge-password"
      }
    }
  }
}

💻 使用例

基本的な使用法

各メールは、複合id（YYYY-MM-DDTHH:mm:ss.<Message-ID>）によって識別され、これはグローバルに一意であり、フォルダの移動に関係なく安定しています。find_emailsが返すidを使用して、コンテンツを取得、添付ファイルをダウンロード、メールを移動、または返信下書きを作成します。アクションツールは、高速な検索のためにオプションのmailboxヒントを受け付けます。省略した場合、すべてのフォルダが検索されます。

find_emails

メールを検索およびフィルタリングします。すべてのパラメーターはオプションです。パラメーターを指定せずに呼び出すと、受信トレイからすべてのメールが最新順に返されます。

使用例：

その他のツール

📚 ドキュメント

トラブルシューティング

"IMAP connection closed unexpectedly" または "Server disconnected"

これはほとんどの場合、TLS/STARTTLSの不一致によりサーバーが接続を拒否したことを意味します。MCPクライアントの設定で、以下の環境変数が正しく設定されていることを確認してください。

ローカルのIMAPブリッジ（例：ProtonMail Bridge）では、通常、IMAP_SECURE=false、IMAP_STARTTLS=false、およびIMAP_TLS_REJECT_UNAUTHORIZED=falseが必要です。上記の環境変数セクションのProtonMail Bridgeの設定例を参照してください。

"IMAP authentication failed"

IMAP_USERとIMAP_PASSが正しいことを確認してください。一部のプロバイダー（例：Gmail）では、アカウントパスワードではなくアプリ固有のパスワードが必要です。

"Cannot reach IMAP server — connection refused"

IMAPサーバーが実行されていないか、設定されたホストとポートで待機していません。ローカルブリッジの場合は、ブリッジアプリケーションが実行されていることを確認してください。

開発

ビルドと実行

npm install
npm run build

.envを使用したローカル開発

MCPクライアントの外部でサーバーを直接実行する場合は、.env.exampleを.envにコピーして資格情報を入力し、次に：

npm start

MCPクライアントを介して使用する場合、資格情報はクライアント設定のenvブロックを介して提供されます。

テスト

テストはvitestを使用し、IMAPレイヤーをモックします。実際のサーバー接続は必要ありません。

npm test             # 一度実行
npm run test:watch   # ウォッチモード
npm run lint         # 型チェックのみ

📄 ライセンス

MIT