outlook-mcp-server
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 install2. Azure Portalでアプリを登録する
この登録によって、このサーバーがあなたの代わりにMicrosoft Graphと通信するために使用するクライアントIDが発行されます。npm run setup(下記)がこの手順を対話的に案内しますが、手順は次のとおりです:
portal.azure.com にアクセスし、任意のMicrosoftアカウントでサインインします。
アプリの登録 を検索 → + 新規登録 をクリックします。
フォームに入力します:
名前: 任意の名前(例:
outlook-mcp-server)。サポートされているアカウントの種類: 「個人用Microsoftアカウントのみ」。これにより、アプリが職場/学校(Azure AD)テナントではなく、Hotmail/Outlook.com/Liveアカウントに制限されます。
リダイレクトURI: プラットフォーム 「パブリッククライアント/ネイティブ(モバイル&デスクトップ)」、値
http://localhost:8765/callback(または別のポート — セットアップスクリプトが尋ねたときに一貫していれば問題ありません)。
登録 をクリックし、概要ページから アプリケーション(クライアント)ID をコピーします。
APIのアクセス許可 → + アクセス許可の追加 → Microsoft Graph → 委任されたアクセス許可 に移動し、以下を追加します:
Mail.ReadMail.ReadWriteMail.Sendoffline_access(通常はデフォルトで存在します)
このような個人用Microsoftアカウントの委任されたアクセス許可は管理者の同意を必要とせず、下記の手順3のサインイン時に自分で同意します。
(任意、上級者向け) パブリッククライアントのPKCEフローの代わりにクライアントシークレット付きの機密クライアントを使用したい場合は、Web プラットフォームのリダイレクトURIを追加し、証明書とシークレット の下でシークレットを作成します。ほとんどの人はこれをスキップして問題ありません。
3. セットアップを実行(認証+設定)
npm run setupこれにより:
上記の手順が表示されます。
クライアントID(およびオプションのシークレット/テナント/リダイレクトURI)を求め、
~/.outlook-mcp-server/config.jsonに保存します。ブラウザを開いてサインインと同意を行います。
GET /meを呼び出してトークンが機能することを確認し、名前/メールアドレスを表示します。Claude設定に追加するJSONスニペットを表示します(下記参照)。
後で再認証する場合(トークンの失効、アカウントの切り替えなど)、アプリ登録の詳細を再入力せずに:
npm run login4. ビルドしてClaudeに登録する
npm run buildClaude 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.jsClaude Desktop / Claude Codeを再起動します。以下のツールが利用可能になるはずです。
ツール
ツール | 説明 |
| フォルダ(デフォルトは |
| IDで1件のメッセージの完全な内容(本文、すべての受信者)を取得します。 |
| メール全体をフリーテキスト検索( |
| メールを即座に送信します( |
| 送信せずに下書きフォルダに下書きを作成します。 |
| メールフォルダとそのIDを一覧表示します。上記の |
すべてのツールは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 を参照してください:
変数 | 目的 |
| Azureアプリ登録のクライアントID。 |
| 秘密クライアント(Webプラットフォーム)を使用する場合のみ。 |
|
|
| Azureアプリ登録と一致している必要があります。 |
| 設定/トークンキャッシュの保存場所。デフォルトは |
セキュリティノート
トークンキャッシュは、ローカルで生成された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) setupAvailable Tools
6 toolscreate_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Connect any IMAP/SMTP mailbox to Claude & ChatGPT: search, read, sort, draft. Sends only with OK.
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Related MCP Servers
- AlicenseBqualityCmaintenanceA MCP server for Claude that reads Outlook emails its attachments through the Microsoft Graph API.619MIT
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseNot gradedqualityDmaintenanceMCP server that enables Claude to manage Outlook emails, including reading, sending, organizing, drafting, and bulk operations via Microsoft Graph API.15 npm1MIT
- AlicenseAqualityDmaintenanceAn 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.312MIT