m365-mcp

m365-mcp

Microsoft 365 MCP Server v2 — AI-orchestrated tools for email, calendar, and real-time notifications via the Model Context Protocol.

Features

• Unified Messages: Email (list, read, send, reply, forward, delete, mark-read, context)
• Calendar & Meetings: Events and online meetings
• Real-time Notifications: Webhook-based alerts with AI priority filtering
• AI Summaries: Conversation summaries, inbox briefings, and work status
• Smart Contact Resolution: Automatic name-to-email resolution
• Authentication: Device code flow with automatic token caching

Prerequisites

• Node.js 18+
• Azure AD Application with delegated permissions

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Start MCP server
npm run mcp

Commands

Build & Development

Command	Description
npm run build	Compile TypeScript to JavaScript
npm run dev	Watch mode - recompile on changes
npm run mcp	Start MCP server (stdio transport)
npm run start:stdio	Start MCP server (stdio transport)
npm run start:http	Start MCP server (HTTP transport)

Testing

Command	Description
npm test	Run all tests
npm run test:unit	Run unit tests only
npm run test:integration	Run integration tests only
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with coverage report

Linting

Command	Description
npm run lint	Check for linting errors
npm run lint:fix	Fix auto-fixable linting errors

Utilities

No additional utility scripts required.

Authentication

The server uses Microsoft's device code flow for authentication. Tokens are cached at ~/.m365-mcp/msal-cache.json.

First-time Setup

The server uses device code flow for authentication. On first use, the MCP client will receive an authentication URL and code. Follow the instructions to complete sign-in.

Managing Auth Cache

Tokens are cached at ~/.m365-mcp/msal-cache.json. To force re-authentication, delete this file:

rm ~/.m365-mcp/msal-cache.json

Configuration

Environment variables can be set in a .env file at the project root:

Variable	Description	Default
M365_CLIENT_ID	Azure AD Application (client) ID	Required
M365_TENANT_ID	Azure AD Tenant ID	common
M365_TIMEZONE	Timezone for calendar operations	W. Europe Standard Time
HTTP_PORT	Port for HTTP transport	3365
POLL_INTERVAL_MINUTES	Interval in minutes for checking new emails (notifications)	5
LOG_LEVEL	Logging level (none, debug, info, warn, error)	none
LOG_FILE	Path to log file (if set, logs to file instead of stderr)	—
DEBUG	Throw exceptions on cache errors (true/1)	false

MCP Integration

Cursor IDE

Use this config when you want Cursor to start m365-mcp from npm via npx. This is the recommended setup after the package is published.

{
  "mcpServers": {
    "m365-mcp-stdio": {
      "command": "npx",
      "args": ["-y", "m365-mcp"],
      "env": {
        "NODE_ENV": "production",
        "M365_CLIENT_ID": "YOUR_AZURE_APP_CLIENT_ID",
        "M365_TIMEZONE": "W. Europe Standard Time"
      }
    }
  }
}

If you are developing locally in this repository, keep using your local build:

{
  "mcpServers": {
    "m365-mcp-stdio": {
      "command": "node",
      "args": ["dist/server/stdio.js"],
      "cwd": "${workspaceFolder}",
      "env": {
        "NODE_ENV": "production",
        "M365_CLIENT_ID": "YOUR_AZURE_APP_CLIENT_ID",
        "M365_TIMEZONE": "W. Europe Standard Time"
      }
    }
  }
}

Other MCP clients

For other MCP clients, use either:

• Published package: command npx with args ["-y", "m365-mcp"]
• Local repo build: command node with args ["dist/server/stdio.js"]

Available MCP Tools

5 Unified Tools (replacing 14 previous tools)

message - Email

Email messages (list, read, send, reply, forward, delete, mark-read, context).

Actions: send, list, read, reply, forward, delete, mark-read, context

• Resolves contact names to email addresses
• Provides conversation context before sending
• Inbox view with folder and filter support

calendar - Events & Meetings

Calendar events and online meetings.

Actions: list, get, create, update, delete, respond

• Resolves attendee names automatically
• Manages calendar events and meeting responses

me - User Info & People Lookup

Current user information and organization directory search.

Actions: (default) for user info, lookup for people search

• Get current user profile
• Search people by name, role, or department

summary - AI Briefings & Summaries

AI-generated summaries of conversations, inbox, and work status.

Actions: briefing, conversation, inbox, day, status

• Morning briefings with highlights and action items
• Conversation summaries with key points
• Inbox summaries grouped by topic/sender
• Day summaries combining calendar and messages

notifications - New Email Alerts

Configure filters and list subscriptions. New emails are checked at a fixed interval (e.g. 5 min); matching notifications appear in the client's MCP logs.

Actions: list, configure

• Polling for new messages (no public URL required)
• Priority filtering (high/normal/low)
• VIP sender detection
• Urgent keyword detection

Notifications (Polling)

The server checks for new emails at a fixed interval (default 5 minutes). Matching messages are delivered to the client via MCP logging (notifications/message). No public URL or webhook is required.

1. Optional: Set POLL_INTERVAL_MINUTES (default: 5).
2. Configure priority filtering via the notifications tool:

   action: configure
   priority: high
   vipSenders: ceo@company.com,client@important.com
   keywords: urgent,asap,deadline

3. Works with both stdio and HTTP transport.

Project Structure

m365-mcp/
├── src/
│   ├── auth/
│   │   ├── cache.ts                  # Token cache management
│   │   └── index.ts                  # Authentication flow
│   ├── graph/
│   │   ├── client.ts                 # Graph API client
│   │   ├── email.ts                  # Email operations
│   │   ├── calendar.ts               # Calendar operations
│   │   ├── contact.ts                # Contact operations
│   │   └── subscriptions.ts          # List Graph subscriptions (read-only)
│   ├── services/
│   │   ├── contact-resolver.ts       # Smart contact lookup
│   │   └── summarizer.ts             # AI summary generation
│   ├── notifications/
│   │   ├── handler.ts                # Polling and notification delivery
│   │   └── priority.ts               # Priority classification
│   ├── server/
│   │   ├── index.ts                  # MCP server setup
│   │   ├── stdio.ts                  # Stdio transport entry
│   │   └── http.ts                   # HTTP transport entry
│   ├── tools/
│   │   ├── message-tool.ts           # Unified message tool
│   │   ├── calendar-tool.ts          # Unified calendar tool
│   │   ├── me-tool.ts                # User info tool
│   │   ├── summary-tool.ts           # Summary tool
│   │   └── notification-tool.ts      # Notifications tool
│   └── utils/
│       ├── config.ts                 # Configuration
│       └── logger.ts                 # Singleton logger
├── tests/
│   ├── unit/                         # Unit tests
│   ├── integration/                  # Integration tests
│   └── fixtures/                     # Test fixtures
├── dist/                             # Compiled JavaScript
├── .cursor/
│   └── mcp.json                      # Cursor MCP config
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── eslint.config.js

License

MIT