Let AI manage your Outlook inbox, calendar, and rules — through natural language.
Outlook MCP Server
Let AI manage your Outlook inbox, calendar, and rules — through natural language.
Built on Model Context Protocol · Powered by Microsoft Graph API
What is this?
This MCP server turns Claude into a full-featured Outlook assistant. Instead of clicking through the Outlook UI, just ask Claude:
"Show me unread emails from this week" "Schedule a meeting with Alice tomorrow at 3pm" "Create a rule to move all GitHub notifications to a folder"
Claude handles authentication, API calls, pagination, filtering — everything. You just talk.
Capabilities
| Area | What Claude can do |
|---|---|
| List, search, read (preview or full body), send, mark read/unread | |
| Calendar | List upcoming events, create, accept, decline, cancel, delete |
| Folders | List folder hierarchy, create folders, move emails between folders |
| Rules | List inbox rules, create new rules, change rule execution order |
| Auth | OAuth 2.0 with automatic token refresh — authenticate once, use forever |
Quick Start
# 1. Clone and install
git clone https://github.com/titanzero/outlook-mcp.git
cd outlook-mcp
npm install
# 2. Configure (see Azure Setup below)
cp .env.example .env
# Edit .env with your Azure credentials
# 3. Start the OAuth server and authenticate
npm run auth-server
# 4. Add to Claude Desktop config and start using!
Azure App Setup
You need an Azure app registration to connect to Microsoft Graph.
1. Register the App
- Open Azure Portal → App registrations
- Click New registration
- Name:
Outlook MCP Server(or anything you like) - Account type: Accounts in any organizational directory and personal Microsoft accounts
- Redirect URI: Web →
http://localhost:3333/auth/callback - Click Register
- Copy the Application (client) ID → this is your
OUTLOOK_CLIENT_ID
2. Set API Permissions
Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions, then add:
offline_accessUser.ReadMail.ReadMail.SendCalendars.ReadCalendars.ReadWriteContacts.Read
3. Generate Client Secret
- Go to Certificates & secrets → Client secrets → New client secret
- Set description and longest expiration
- Copy the secret VALUE (not the Secret ID!)
- This is your
OUTLOOK_CLIENT_SECRET
Configuration
Environment Variables
Create .env in the project root:
OUTLOOK_CLIENT_ID=your-application-client-id
OUTLOOK_CLIENT_SECRET=your-client-secret-VALUE
Important: Always use the secret VALUE from Azure, not the Secret ID.
Claude Desktop
Add to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"outlook-assistant": {
"command": "node",
"args": ["/absolute/path/to/outlook-mcp/index.js"],
"env": {
"OUTLOOK_CLIENT_ID": "your-client-id",
"OUTLOOK_CLIENT_SECRET": "your-client-secret"
}
}
}
}
Advanced
Edit config.js to customize server name, timezone, pagination limits, field selections, and response format (toon or text).
Authentication Flow
You ──ask Claude──▸ "authenticate"
│
Claude returns URL ◂────┘
│
You open URL in browser ▸ Microsoft login ▸ Grant permissions
│
┌───────────────────────────┘
▼
OAuth callback on localhost:3333
Tokens saved to ~/.outlook-mcp-tokens.json
✔ Auto-refresh — no re-auth needed
Step 1 — Start the auth server (must be running before authenticating):
npm run auth-server
Step 2 — Ask Claude to authenticate, open the URL, sign in, done.
Tokens persist in ~/.outlook-mcp-tokens.json and refresh automatically.
Project Structure
index.js ── MCP entry point
config.js ── centralized constants & settings
outlook-auth-
Tools (4)
email_managementList, search, read, send, and mark emails as read or unread.calendar_managementList upcoming events, create, accept, decline, cancel, or delete calendar items.folder_managementList folder hierarchy, create folders, and move emails between folders.rule_managementList, create, and modify inbox rules and execution order.Environment Variables
OUTLOOK_CLIENT_IDrequiredThe Application (client) ID from your Azure App registration.OUTLOOK_CLIENT_SECRETrequiredThe client secret value generated in your Azure App registration.Configuration
{
"mcpServers": {
"outlook-assistant": {
"command": "node",
"args": ["/absolute/path/to/outlook-mcp/index.js"],
"env": {
"OUTLOOK_CLIENT_ID": "your-client-id",
"OUTLOOK_CLIENT_SECRET": "your-client-secret"
}
}
}
}