Email Processing MCP Server

メール処理 MCP サーバー

Microsoft Outlook のメールを処理し、Ollama を使用してベクトル埋め込みを生成し、セマンティック検索機能を提供するクロスプラットフォームの MCP サーバーです。Windows、macOS、および Microsoft Graph API を介したあらゆるプラットフォームで動作します。

このサーバーは Model Context Protocol（MCP）2025-06-18 仕様に準拠し、公式 MCP SDK を使用しています。

機能

主な機能

• 日付範囲によるフィルタリングを行い、Outlook からメールを処理
• 適切な接続管理を行い、メールを SQLite データベースに保存
• Ollama（nomic-embed-text）を使用してベクトル埋め込みを生成
• MongoDB ベクトルストアを介してメール内容をセマンティック検索
• 複数のメールボックスおよびアカウントをサポート
• 受信トレイ、送信済みアイテム、およびオプションで削除済みアイテムのフォルダーをサポート

クロスプラットフォーム対応

• Windows：pywin32 を介したネイティブの Outlook COM 自動化
• macOS：Outlook for Mac との AppleScript 統合
• あらゆるプラットフォーム：クラウドベースのアクセスに Microsoft Graph API を使用（Windows、macOS、Linux、コンテナー）

MCP 2025-06-18 への準拠

• 構造化ツール結果：ツールは適切に型付けされ、検証された Pydantic モデルを返します
• HTTP トランスポート：STDIO と HTTP（Streamable HTTP）の両方のトランスポートをサポート
• プロトコルネゴシエーション：ハンドシェイク時にプロトコルバージョンを宣言
• 強化されたメタデータ：UI との統合を向上させるツールのタイトルと説明

利用可能なツール（12 個以上）

カテゴリー	ツール
メール処理	process_emails
検索と分析	search_emails, analyze_email_sentiment, find_actionable_items
データのエクスポート	export_email_data（CSV、JSON、HTML、Excel）
フォルダー管理	list_outlook_folders, get_folder_statistics, organize_emails_by_rules
連絡先管理	extract_contacts
統計	get_email_statistics, check_data_consistency

前提条件

必須（すべてのプラットフォーム）

• Python 3.10 以降
• nomic-embed-text モデルを使用してローカルで実行中の Ollama
• MongoDB サーバー（埋め込みの保存用）

プラットフォーム固有の要件

プラットフォーム	要件
Windows	Microsoft Outlook がインストール済みであること + pywin32
macOS	Microsoft Outlook for Mac がインストール済みであること
Graph API	Mail.Read 権限を持つ Azure AD アプリ登録

インストール

1. uv をインストールする（まだインストールされていない場合）

pip install uv

2. 仮想環境を作成して有効化する

uv venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

3. 依存関係をインストールする

コアのインストール（必須）：

uv pip install -e .

プラットフォーム固有の追加要件：

# Windows (adds pywin32 for COM automation)
uv pip install -e ".[windows]"

# Graph API support (cross-platform cloud access)
uv pip install -e ".[graph]"

# All optional dependencies
uv pip install -e ".[all]"

4. Ollama 埋め込みモデルをインストールする

ollama pull nomic-embed-text

5. （Graph API のみ）Azure AD アプリケーションを登録する

Microsoft Graph API を使用する場合は、Azure AD でアプリケーションを登録する必要があります。

1. Azure Portal に移動 → Azure Active Directory → アプリの登録
2. 「新規登録」をクリック
3. アプリに名前を付け、「この組織のディレクトリ内のアカウントのみ」を選択
4. 作成後、アプリケーション（クライアント）ID と ディレクトリ（テナント）ID を控える
5. 「証明書とシークレット」→「新しいクライアント シークレット」に移動し、シークレット値を控える
6. 「API のアクセス許可」→「アクセス許可の追加」→「Microsoft Graph」→「アプリケーションのアクセス許可」に移動
7. Mail.Read、User.Read.All（複数アカウントの検出用）を追加
8. 「管理者の同意を付与」をクリック

設定

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

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

環境変数

変数	説明	必須
MONGODB_URI	MongoDB 接続文字列	はい
SQLITE_DB_PATH	SQLite データベースファイルのパス	はい
EMBEDDING_BASE_URL	Ollama サーバーの URL（デフォルト：http://localhost:11434）	いいえ
EMBEDDING_MODEL	埋め込みモデル名（デフォルト：nomic-embed-text）	いいえ
COLLECTION_NAME	MongoDB コレクション名	はい
PROCESS_DELETED_ITEMS	削除済みアイテムフォルダーを処理するかどうか（デフォルト："false"）	いいえ
OUTLOOK_PROVIDER	プロバイダー：auto、windows、mac、graph（デフォルト："auto"）	いいえ
LOCAL_TIMEZONE	日付に使用するタイムゾーン（デフォルト："UTC"、例："America/Chicago"）	いいえ

Graph API 変数（OUTLOOK_PROVIDER=graph の場合に必須）：

変数	説明
GRAPH_CLIENT_ID	Azure AD アプリケーション（クライアント）ID
GRAPH_CLIENT_SECRET	Azure AD クライアントシークレット
GRAPH_TENANT_ID	Azure AD テナント ID
GRAPH_USER_EMAILS	メールボックス：カンマ区切りのリスト、または自動検出する場合は "All"

---

Windows の設定（COM オートメーション）

pywin32 を使用して、ネイティブの Outlook COM オートメーションを利用します。

{
  "mcpServers": {
    "outlook-email": {
      "command": "C:/path/to/.venv/Scripts/python",
      "args": ["C:/path/to/src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "windows",
        "LOCAL_TIMEZONE": "America/Chicago"
      }
    }
  }
}

macOS の設定（AppleScript）

AppleScript を使用して、Outlook for Mac と通信します。

{
  "mcpServers": {
    "outlook-email": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "SQLITE_DB_PATH": "/path/to/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "mac",
        "LOCAL_TIMEZONE": "America/Los_Angeles"
      }
    }
  }
}

Graph API の設定（クロスプラットフォーム）

Azure AD 認証情報があれば、どのプラットフォームでも動作します。単一または複数のメールボックスに対応しています。

単一または特定のメールボックス：

{
  "mcpServers": {
    "outlook-email": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP",
        "SQLITE_DB_PATH": "/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "graph",
        "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
        "GRAPH_CLIENT_SECRET": "your-client-secret",
        "GRAPH_TENANT_ID": "your-tenant-id",
        "GRAPH_USER_EMAILS": "[email protected],[email protected]"
      }
    }
  }
}

テナント内のすべてのメールボックス（自動検出）：

{
  "mcpServers": {
    "outlook-email": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP",
        "SQLITE_DB_PATH": "/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "graph",
        "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
        "GRAPH_CLIENT_SECRET": "your-client-secret",
        "GRAPH_TENANT_ID": "your-tenant-id",
        "GRAPH_USER_EMAILS": "All"
      }
    }
  }
}

プロバイダーの自動検出

OUTLOOK_PROVIDER が auto（デフォルト）に設定されている場合、サーバーは最適なプロバイダーを自動的に選択します。

プラットフォーム	自動選択されるプロバイダー
Windows	windows（COM オートメーション）
macOS	mac（AppleScript）
Linux/その他	graph（Azure AD の設定が必要）

HTTP トランスポート（2025-06-18 準拠）

HTTP トランスポートを使用するには、--http フラグを指定してサーバーを実行します。

python src/mcp_server.py --http

これにより、次の内容を含む 2025-06-18 プロトコルに完全準拠したサーバーが http://localhost:8000/mcp で起動します。

• プロトコルバージョンのネゴシエーション
• 構造化出力スキーマ
• HTTP ヘッダーの検証
• 適切なエラー処理

HTTP トランスポートは、ステートフルモードとステートレスモードの両方に対応しています。

---

利用可能なツール

1. process_emails

指定した期間のメールを処理し、構造化された結果を返します。

入力：

{
  "start_date": "2024-01-01",    # ISO format date (YYYY-MM-DD)
  "end_date": "2024-02-15",      # ISO format date (YYYY-MM-DD)
  "mailboxes": ["All"]           # List of mailbox names or ["All"] for all mailboxes
}

出力（構造化形式）：

{
  "success": true,
  "processed_count": 150,
  "retrieved_count": 200,
  "stored_count": 180,
  "failed_count": 20,
  "message": "Successfully processed 150 emails (retrieved: 200, stored: 180, failed: 20)",
  "error": null
}

このツールは次の処理を行います。

1. 指定された Outlook メールボックスに接続します
2. 受信トレイと送信済みアイテムのフォルダーからメールを取得します（有効な場合は削除済みアイテムも含みます）
3. SQLite データベースにメールを保存します
4. Ollama を使用して埋め込みを生成します
5. 意味検索に使用する埋め込みを MongoDB に保存します
6. 詳細な統計情報を含む構造化された結果を返します

Claude での使用例

"Process emails from February 1st to February 17th from all mailboxes"

アーキテクチャ

プロバイダー方式のコネクター設計

このサーバーは、クロスプラットフォームでメールにアクセスするために、プロバイダー方式の抽象化を使用します。

src/connectors/
├── base.py               # OutlookConnectorBase (abstract interface)
├── factory.py            # create_connector() with auto-detection
├── windows_connector.py  # Windows COM via pywin32
├── mac_connector.py      # macOS AppleScript via osascript
└── graph_connector.py    # Microsoft Graph API (cross-platform)

すべてのコネクターは同じインターフェースを実装しており、プラットフォームにかかわらず、標準化された EmailMetadata オブジェクトを返します。

デュアルデータベースアーキテクチャ

このサーバーは、ハイブリッドなストレージ方式を採用しています。

SQLite データベース：

• メールとメタデータのプライマリーストレージ
• 全文検索機能
• 処理状況の追跡
• 日付範囲とフォルダーによるフィルタリング
• 高速な構造化クエリ

MongoDB：

• ベクトル埋め込みの保存（768 次元）
• 意味的類似性検索
• 埋め込みと併せたメタデータの保存
• AI を活用した検索を実現

エラー処理

このサーバーは、次のような一般的な問題について詳細なエラーメッセージを表示します。

• 無効な日付形式
• Outlook との接続の問題
• MongoDB のエラー
• 再試行ロジックを備えた埋め込み生成の失敗
• SQLite のストレージエラー
• 自動再試行を伴う Ollama サーバーへの接続の問題

リソース管理

サーバーは、問題を防ぐために適切なリソース管理を実装しています。

• 「Cannot operate on a closed database」エラーを防ぐため、データベース接続（SQLite および MongoDB）はサーバーの稼働中、開いたまま維持されます
• 接続は、atexit ハンドラーを使用してサーバーのシャットダウン時にのみ閉じられます
• オブジェクトがガベージコレクションされる際に接続が確実に閉じられるよう、デストラクターとコンテキストマネージャーをフォールバックとして使用します
• 接続管理は、リソース使用量と運用上の信頼性のバランスを取るように設計されています
• 一時的な接続問題に対処するため、Ollama などの外部サービスには堅牢な再試行ロジックを使用します

MCP 2025-06-18 準拠

このサーバーは、MCP 2025-06-18 仕様に準拠するようアップグレードされています。

プロトコル機能

• プロトコルバージョン：ハンドシェイク中に protocolVersion: "2025-06-18" を宣言します
• 構造化出力：すべてのツールが、型付けされ検証済みの Pydantic モデルを返します
• HTTP トランスポート：適切なヘッダー検証を備えた Streamable HTTP をサポートします
• ツールメタデータ：タイトルとスキーマを含む、より詳細なツールの説明を提供します
• エラー処理：詳細情報を含む構造化エラーレスポンスを返します

トランスポートのサポート

• STDIO：従来の stdin/stdout 通信（デフォルト）
• HTTP：ヘッダー検証を備えた localhost:8000/mcp での Streamable HTTP
• プロトコルヘッダー：MCP-Protocol-Version および Origin ヘッダーを検証します
• 単一メッセージの JSON-RPC：2025-06-18 仕様に従い、バッチリクエストはサポートしません

構造化出力

process_emails ツールは、次の内容を含む構造化された ProcessEmailsResult を返します。

• success：処理が成功したかどうかを示すブール値
• processed_count：正常に処理されたメールの数
• retrieved_count：Outlook から取得したメールの合計数
• stored_count：SQLite に保存されたメールの数
• failed_count：処理に失敗したメールの数
• message：人間が読めるステータスメッセージ
• error：処理に失敗した場合のエラー詳細

セキュリティに関する注意事項

• サーバーは、指定されたメールボックスのメールのみを処理します
• すべてのデータはローカル（SQLite）および MongoDB に保存されます
• ローカルの Ollama サーバー（およびそのプロバイダーを使用する場合は Microsoft Graph）以外への外部 API 呼び出しはありません
• メール処理には、ユーザーによる明示的な承認が必要です
• MCP インターフェースを通じて機密性の高いメールデータが公開されることはありません
• セキュリティのため、HTTP トランスポートは localhost のみにバインドされます
• Graph API は、Azure AD で OAuth 2.0 クライアント資格情報フローを使用します
• Azure AD の資格情報は安全に保管してください（コード内ではなく、環境変数に設定してください）

デバッグ

問題が発生した場合は、次の項目を確認してください。

1. メールが正常に処理されたことを確認します（process_emails のレスポンスを確認してください）
2. 埋め込み生成のために Ollama サーバーが実行中であることを確認します
3. SQLite データベースにアクセスできることを確認します
4. MongoDB 接続が正常に機能していることを確認します
5. check_data_consistency ツールを使用して、SQLite/MongoDB の同期を確認します

プラットフォーム固有のデバッグ

Windows：

• Outlook が実行中で、アクセス可能であることを確認します
• pywin32 がインストールされていることを確認します：pip show pywin32
• COM オートメーションが機能することを確認します：python -c "import win32com.client; print('OK')"

macOS：

• Outlook for Mac がインストールされていることを確認します（「New Outlook」の Web アプリだけでは不十分です）
• AppleScript へのアクセスをテストします：osascript -e 'tell application "Microsoft Outlook" to get name'
• 「システム設定」→「プライバシーとセキュリティ」→「オートメーション」で、ターミナル／IDE に権限を付与します

Graph API：

• Azure AD アプリに適切な権限（Mail.Read、User.Read.All）が設定されていることを確認します
• 管理者の同意が付与されていることを確認します
• トークン取得をテストします：起動時に資格情報がログに記録されます
• GRAPH_USER_EMAILS が正しく設定されていることを確認します（「All」またはカンマ区切りのメールアドレス）

プラットフォームの制限事項

プラットフォーム	制限事項
Windows	Outlook デスクトップアプリの起動が必要です
macOS	「New Outlook」では AppleScript のサポートが限定的な場合があります。代替手段として Graph API を使用してください
Graph API	Azure AD の設定が必要です。日付範囲は最大 30 日に制限されます
すべて	リクエストごとの処理期間は最大 30 日です

今後の機能

• LLM を使用したメールの要約
• メールの自動分類
• カスタマイズ可能なメールレポート
• Outlook でのメール返信の下書き作成
• Outlook のルールの提案
• Neo4j と ChromaDB の連携によるデータベースの選択肢の拡充