Outlook MCP

🚀 Outlook MCP Server

このModel Context Protocol (MCP)サーバーは、Microsoft Graph APIを通じてClaudeにMicrosoft Outlookへのアクセスを提供します。複数アカウントのサポート、リモートデプロイ機能、そして包括的なメール、カレンダー、フォルダ管理機能を備えています。

🚀 クイックスタート

1. 依存関係のインストール

npm install

2. Azureアプリ登録の設定

1. AzureポータルでAzureアプリ登録を作成します。
2. リダイレクトURIを設定します。
   • http://localhost:3333/auth/callback
   • リモートの場合: https://your-domain.com/auth/callback
3. パーミッションを付与します: Mail.ReadWrite, Calendars.ReadWrite, offline_access

3. 環境設定

.env.exampleを.envにコピーし、以下のように設定します。

# Azureアプリ登録
MS_CLIENT_ID=your-azure-client-id
MS_CLIENT_SECRET=your-azure-client-secret
OUTLOOK_CLIENT_ID=your-azure-client-id
OUTLOOK_CLIENT_SECRET=your-azure-client-secret

# サーバー設定
USE_TEST_MODE=false
MCP_PORT=3001

4. Claude Desktopの設定

Claude Desktopの設定に以下を追加します。

{
  "mcpServers": {
    "outlook-mcp": {
      "command": "node",
      "args": ["/path/to/outlook-mcp/index.js"],
      "env": {
        "USE_TEST_MODE": "false"
      }
    }
  }
}

💻 使用例

基本的な使用法

ローカルモード（デフォルト）

npm start

Claude Desktopとの統合のためにstdio経由で実行されます。

リモートモード

npm run start-remote

ポート3001でHTTPサーバーを起動し、MCPエンドポイントは/mcpとなります。

テストモード

npm run test-mode

開発用のモックデータで実行されます。

✨ 主な機能

複数アカウントサポート

• 複数のOutlookアカウントを同時に管理できます。
• アカウントごとに個別の認証とトークンの保存が行われます。
• アカウント固有の操作とデータの分離が可能です。

メール管理

• メールの一覧表示、検索、読み取りができます。
• メールの送信と下書きの作成が可能です。
• メッセージに返信できます。
• フォルダの管理とメールの移動ができます。
• 添付ファイルの取り扱いが可能です。

カレンダー管理

• カレンダーイベントの一覧表示ができます。
• イベントの作成、更新、削除が可能です。
• 会議招待の承諾/拒否ができます。
• カレンダーのパーミッション管理ができます。

フォルダとルール管理

• メールフォルダの作成と管理ができます。
• メールルールとフィルターの設定が可能です。
• メールボックスの構造を整理できます。

📚 ドキュメント

MCPツール

認証

• authenticate - 新しいOutlookアカウントを追加します。
• check-auth-status - アカウントの認証状態を表示します。
• list-accounts - すべての設定済みアカウントを一覧表示します。
• remove-account - アカウントを削除します。

メールツール

• list-emails - フィルタリングオプション付きでメールを一覧表示します。
• read-email - 特定のメールの内容を読み取ります。
• send-email - 新しいメールを送信します。
• create-draft - メールの下書きを作成します。
• reply-to-email - 既存のメールに返信します。
• search-emails - 条件によるメールの検索を行います。
• mark-as-read - メールを既読/未読にマークします。

カレンダーツール

• list-calendar-events - カレンダーイベントを一覧表示します。
• create-calendar-event - 新しいイベントを作成します。
• delete-calendar-event - イベントを削除します。
• accept-calendar-event - 会議招待を承諾します。
• decline-calendar-event - 会議招待を拒否します。

フォルダツール

• list-folders - メールフォルダを一覧表示します。
• create-folder - 新しいフォルダを作成します。
• move-email - メールをフォルダに移動します。

デプロイメント

Railwayデプロイメント

1. RailwayにGitHubリポジトリを接続します。
2. Railwayダッシュボードで環境変数を設定します。
3. git push時に自動的にデプロイされます。

Railway用の環境変数:

MS_CLIENT_ID=your-azure-client-id
MS_CLIENT_SECRET=your-azure-client-secret
OUTLOOK_CLIENT_ID=your-azure-client-id
OUTLOOK_CLIENT_SECRET=your-azure-client-secret
NODE_ENV=production
USE_TEST_MODE=false

Dockerデプロイメント

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3001
CMD ["npm", "run", "start-remote"]

手動サーバーセットアップ

1. リポジトリをクローンします。
2. 依存関係をインストールします: npm ci --production
3. 環境変数を設定します。
4. サーバーを起動します: npm run start-remote
5. 必要に応じてリバースプロキシ（nginx/Apache）を設定します。

アーキテクチャ

outlook-mcp/
├── auth/                  # 認証とアカウント管理
│   ├── index.js          # メインの認証モジュールエクスポート
│   ├── server.js         # OAuthサーバー（ルートから移動）
│   ├── account-manager.js # 複数アカウント管理
│   ├── token-manager.js  # トークンの保存と更新
│   └── tools.js          # 認証MCPツール
├── calendar/             # カレンダー操作
├── email/               # メール操作
├── folder/              # フォルダ管理
├── rules/               # メールルール
├── utils/               # 共有ユーティリティ
│   ├── graph-api.js     # Graph APIヘルパー
│   ├── odata-helpers.js # ODataクエリビルダー
│   ├── permissions.js   # パーミッションチェック
│   └── mock-data.js     # テストデータ
├── Scripts/             # デプロイメントと管理スクリプト
├── config.js            # 設定管理
├── index.js             # メインサーバーのエントリポイント
└── package.json         # 依存関係とスクリプト

セキュリティ

ベストプラクティス

• すべてのシークレット情報は環境変数で管理します。
• アカウントごとに個別のトークン保存を行います。
• トークンは自動的に更新されます。
• 本番環境ではHTTPSを強制します。
• リモートアクセス用にCORS設定を行います。

トークン管理

• トークンは~/.outlook-mcp-accounts/に保存されます。
• 期限切れ前に自動的に更新されます。
• 一意のアカウントIDで安全にトークンを保存します。
• アカウント削除時にはクリーンアップされます。

トラブルシューティング

一般的な問題

"No accounts configured"

• 解決策: authenticateツールを使用してアカウントを追加します。

"Authentication required for account X"

• 解決策: 特定のアカウントを再認証します。

ブラウザでCORSエラーが発生する

• 解決策: ドメインのCORS設定を確認します。

ポートが既に使用されている

• 解決策: MCP_PORT環境変数を変更します。

ヘルスチェック

• ローカル: check-auth-statusツールを使用します。
• リモート: http://localhost:3001/healthにアクセスします。

ログ

• サーバーのログはstderrに出力されます。
• 認証イベントはアカウントIDとともに記録されます。
• デバッグ用のエラー詳細が記録されます。

開発

前提条件

• Node.js 14以上
• Azureアプリ登録
• Microsoft Graph APIパーミッション

スクリプト

• npm start - ローカルstdioモード
• npm run start-remote - リモートHTTPモード
• npm run auth-server - OAuthサーバーのみ起動
• npm run test-mode - モックデータで実行
• npm run inspect - MCPインスペクターで実行

コントリビューション

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. テストを含めて変更を加えます。
4. ドキュメントを更新します。
5. プルリクエストを送信します。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

サポート

• GitHubの問題: バグ報告
• ドキュメント: このREADME
• MCPプロトコル: modelcontextprotocol.io
• Microsoft Graph: docs.microsoft.com/graph