EWS Meeting MCP

EWS Meeting MCP

オンプレミスのExchange EWSで、Outlookの受信トレイのメッセージを安全に読み取り、自分宛てのレポートのみを送信し、会議をスケジュールするためのMCP サーバーです。

EWS Meeting MCPは、コーディングアシスタントやデスクトップエージェントが、Outlookの受信トレイのメッセージや空き状況を安全かつ構造化された方法で読み取り、設定済みのメールボックスのみにレポートを送信し、会議室を見つけて会議候補の時間を提案し、明示的な人間の確認を経てからのみ会議を作成、更新、キャンセルできるようにします。

カレンダーへのアクセスが機密性の高いインフラとなる企業向けに構築されています。規制対象のチーム、社内ネットワーク、厳格なセキュリティ審査、レガシーなExchange環境、クラウドエージェントにMicrosoft 365の広範な権限を簡単に付与できない組織が対象です。認証情報はローカルに保持され、会議への書き込みはExchangeに反映する前にプレビューされ、自分宛てのみのレポート送信には冪等性による保護が適用され、すべての書き込みをローカルの監査証跡で追跡できます。

npx ews-meeting-mcp

このプロジェクトが生まれた理由

多くのチームはいまも、オンプレミスのExchange/EWSを通じてカレンダーインフラを運用しています。汎用エージェントはスケジュール調整について推論できますが、生のパスワードを渡したり、参加者のアドレスを推測したり、確認可能なチェックポイントなしにカレンダー招待を送信したりするべきではありません。

これは汎用的なOutlookラッパーでも、Microsoft Graphを優先するカレンダーコネクターでもありません。ローカルのEWSアクセス、会議室リソース、明示的な人間による承認、重複送信の防止、監査に適した会議ライフサイクルツールを必要とする、より厳格なエンタープライズ環境向けに設計されています。

このプロジェクトは、Exchangeのカレンダー操作を小規模なMCPサーフェスで提供し、次の機能を備えています。

• 会議室を考慮したスケジュール調整：参加者の空き時間が重なる時間帯を見つけ、Exchangeによる検出またはローカルポリシーに基づいて会議室を絞り込みます。
• 人間が介在する書き込み：作成、更新、キャンセルの操作には、プレビューと、それに一致するconfirmation_idが必要です。
• Outlookの予定の表示方法：show_as: "out_of_office"（EWS OOF）を指定して個人の予定を作成または更新できます。参加者と会議室が空の場合、招待は送信されません。この設定はメールの自動応答を構成するものではありません。
• ローカル優先の認証情報管理：モデルにパスワードを渡すことなく、.env、シェル環境、またはmacOS Keychainから読み取ります。
• 構造化された復旧機能：セットアップに失敗すると、機械可読なエラーコードと、ユーザー向けのセットアップコマンドを返します。
• 監査可能性：ライフサイクルのプレビュー、確認済みの操作、重複確認、処理中の状態、構造化されたエラーを、ローカルのJSONL監査ログに記録します。
• エージェント向けの手順：MCP サーバーはツールの説明と初期化ガイダンスを公開します。また、このリポジトリには、スキルに対応するエージェント向けの補助スキルが含まれています。

エージェントにできること

機能	ツール	安全性
セットアップと認証情報を確認する	ews_setup_check, ews_keychain_status	EWS パスワードは返しません
会議の署名を設定する	ews_signature_setup_guide	コピー可能な HTML サンプルとローカル環境の設定方法を返します
Outlook の受信トレイを読む	ews_search_emails, ews_read_email	読み取り専用です。メッセージを既読にしたり、メールボックスの状態を変更したりしません
自分宛てに週次レポートを送信する	ews_send_email_to_self	EWS_EMAIL にのみ送信します。宛先は入力項目ではありません。安定した冪等性キーと、実際の EWS CreateItem + SendItem が必要です
カレンダーの空き状況を読む	ews_list_calendar, ews_get_free_busy, ews_find_calendar_events	読み取り専用です
人や会議室を特定する	ews_resolve_attendees, ews_list_rooms	利用可能な場合は Exchange ディレクトリを使用します
候補日時を提案する	ews_suggest_slots	ローカルの勤務日、回避時間帯、会議室の収容人数を考慮します
会議を作成する	ews_create_meeting_preview, ews_create_meeting_confirmed	毎週の繰り返しを任意で設定できます。プレビュー、明示的な承認、一致する確認 ID が必要です
会議を更新する	ews_update_meeting_preview, ews_update_meeting_confirmed	正確な EWS 項目メタデータと一致する確認 ID が必要です
会議をキャンセルする	ews_cancel_meeting_preview, ews_cancel_meeting_confirmed	正確な EWS 項目メタデータと一致する確認 ID が必要です
検証と監査を行う	ews_verify_meeting, ews_get_audit_log	認証情報を公開せずにサーバー側の状態を確認します

ドキュメント

• 使用ガイド：ローカルセットアップ、Keychain、スケジュールポリシー、スモークテスト、CLI の例、MCP 設定、npm ラッパーの詳細。
• エージェントガイド：ツールの契約、セットアップ確認、出席者の特定、会議室の選択、プレビューと確認のフロー、監査ログ、検証ルール。
• 公開：npm パッケージと GitHub Actions のリリースチェックリスト。

クイックスタート

1. EWS を設定する

作業ディレクトリに .env ファイルを作成するか、同等の環境変数を指定します。

EWS_ENDPOINT=https://mail.company.com/EWS/Exchange.asmx
[email protected]
EWS_USERNAME='DOMAIN\your_user'
EWS_AUTH_TYPE=NTLM
EWS_TIMEZONE=Asia/Taipei

IT 部門が Basic 認証の有効化を確認し、エンドポイントが HTTPS で保護されている場合に限り、EWS_AUTH_TYPE=BASIC を使用してください。

2. パスワードを保存する

ローカル開発では、汎用の ACCOUNT_PASSWORD オーバーライドを使用できますが、MCP の設定には記載しないでください。

ACCOUNT_PASSWORD='your-password'

macOS では、パスワードを .env または MCP クライアントの設定に保存するより、Keychain のほうが安全です。

read -rsp "Account password: " ACCOUNT_PASSWORD
echo
security add-generic-password -U -s ews-meeting-mcp-account-password -a 'DOMAIN\your_user' -w "$ACCOUNT_PASSWORD"
unset ACCOUNT_PASSWORD

このアカウントのパスワードを必要とするローカルツールでは、同じ Keychain サービスとアカウントの組み合わせを使用してください。

ACCOUNT_PASSWORD_KEYCHAIN_SERVICE=ews-meeting-mcp-account-password
ACCOUNT_PASSWORD_KEYCHAIN_ACCOUNT='DOMAIN\your_user'

ACCOUNT_PASSWORD_KEYCHAIN_ACCOUNT を省略すると、EWS_USERNAME が使用されます。ACCOUNT_PASSWORD は汎用のローカルオーバーライドに限られます。Keychain の使用を推奨します。

3. MCP サーバーを追加する

npm でインストールした MCP クライアントの場合：

{
  "mcpServers": {
    "ews-meeting-mcp": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "EWS_ENDPOINT": "https://mail.company.com/EWS/Exchange.asmx",
        "EWS_EMAIL": "[email protected]",
        "EWS_USERNAME": "DOMAIN\\your_user",
        "ACCOUNT_PASSWORD_KEYCHAIN_SERVICE": "ews-meeting-mcp-account-password",
        "ACCOUNT_PASSWORD_KEYCHAIN_ACCOUNT": "DOMAIN\\your_user",
        "EWS_AUTH_TYPE": "NTLM",
        "EWS_TIMEZONE": "Asia/Taipei"
      }
    }
  }
}

ローカルのチェックアウトの場合：

{
  "mcpServers": {
    "ews-meeting-mcp": {
      "command": "/path/to/ews-meeting-mcp/.venv/bin/python",
      "args": ["-m", "ews_meeting_mcp.mcp_server"],
      "cwd": "/path/to/ews-meeting-mcp",
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

任意：Outlook 風の署名を追加する

既定では、会議の招待状に設定済みの HTML 署名が追加されます。コピーして使えるスターターテンプレートを MCP ツールに依頼してください。

ews_signature_setup_guide

返された sample_html を MCP の作業ディレクトリに ews-meeting-signature.html として保存し、名前、メールアドレス、役職、ロゴの URL、免責事項を編集します。別のファイルを指定することもできます。

EWS_MEETING_SIGNATURE_HTML_PATH=/path/to/ews-meeting-signature.html
EWS_MEETING_SIGNATURE_ENABLED=true

受信者がアクセスできる HTTPS のロゴ URL を使用するか、<img> のソースを base64 のデータ URI に置き換えてください。署名の追加を一時的に停止するには、EWS_MEETING_SIGNATURE_ENABLED=false を設定します。

4. セットアップを確認する

npx ews-meeting-mcp --cli env
npx ews-meeting-mcp --cli probe

最初のコマンドは、パスワードを出力せずに設定済みのエンドポイントとアカウントを表示します。2 番目のコマンドは、アカウントが EWS に接続できることを検証します。

エージェントのワークフロー

Outlook のメールを受信したら、まず設定済みの受信トレイを検索してから、選択したメッセージを読み取ります。

user asks about company email
-> ews_setup_check
-> ews_search_emails with the narrowest known filters
-> user selects or identifies one message
-> ews_read_email with the exact id and optional changekey

これらのメールボックスツールは読み取り専用です。メッセージを既読にしたり、メールを送信したり、メッセージを移動したり、ラベルを変更したりすることはありません。

木曜日の Jira 週次レポート自動化では、Jira の検索結果からレポートを作成し、この EWS MCP の専用の自分宛てメールツールを呼び出します。

weekly report is ready
-> ews_setup_check
-> ews_send_email_to_self with subject, body, and a stable idempotency_key
-> stop after sent=true; do not use Gmail, to: me, or another mail provider

ews_send_email_to_self は、宛先、to、cc、bcc の引数を受け取りません。唯一の宛先は EWS_EMAIL から取得し、Exchange EWS 経由で送信します。また、デフォルトで設定済みの HTML 署名を追加します。メール本文や宛先アドレスは監査ログに記録されません。自動化を再試行する場合は、同じ冪等性キーを再利用してください。完了済みまたは処理中のキーでは、Exchange は再度呼び出されません。

スケジュール設定は、次の形式に従ってください。

user request
-> ews_setup_check
-> ews_signature_setup_guide, if the user needs help creating the optional HTML signature
-> ews_resolve_attendees, if names or aliases are provided
-> ews_list_rooms, if a room may be needed
-> ews_suggest_slots
-> user chooses a slot and room
-> ews_create_meeting_preview
-> show exact invite details, recurrence if present, and confirmation_id
-> user explicitly confirms
-> ews_create_meeting_confirmed with confirm=true and the same confirmation_id
-> ews_verify_meeting, when item id and changekey are available

定期的な会議を作成するには、プレビューと確定後の作成呼び出しの両方に、構造化された recurrence オブジェクトを渡します。たとえば、「毎週月曜日と水曜日」は週次の繰り返しを使用します。

{
  "type": "weekly",
  "interval": 1,
  "weekdays": ["MO", "WE"],
  "range": {
    "type": "numbered",
    "count": 10
  }
}

「7/26 まで毎営業日」は、祝日や振替休日を考慮せず、月曜日から金曜日までを意味します。

{
  "type": "weekly",
  "interval": 1,
  "weekdays": ["MO", "TU", "WE", "TH", "FR"],
  "range": {
    "type": "end_date",
    "end_date": "2026-07-26"
  }
}

「毎週月曜日と水曜日」のように、終了日、発生回数、または終了日なしの明示的な選択がないまま、曜日だけが指定された場合は、プレビューの前にいずれかを確認してください。

既存の会議を変更する場合は、正確なカレンダーメタデータを使用してください。

user asks to update or cancel a meeting
-> ews_find_calendar_events with the narrowest known time window
-> user chooses one exact event, if more than one candidate exists
-> ews_update_meeting_preview or ews_cancel_meeting_preview
-> show current/proposed details, warnings, and confirmation_id
-> user explicitly confirms
-> matching confirmed tool with confirm=true and the same confirmation_id

候補が複数ある場合、エージェントは件名のテキストからイベントを推測してはいけません。

安全性モデル

EWS Meeting MCP は、シンプルなルールに基づいて設計されています。読み取りは自動化できますが、書き込みにはすべて厳格な安全策が必要です。受信トレイの読み取りは、明示的に読み取り専用の検索ツールと読み取りツールに限定されます。会議への書き込みにはプレビューと明示的な確認が必要です。一方、自分宛てのレポート送信には、設定済みの自分宛てアドレスの強制と冪等性による保護が必要です。

• 認証エラーは即座に処理を停止します。EWS クライアントは FailFast を使用し、無効な認証情報またはアカウントロックの応答を一度でも受けると、そのプロセス内の以降の EWS 呼び出しを MCP がすべてブロックします。共有 Keychain 項目を修正し、再試行する前に MCP を再起動してください。
• 作成、更新、キャンセルを確定するツールは、confirm=true が渡されない限り実行されません。
• 確定用ツールには、対応するプレビューから返された正確な confirmation_id が必要です。
• 更新とキャンセルを確定するツールには、ews_find_calendar_events または以前に検証済みの結果から取得した、正確な EWS id と changekey も必要です。
• 重複した確定リクエストには、EWS を再度呼び出す代わりに、以前の結果のメタデータを含む error_code: "duplicate_confirmation" が返されます。
• 確認処理中のリクエストには error_code: "confirmation_in_progress" が返されます。むやみに再試行しないでください。
• プレビューツールは、Exchange の通知を保存、移動、削除、送信しません。
• メールを書き込む機能は ews_send_email_to_self のみです。この機能は自分宛てに限定されており、EWS_EMAIL の設定が必要です。また、EWS CreateItem で下書きを保存した後、SendItem で送信します。任意の宛先は指定できません。
• 自分宛ての送信には、安定した非秘密情報の idempotency_key が必要です。キーが重複している、または処理中の場合は、別の EWS 送信を行う前に拒否されます。配信状況が不明な場合は、再試行する前に送信済みアイテムを確認してください。
• 自分宛て送信の監査エントリに含まれるのは、アクション／ステータスと、機密性のない配信／冪等性メタデータのみです。設定済みのメールアドレス、件名、本文、パスワード、トークンは含まれません。
• ローカルの確認台帳と監査ログには、操作メタデータが保存されます。EWS のパスワードは保存されません。

ews_setup_check が ready: false を返した場合、エージェントは返された user_message または setup_command をそのまま表示して、処理を中止してください。回避策として出席者のメールアドレスを尋ねたり、スケジュール設定を続けたりしてはいけません。

スケジューリングポリシー

デフォルトでは、スケジューリングツールは現在の作業ディレクトリにある ews-meeting-policy.json を検索します。別のファイルを指定するには、EWS_MEETING_POLICY_FILE を設定します。

ポリシーファイルが存在しない場合は、組み込みのデフォルト設定が使用されます。

• 勤務時間：10:00～18:00
• 避ける時間帯：12:00-14:00
• フォールバック用会議室：2-11、2-13、2-14、3-1、3-2、3-4

利用可能な場合、実際の会議室選択では Exchange の会議室リスト検出を使用し、その後、設定済みの会議室にフォールバックします。

ポリシーの例：

{
  "workday_start": "10:00",
  "workday_end": "18:00",
  "avoid": ["12:00-14:00"],
  "rooms": [
    {
      "alias": "3-1",
      "name": "3-1 Meeting Room(12P)",
      "email": "[email protected]",
      "capacity": 12
    }
  ]
}

ポリシーで指定した会議室は、alias に基づいてデフォルトのフォールバック用会議室と統合されます。一致するエイリアスがある場合はデフォルトの会議室を上書きし、新しいエイリアスは追加されます。

CLI の使い方

npm ラッパーは、デフォルトで MCP サーバーを起動します。

npx ews-meeting-mcp

同じパッケージから Python CLI を実行するには、--cli を渡します。

npx ews-meeting-mcp --cli env
npx ews-meeting-mcp --cli calendar --days 7

30 分の会議枠を提案します。

npx ews-meeting-mcp --cli suggest \
  --attendee [email protected] \
  --attendee [email protected] \
  --start 2026-06-15T09:00:00+08:00 \
  --end 2026-06-19T18:00:00+08:00 \
  --duration-minutes 30 \
  --limit 5

会議招待を送信せずにプレビューします。

npx ews-meeting-mcp --cli create-meeting \
  --attendee [email protected] \
  --attendee [email protected] \
  --start 2026-06-15T11:00:00+08:00 \
  --end 2026-06-15T11:30:00+08:00 \
  --subject "Project sync" \
  --body "Discuss next steps" \
  --location "Webex"

実際に会議を作成し、招待を送信します。

npx ews-meeting-mcp --cli create-meeting \
  --attendee [email protected] \
  --attendee [email protected] \
  --start 2026-06-15T11:00:00+08:00 \
  --end 2026-06-15T11:30:00+08:00 \
  --subject "Project sync" \
  --body "Discuss next steps" \
  --location "Webex" \
  --confirm

--confirm フラグは意図的に必須となっています。このフラグを指定しない場合、コマンドはドライランのプレビューを表示し、EWS を呼び出してイベントを作成することはありません。

カレンダーの表示状態／不在通知

会議の作成・更新を行うプレビュー／確定済み MCP ツールでは、オプションの show_as を指定できます。

show_as	EWS LegacyFreeBusyStatus
free	Free
tentative	Tentative
busy	Busy
out_of_office	OOF

作成時に省略すると、既存のデフォルトである「予定あり」が維持されます。更新時に省略すると、保存済みの状態が保持されます。個人の予定では attendees: [] と rooms: [] を使用し、SendToNone で保存されます。出席者またはリソースがある既存の会議では、従来の招待動作が維持されます。週次の繰り返し予定の作成でも show_as を指定できます。繰り返し設定の編集機能に変更はありません。

たとえば、次のように ews_create_meeting_preview を呼び出します。

{
  "subject": "不在辦公室",
  "attendees": [],
  "rooms": [],
  "start": "2026-09-21T09:00:00+08:00",
  "end": "2026-09-21T18:00:00+08:00",
  "show_as": "out_of_office",
  "include_signature": false
}

開始時刻と終了時刻、タイムゾーンのオフセット、show_as、招待の動作をユーザーに提示します。明示的な確認を受けた後、同じ引数に confirm: true と返された confirmation_id を追加して、ews_create_meeting_confirmed を呼び出します。プレビュー後に状態を変更すると、その確認は無効になります。クエリ／検証ツールは保存済みの show_as と生の legacy_free_busy_status を返します。保存後にサーバーの状態を読み取るには、ews_verify_meeting を使用してください。

更新例と手動検証チェックリストについては、カレンダー状態の使い方、MCP による更新手順、実際の検証を参照してください。この機能が変更するのはカレンダーの状態のみで、メールの自動応答には影響しません。

ローカル開発

詳細なセットアップ、スモークテスト、CLI の例、MCP クライアントの設定については、使用ガイドを参照してください。

開発時の基本的な流れは次のとおりです。

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
npm test

チェックアウトしたリポジトリから MCP サーバーを実行します。

env PYTHONPATH=src python -m ews_meeting_mcp.mcp_server

関連スキル

このリポジトリには、スキルに対応したエージェント向けの関連スキルが含まれています。

skills/ews-meeting-mcp/SKILL.md

同じワークフローを通常の Markdown で確認するには、エージェントガイドを参照してください。

トラブルシューティング

運用上のトラブルシューティングについては、使用ガイドを参照してください。エージェントの動作、セットアップ確認の処理、ライフサイクルの安全性については、エージェントガイドを参照してください。

リリース

公開手順を参照してください。

ライセンス

MIT