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

Claude handles authentication, API calls, pagination, filtering — everything. You just talk.

Related MCP server: Outlook MCP

Capabilities

45 tools 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 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.ReadWrite

• Mail.Send

• Calendars.Read

• Calendars.ReadWrite

• Contacts.Read

• Contacts.ReadWrite

• MailboxSettings.Read

• MailboxSettings.ReadWrite

• MailboxFolder.Read

• MailboxFolder.ReadWrite

• Tasks.Read

• Tasks.ReadWrite

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, 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
contacts/                 ── list, create, update, delete
mailbox/                  ── settings, out-of-office
tasks/                    ── task lists and tasks (Microsoft To Do)
rules/                    ── list, create, update, delete, edit-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