What can you do with this server?

The Outlook Assistant MCP server enables AI-powered management of Outlook email, calendar, folders, and rules through natural language commands. Email Management: List, search, and read emails across all folders with advanced filtering (sender, recipient, subject, attachments, unread status). Send emails with CC/BCC support, importance levels, and HTML/plain text body options. Mark emails as read/unread and move them between folders. Calendar Management: Full event lifecycle management including listing upcoming events, creating events with attendees, accepting/declining invitations with optional comments, canceling, and deleting events. Folder Organization: List folder hierarchy with item counts, create new folders (including nested structures), and move emails between folders. Inbox Rules Automation: List existing rules with detailed conditions and actions, create new rules with conditions (sender, subject, attachments) and actions (move to folder, mark as read), and edit rule execution order/sequence. Authentication & Status: OAuth 2.0 authentication with Microsoft Graph API, automatic token refresh for persistent access, check authentication status, and force re-authentication if needed. Key Features: Automatic pagination for large result sets (up to 500 emails/events), configurable output formats (TOON or plain text), and searches across all folders by default.

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

Node.js License: MIT MCP SDK

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
Email	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.

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

Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions, then add:

offline_access
User.Read
Mail.Read
Mail.Send
Calendars.Read
Calendars.ReadWrite
Contacts.Read

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-server.js ── standalone OAuth server auth/ ── authentication & token management email/ ── list, search, read, send, mark-as-read calendar/ ── list, create, accept, decline, cancel, delete folder/ ── list, create, move rules/ ── list, create, edit-rule-sequence 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 helpers

Available Commands

Command	Description
`npm install`	Install dependencies
`npm start`	Start the MCP server (stdio)
`npm run auth-server`	Start OAuth server on port 3333
`npm run inspect`	Launch MCP Inspector for interactive testing
`npm test`	Run Jest test suite
`npm run debug`	Print env vars and start server
`npx kill-port 3333`	Free port 3333 if occupied

Troubleshooting

Run npm install first.

npx kill-port 3333 npm run auth-server

You'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.js in your Claude Desktop config
Ensure OUTLOOK_CLIENT_ID and OUTLOOK_CLIENT_SECRET are set
Restart 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.js exports
It's automatically registered via index.js at the root

See .cursor/rules/new-tool.mdc for the full checklist.

License

MIT

Outlook Assistant