useful-outlook-mcp
A remote MCP server for Microsoft Outlook with proper OAuth2 and agent-optimized tools.
Features
- Spec Compliant: RFC 9728/8414 OAuth metadata, RFC 7591 dynamic client registration
- Stateless OAuth: Tokens managed by client, not server—as OAuth intended
- Agent-Optimized Tools: Extensive prompt engineering in tool descriptions
- Dynamic Scopes: OAuth scopes auto-adjust to enabled tools
- Production Ready: Docker, rate limiting, read-only mode, tool filtering
Quick Start
npm install
npm run build
npm start # Server at http://localhost:3000
Required environment:
MS365_MCP_CLIENT_ID=your-azure-ad-client-id
MS365_MCP_CLIENT_SECRET=your-azure-ad-client-secret
MS365_MCP_TENANT_ID=your-tenant-id # or 'common'
Azure AD Setup
- Azure Portal → Microsoft Entra ID → App registrations → New
- Add delegated permissions:
User.Read,Mail.Read,Mail.ReadWrite,Mail.Send,Calendars.Read,Calendars.ReadWrite,Calendars.Read.Shared,offline_access - Add redirect URI:
http://localhost:6274/oauth/callback(for MCP Inspector) - Certificates & secrets → New client secret → Copy the value
- Copy Client ID, Client Secret, and Tenant ID to your
.env
Tools
list-mail-folders · list-mail-messages · search-mail · get-mail-message · send-mail · create-draft-mail · reply-mail · reply-all-mail · create-reply-draft · create-reply-all-draft · delete-mail-message · move-mail-message
Calendar
list-calendars · list-calendar-events · search-calendar-events · find-meeting-times · get-calendar-event · get-calendar-view · create-calendar-event · update-calendar-event · delete-calendar-event
Configuration
| Variable | Default | Description |
|---|---|---|
MS365_MCP_CLIENT_ID | required | Azure AD client ID |
MS365_MCP_CLIENT_SECRET | - | Client secret (optional) |
MS365_MCP_TENANT_ID | common | Tenant ID |
MS365_MCP_PORT | 3000 | Server port |
MS365_MCP_READ_ONLY_MODE | false | Disable write operations |
MS365_MCP_ENABLED_TOOLS | all | Comma-separated tool allowlist |
MS365_MCP_CORS_ORIGIN | * | CORS origins |
MS365_MCP_RATE_LIMIT_REQUESTS | 30 | Requests per window |
MS365_MCP_RATE_LIMIT_WINDOW_MS | 60000 | Window size (ms) |
MS365_MCP_ALLOWED_TENANTS | - | Restrict to specific tenants |
Docker
From GitHub Container Registry:
docker run -p 3000:3000 \
-e MS365_MCP_CLIENT_ID=xxx \
-e MS365_MCP_CLIENT_SECRET=xxx \
-e MS365_MCP_TENANT_ID=xxx \
ghcr.io/Leonine-Studios/useful-outlook-mcp:latest
Or build locally:
docker build -t useful-outlook-mcp .
docker run -p 3000:3000 \
-e MS365_MCP_CLIENT_ID=xxx \
-e MS365_MCP_CLIENT_SECRET=xxx \
-e MS365_MCP_TENANT_ID=xxx \
useful-outlook-mcp
Endpoints
| Endpoint | Description |
|---|---|
POST /mcp | MCP protocol |
GET /health | Health check |
GET /.well-known/oauth-protected-resource | RFC 9728 |
GET /.well-known/oauth-authorization-server | RFC 8414 |
GET /authorize | OAuth (proxies to Microsoft) |
POST /token | Token exchange (proxies to Microsoft) |
POST /register | Dynamic client registration |
Testing
npm run dev
npx @modelcontextprotocol/inspector # Connect to http://localhost:3000/mcp
Design Notes
Why another Outlook MCP server?
Problems with existing servers
-
Legacy architecture: Built as stdio with HTTP bolted on. This is HTTP-native.
-
OAuth done wrong: Most servers store tokens server-side. This server is stateless—tokens passed per-request via Authorization header, never stored.
-
Tools without thought: Typical servers map API endpoints 1:1 without guidance. Agents fail in practical use because they don't know API quirks or multi-step workflows.
What's different
Every tool includes:
- When to use it vs alternatives
- Known Graph API quirks (there are many)
- Workflow guidance for multi-step tasks
- Parameter combinations that fail
Example: find-meeting-times explains that email addresses are required (names don't work), how to find emails from names using search-mail, what OrganizerUnavailable means, and that isOrganizerOptional=true needs user confirmation.
Known Graph API quirks
- Mail sender filtering:
eqonfrom/emailAddress/addressis unreliable—usesstartswith() - Mail recipient filtering: Can't filter to/cc/bcc with
$filter—must use$search - Calendar organizer filtering:
$filteron organizer email returns 500—filtered client-side - Concurrency: Parallel calls can return
MailboxConcurrencyerrors - Search + sort:
$searchcan't combine with$orderby
License
MIT
