Outlook Assistant
Manage Outlook authentication, calendar events, email, mail folders, and inbox rules through Microsoft Graph.
Authentication: Get server information, authenticate or force re-authentication, and check current auth status.
Calendar: List upcoming events; create, accept, decline, cancel, and delete events.
Email: List recent inbox messages; search across folders with sender, recipient, subject, text, unread, and attachment filters; read previews or full bodies; send emails; mark emails read/unread.
Folders: List mail folders with optional hierarchy and item counts, create folders, and move emails between folders.
Rules: List inbox rules with optional details, create rules using sender/subject/attachment conditions and move/mark-read actions, and change rule execution order.
Note: The README also advertises broader capabilities like contacts, tasks, out-of-office, attachments, and drafts, but the provided schema only exposes the tools above.
Outlook MCP Server
Let AI manage your Outlook inbox, calendar, contacts, tasks and rules — through natural language.
Built on Model Context Protocol · Powered by Microsoft Graph API
What is this?
This MCP server turns any compatible AI assistant into a full-featured Outlook assistant. Instead of clicking through the Outlook UI, just ask your AI:
"Show me unread emails from this week" "Schedule a meeting with Alice tomorrow at 3pm and check if she's free first" "Forward that email to my team and create a follow-up task" "Set my out-of-office until Friday"
Your AI handles authentication, API calls, pagination, filtering — everything. You just talk.
Related MCP server: Outlook MCP
Capabilities
Area | Tools | What your AI can do |
13 | List, search, read (preview or full body), send, reply, reply-all, forward, delete, mark read/unread, manage drafts, list and download attachments | |
Calendar | 10 | List calendars, list events, create, update, accept, tentatively accept, decline, cancel, delete, check free/busy schedules |
Folders | 5 | List folder hierarchy, create folders, move emails between folders, rename folders, delete folders |
Contacts | 6 | List/search, create (basic/full), update, delete contacts in your address book |
Mailbox | 2 | Get mailbox settings (timezone, language), set out-of-office auto-replies |
Tasks | 5 | List task lists, list tasks, create, update, complete, delete (Microsoft To Do) |
Rules | 5 | List, create, update, delete inbox rules and change rule execution order |
Auth | 3 | OAuth 2.0 with automatic token refresh — authenticate once, use forever |
Resources | 20 | 13 static resources + 7 resource templates across email, calendar, contacts, folders, mailbox, tasks, rules |
Prompts | 7 | Reusable prompt templates for common Outlook workflows |
Completions | 9 | Argument completion handlers for folder names, event IDs, contact emails, and more |
55 tools, 20 resources, 7 prompts, 9 completions total.
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 your MCP client config and start using!Azure App Setup
You need an Azure app registration to connect to Microsoft Graph.
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/callbackClick Register
Copy the Application (client) ID → this is your
OUTLOOK_CLIENT_ID
Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions, then add:
offline_accessUser.ReadMail.ReadMail.ReadWriteMail.SendCalendars.ReadCalendars.ReadWriteContacts.ReadContacts.ReadWriteMailboxSettings.ReadMailboxSettings.ReadWriteMailboxFolder.ReadMailboxFolder.ReadWriteTasks.ReadTasks.ReadWrite
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-VALUEImportant: Always use the secret VALUE from Azure, not the Secret ID.
MCP Client Configuration
Add to your MCP client config (e.g., claude_desktop_config.json, VS Code settings, etc.):
{
"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"
}
}
}
}See AGENTS.md for client-specific examples.
Advanced
Edit config.js to customize server name, timezone, pagination limits, field selections, and response format (toon or text).
Authentication Flow
You ──ask AI──▸ "authenticate"
│
AI 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 neededStep 1 — Start the auth server (must be running before authenticating):
npm run auth-serverStep 2 — Ask your AI 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 (McpServer with resources, prompts, completions)
config.js ── centralized constants & settings
outlook-auth-server.js ── standalone OAuth server
auth/ ── authentication & token management
email/ ── list, search, read, send, reply, forward, delete,
│ mark-as-read, attachments, drafts
calendar/ ── list calendars & events, create, update, accept,
│ tentatively-accept, decline, cancel, delete, free-busy
folder/ ── list, create, move, rename, delete
contacts/ ── list, create (basic/full), update, delete
mailbox/ ── settings, out-of-office
tasks/ ── task lists and tasks (Microsoft To Do)
rules/ ── list, create, update, delete, edit-sequence
prompts/ ── 7 reusable prompt templates
completion/ ── 9 argument completion handlers
utils/
├── graph-client.js ── Graph SDK wrapper with pagination
├── response-formatter.js ── TOON / plain-text output toggle
└── response-helpers.js ── error detection & MCP response builders
scripts/ ── CLI utilities & debug helpersAvailable Commands
Command | Description |
| Install dependencies |
| Start the MCP server (stdio) |
| Start OAuth server on port 3333 |
| Launch MCP Inspector for interactive testing |
| Run Jest test suite |
| Print env vars and start server |
| Free port 3333 if occupied |
Troubleshooting
Run npm install first.
npx kill-port 3333
npm run auth-serverYou're using the Secret ID instead of the Secret Value. Go to Azure Portal → Certificates & secrets → copy the Value column.
The auth server isn't running. Start it first with npm run auth-server, then retry.
Token may be expired or corrupted. Delete ~/.outlook-mcp-tokens.json and re-authenticate.
Verify the absolute path to
index.jsin your Claude Desktop configEnsure
OUTLOOK_CLIENT_IDandOUTLOOK_CLIENT_SECRETare setRestart Claude Desktop after config changes
Extending the Server
Adding a new tool is straightforward:
Create a handler file in the appropriate module directory
Export
{ name, description, inputSchema, handler }Add it to the module's
index.jsexportsIt's automatically registered via
index.jsat the root
See AGENTS.md for the full checklist.
License
Available Tools
20 toolsaboutB
Returns information about this Outlook Assistant server
Inputs: no named parameters.
accept-eventC
Accepts a calendar event invitation
Inputs: eventId (required), comment.
authenticateC
Authenticate with Microsoft Graph API to access Outlook data
Inputs: force.
cancel-eventC
Cancels a calendar event
Inputs: eventId (required), comment.
check-auth-statusB
Check the current authentication status with Microsoft Graph API
Inputs: no named parameters.
create-eventC
Creates a new calendar event
Inputs: subject (required), start (required), end (required), attendees, +1 more.
create-folderC
Creates a new mail folder
Inputs: name (required), parentFolder.
create-ruleC
Creates a new inbox rule
Inputs: name (required), fromAddresses, containsSubject, hasAttachments, +4 more.
decline-eventC
Declines a calendar event
Inputs: eventId (required), comment.
delete-eventC
Deletes a calendar event
Inputs: eventId (required).
edit-rule-sequenceC
Changes the execution order of an existing inbox rule
Inputs: ruleName (required), sequence (required).
list-emailsB
Lists recent emails from your inbox
Inputs: folder, count.
list-eventsC
Lists upcoming events from your calendar
Inputs: count.
list-foldersC
Lists mail folders in your Outlook account
Inputs: includeItemCounts, includeChildren.
list-rulesC
Lists inbox rules in your Outlook account
Inputs: includeDetails.
mark-as-readC
Marks an email as read or unread
Inputs: id (required), isRead.
move-emailsC
Moves emails from one folder to another
Inputs: emailIds (required), targetFolder (required), sourceFolder.
read-emailA
Reads the content of a specific email. Returns a short preview (255 chars) by default. Set fullBody=true to fetch the complete email body.
Inputs: id (required), fullBody.
search-emailsB
Search for emails using various criteria. Searches across ALL folders (inbox, archive, sent, etc.) by default. Specify folder to limit scope.
Inputs: query, folder, from, to, +4 more.
send-emailC
Composes and sends a new email
Inputs: to (required), subject (required), body (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 20 tools
Each tool has a clearly distinct purpose with no ambiguity, such as accept-event vs. decline-event for calendar responses, or list-emails vs. search-emails for email retrieval. The descriptions reinforce distinct actions on specific resources like events, emails, folders, and rules, ensuring agents can easily differentiate between tools.
All tool names follow a consistent verb_noun pattern with hyphens, such as create-event, list-folders, and mark-as-read. There are no deviations in naming conventions, making the set predictable and easy to parse for agents.
With 20 tools, the count is slightly high but reasonable for the Outlook domain, covering email, calendar, folders, and rules comprehensively. It includes core CRUD operations and management functions, though it might be borderline for some use cases due to the breadth.
The tool surface provides complete coverage for the Outlook domain, including CRUD operations for events, emails, folders, and rules, along with authentication and status checks. There are no obvious gaps, as it supports full lifecycle management from creation to deletion and search capabilities.
Maintenance
Related MCP Connectors
MCP server for Nylas — read email, calendars, events and contacts, and send email or create events.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
MCP server for Cronofy — read calendars, events and free/busy, and create, update or delete events.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables sending emails through Microsoft Outlook using the Microsoft Graph API. Provides the missing send-email capability for Agent Builder's Outlook connector with support for both delegated and app-only authentication flows.MIT
- AlicenseNot gradedqualityDmaintenanceEnables semantic search and AI-powered analysis of Outlook emails using RAG-based natural language queries and Vision AI for architectural documents, with specialized support for AEC workflows.MIT
- AlicenseBqualityDmaintenanceA 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-