Skip to main content
Glama

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

Node.js License: MIT MCP SDK


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

Email

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.

  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.

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 needed

Step 1 — Start the auth server (must be running before authenticating):

npm run auth-server

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

  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 AGENTS.md for the full checklist.


License

MIT

Available Tools

20 tools
aboutB

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

    A3.5/5.0

    Scored across 20 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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
      -