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

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_access
User.Read
Mail.Read
Mail.Send
Calendars.Read
Calendars.ReadWrite
Contacts.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-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

Cannot find module '@modelcontextprotocol/sdk'

Run npm install first.

EADDRINUSE: port 3333 already in use

npx kill-port 3333
npm run auth-server

Invalid client secret (AADSTS7000215)

You're using the Secret ID instead of the Secret Value. Go to Azure Portal → Certificates & secrets → copy the Value column.

Auth URL doesn't load / "site can't be reached"

The auth server isn't running. Start it first with npm run auth-server, then retry.

"Authentication required" after setup

Token may be expired or corrupted. Delete ~/.outlook-mcp-tokens.json and re-authenticate.

Server doesn't start in Claude Desktop

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