outlook-mcp-server

モデルコンテキストプロトコルに基づくローカルMCPサーバーで、Claude（DesktopまたはCode）に個人用のHotmail / Outlook.comメールボックスへの読み書きアクセスを提供します。Microsoft Graph APIを介し、Microsoft IDプラットフォームに対するOAuth 2.0認可コードフロー（PKCE付き）を使用します。

list_messages、get_message、search_messages、send_message、create_draft、list_folders の6つのツールを公開します。

すべてがstdio上でローカルに動作します。ホスト型サービスはなく、メールは自分のマシンとMicrosoft自身のGraph API以外を経由しません。

仕組み

• 認証: MSAL Node が、https://login.microsoftonline.com/consumers に対して認可コード+PKCEフローを実行します（個人アカウントのみ — テナントの選択を参照）。リダイレクト先として短命のローカルHTTPサーバーを使用します。トークン（offline_access リフレッシュトークンを含む）はキャッシュされ、今後の実行時に自動的に更新されます。

• ストレージ: トークンキャッシュはMSALによってシリアライズされ、ローカルで生成されたキーでAES-256-GCM暗号化され、~/.outlook-mcp-server/token-cache.enc（モード 0600）に書き込まれます。キー自体は ~/.outlook-mcp-server/cache.key（こちらも 0600）に保存されます。この脅威モデルがカバーする範囲（としない範囲）についてはセキュリティノートを参照してください。

• Graph呼び出し: 軽量な fetch ベースのクライアントが、現在のアクセストークンで https://graph.microsoft.com/v1.0/... を呼び出します。

• MCPサーバー: @modelcontextprotocol/sdk 上に構築され、stdioで通信するため、Claude Desktop / Claude Codeから子プロセスとして直接起動できます。

Related MCP server: Outlook MCP Python

前提条件

• Node.js 18以上

• Microsoftアカウント（Hotmail、Outlook.com、Live） — Claudeにアクセスさせたいメールアドレス。

• アプリを登録するための無料のAzureアカウント（どのMicrosoftアカウントでも可能 — 有料のAzureサブスクリプションは不要です）。

1. インストール

git clone <this repo>
cd outlook-mcp-server
npm install

2. Azure Portalでアプリを登録する

この登録によって、このサーバーがあなたの代わりにMicrosoft Graphと通信するために使用するクライアントIDが発行されます。npm run setup（下記）がこの手順を対話的に案内しますが、手順は次のとおりです：

1. portal.azure.com にアクセスし、任意のMicrosoftアカウントでサインインします。

2. アプリの登録 を検索 → + 新規登録 をクリックします。

3. フォームに入力します：

   • 名前: 任意の名前（例：outlook-mcp-server）。

   • サポートされているアカウントの種類: 「個人用Microsoftアカウントのみ」。これにより、アプリが職場/学校（Azure AD）テナントではなく、Hotmail/Outlook.com/Liveアカウントに制限されます。

   • リダイレクトURI: プラットフォーム 「パブリッククライアント/ネイティブ（モバイル＆デスクトップ）」、値 http://localhost:8765/callback（または別のポート — セットアップスクリプトが尋ねたときに一貫していれば問題ありません）。

4. 登録 をクリックし、概要ページから アプリケーション（クライアント）ID をコピーします。

5. APIのアクセス許可 → + アクセス許可の追加 → Microsoft Graph → 委任されたアクセス許可 に移動し、以下を追加します：

   • Mail.Read

   • Mail.ReadWrite

   • Mail.Send

   • offline_access（通常はデフォルトで存在します）

   このような個人用Microsoftアカウントの委任されたアクセス許可は管理者の同意を必要とせず、下記の手順3のサインイン時に自分で同意します。

6. （任意、上級者向け） パブリッククライアントのPKCEフローの代わりにクライアントシークレット付きの機密クライアントを使用したい場合は、Web プラットフォームのリダイレクトURIを追加し、証明書とシークレット の下でシークレットを作成します。ほとんどの人はこれをスキップして問題ありません。

3. セットアップを実行（認証+設定）

npm run setup

これにより：

1. 上記の手順が表示されます。

2. クライアントID（およびオプションのシークレット/テナント/リダイレクトURI）を求め、~/.outlook-mcp-server/config.json に保存します。

3. ブラウザを開いてサインインと同意を行います。

4. GET /me を呼び出してトークンが機能することを確認し、名前/メールアドレスを表示します。

5. Claude設定に追加するJSONスニペットを表示します（下記参照）。

後で再認証する場合（トークンの失効、アカウントの切り替えなど）、アプリ登録の詳細を再入力せずに：

npm run login

4. ビルドしてClaudeに登録する

npm run build

Claude Desktop — claude_desktop_config.json に追加します（macOSでは ~/Library/Application Support/Claude/claude_desktop_config.json、Windowsでは %APPDATA%\Claude\claude_desktop_config.json）：

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

Claude Code：

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

Claude Desktop / Claude Codeを再起動します。以下のツールが利用可能になるはずです。

ツール

すべてのツールはJSON（MCPテキストコンテンツとして）を返し、Graph APIエラーをサーバーのクラッシュではなくツールエラーとして表示します。

テナントの選択

デフォルトでは consumers テナント（https://login.microsoftonline.com/consumers）を使用します。これは個人のMicrosoftアカウント（Hotmail/Outlook.com/Live）のみを受け付けます — 職場/学校のアカウントはサインイン時に拒否されます。個人アカウントとAzure ADアカウントの両方をサポートする必要がある場合は、npm run setup でテナントを common に設定します（または OUTLOOK_MCP_TENANT=common）。このプロジェクトは個人アカウント（consumers）のケース向けに設計・テストされています。

設定リファレンス

すべては npm run setup（~/.outlook-mcp-server/config.json に書き込まれる）または環境変数で設定できます。環境変数が優先されます — .env.example を参照してください：

セキュリティノート

• トークンキャッシュは、ローカルで生成されたAES-256-GCMキー（~/.outlook-mcp-server/cache.key、モード 0600）で保存時に暗号化されます。これは偶発的な開示（誤ったコミット、バックアップ、共有マシン上の他の非特権ユーザー）から保護しますが、キーが暗号化されたキャッシュの隣にあるため、すでにユーザーアカウントのファイルへの読み取りアクセス権を持つ攻撃者からは保護されません。より強力な保護が必要な場合は、src/auth/tokenCache.ts の ICachePlugin をOSのキーチェーン（例: keytar 経由）にバックアップされたものに置き換えてください — プラグインインターフェースは意図的にその1つのファイルに分離されています。

• ~/.outlook-mcp-server/（デフォルトではリポジトリの外）や、OUTLOOK_MCP_CLIENT_SECRET を含む .env ファイルをコミットしないでください。

• send_message はこのサーバー内で確認ステップなしで即座に送信します — Claudeは機密性の高いものを送信する前に、あなたに意図を確認することが期待されています。レビューステップが必要な場合は create_draft を優先してください。

• 要求されるスコープは Mail.Read、Mail.ReadWrite、Mail.Send、offline_access に限定されています — カレンダー、連絡先、またはより広範な Mail.* アプリケーションレベルのアクセスはありません。

トラブルシューティング

• AADSTS50020 / 「ユーザーアカウント...がテナントに存在しません」 — 個人アカウントを受け付けないテナントにアクセスしているか、consumers に対して職場/学校のアカウントでサインインしています。アプリ登録の「サポートされているアカウントの種類」が「個人用Microsoftアカウントのみ」であること、および OUTLOOK_MCP_TENANT が consumers（両方を意図的にサポートする場合は common）であることを確認してください。

• AADSTS50011 / リダイレクトURIの不一致 — ~/.outlook-mcp-server/config.json の redirectUri は、Azureアプリ登録で設定されたリダイレクトURIとポートを含めて完全に一致する必要があります。

• 「サインインしていません」というツールエラー — npm run login を実行してください。

• セットアップ/ログイン中にポートが使用中 — 別のプロセスがリダイレクトURIのポートを使用しています。そのプロセスを停止するか、アプリ登録と npm run setup を別のポートで再設定してください。

開発

npm run dev     # run the MCP server directly from TypeScript (stdio)
npm run build   # compile to dist/
npm run clean   # remove dist/

プロジェクト構造

src/
  index.ts            MCP server entrypoint (stdio transport)
  config.ts            Config loading (env + config file)
  auth/
    crypto.ts           AES-256-GCM file encryption helpers
    tokenCache.ts        MSAL ICachePlugin backed by crypto.ts
    msalClient.ts        MSAL app factory + silent token acquisition
    loginFlow.ts          Interactive loopback OAuth flow
  graph/
    client.ts            Generic Microsoft Graph fetch wrapper
    mail.ts               Mail-specific Graph calls
    types.ts              Graph response types
  tools/                 One file per MCP tool, registered in index.ts
scripts/
  setup.ts              Interactive one-time (and re-runnable) setup