Outlook MCP Server

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

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. Open Azure Portal → App registrations
2. Click New registration
3. Name: Outlook MCP Server (or anything you like)
4. Account type: Accounts in any organizational directory and personal Microsoft accounts
5. Redirect URI: Web → http://localhost:3333/auth/callback
6. Click Register
7. 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

1. Go to Certificates & secrets → Client secrets → New client secret
2. Set description and longest expiration
3. Copy the secret VALUE (not the Secret ID!)
4. 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

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.

1. Verify the absolute path to index.js in your Claude Desktop config
2. Ensure OUTLOOK_CLIENT_ID and OUTLOOK_CLIENT_SECRET are set
3. Restart Claude Desktop after config changes

Extending the Server

Adding a new tool is straightforward:

1. Create a handler file in the appropriate module directory
2. Export { name, description, inputSchema, handler }
3. Add it to the module's index.js exports
4. It's automatically registered via index.js at the root

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

License

MIT