Skip to main content
Glama
outlook-mcp-server

outlook-mcp-server

by acangialosi

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を再起動します。以下のツールが利用可能になるはずです。

ツール

ツール

説明

list_messages

フォルダ(デフォルトは inbox)からメッセージを一覧表示します。since/until の日付フィルター、unreadOnly、並べ替え、ページネーションに対応。

get_message

IDで1件のメッセージの完全な内容(本文、すべての受信者)を取得します。

search_messages

メール全体をフリーテキスト検索($search)し、オプションでフォルダに限定します。

send_message

メールを即座に送信します(to/cc/bcc、件名、テキストまたはHTML本文)。

create_draft

送信せずに下書きフォルダに下書きを作成します。

list_folders

メールフォルダとそのIDを一覧表示します。上記の folder パラメータで使用します。

すべてのツールは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 を参照してください:

変数

目的

OUTLOOK_MCP_CLIENT_ID

Azureアプリ登録のクライアントID。

OUTLOOK_MCP_CLIENT_SECRET

秘密クライアント(Webプラットフォーム)を使用する場合のみ。

OUTLOOK_MCP_TENANT

consumers(デフォルト)または common。

OUTLOOK_MCP_REDIRECT_URI

Azureアプリ登録と一致している必要があります。

OUTLOOK_MCP_CONFIG_DIR

設定/トークンキャッシュの保存場所。デフォルトは ~/.outlook-mcp-server。

セキュリティノート

  • トークンキャッシュは、ローカルで生成された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

Available Tools

6 tools
create_draftCreate a draft emailA

Create a draft message in the mailbox's Drafts folder without sending it. Prefer this over send_message whenever the user should review the email first.

Inputs: cc, to, bcc, body, +2 more.

get_messageGet full email messageA

Fetch the full content (including body, all recipients, and sender) of a single message by its Graph message ID, as returned by list_messages or search_messages.

Inputs: messageId (required).

list_foldersList mail foldersA

List top-level mail folders in the mailbox (Inbox, Sent Items, Drafts, Archive, custom folders, etc.) along with their IDs and item counts. Use a returned folder ID with list_messages or search_messages to target that folder.

Inputs: no named parameters.

list_messagesList email messagesA

List messages from a mail folder (default: inbox), newest first by default. Supports date-range and read/unread filtering. Use list_folders first if you need a folder ID other than a well-known name like 'inbox', 'drafts', 'sentitems', 'archive', or 'junkemail'.

Inputs: top, skip, since, until, +4 more.

search_messagesSearch email messagesA

Full-text search across mail (subject, body, sender, recipients, attachments) using Microsoft Graph's $search, ranked by relevance. Optionally scope the search to one folder. For structured filtering (date ranges, read/unread) without free-text search, prefer list_messages instead.

Inputs: query (required), top, folder.

send_messageSend an emailA

Send a new email immediately from the signed-in mailbox. This sends right away — there is no confirmation step, so only call this once you (and the user, if appropriate) are sure about the recipients and content. Use create_draft instead if the message should be reviewed before sending.

Inputs: to (required), body (required), subject (required), cc, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: listing, fetching, searching, folder enumeration, sending, and drafting. The only possible confusion is between list_messages and search_messages, but their descriptions clearly differentiate structured filtering from full-text relevance search.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: list_messages, get_message, search_messages, list_folders, send_message, create_draft. There are no style mixups or vague verbs.

    Tool Count5/5

    Six tools is a well-scoped set for an Outlook mail server. Each tool covers a distinct core email operation without unnecessary bloat or missing essentials.

    Completeness4/5

    The tool surface covers the primary mail workflows: listing, searching, reading, sending, drafting, and folder navigation. Some common operations like reply, forward, delete, move, or updating drafts are absent, but the core read/send workflow is solid.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Python-based MCP server for Microsoft Outlook integration using Microsoft Graph API, enabling email reading/sending, calendar management, and contact operations through Claude Desktop.
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables Claude to manage Outlook emails, including reading, sending, organizing, drafting, and bulk operations via Microsoft Graph API.
      15 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that gives Claude Code and Codex full control of a personal Outlook.com mailbox and calendar via the Microsoft Graph API, enabling mail, draft, folder, and calendar operations through natural language.
      31
      2
      MIT