outlook-mcp by peacockery-studio - MCP Server

Modular Outlook MCP Server

A modular MCP (Model Context Protocol) server that connects Claude with Microsoft Outlook through the Microsoft Graph API using app-only (client credentials) authentication — no browser sign-in required.

Certified by MCPHub

Directory Structure

├── index.ts                 # Main entry point
├── config.ts                # Configuration settings
├── types.ts                 # Shared TypeScript type definitions
├── auth/                    # Authentication modules
│   ├── index.ts             # Authentication exports
│   ├── token-manager.ts     # Token management (client credentials)
│   └── tools.ts             # Auth-related tools
├── calendar/                # Calendar functionality
│   ├── index.ts             # Calendar exports and tool schemas
│   ├── types.ts             # Calendar type definitions
│   ├── list.ts              # List events (calendarView)
│   ├── create.ts            # Create event
│   ├── delete.ts            # Delete event
│   ├── cancel.ts            # Cancel event
│   ├── accept.ts            # Accept event
│   └── decline.ts           # Decline event
├── config/                  # Configuration modules
│   └── mailbox-permissions.ts  # Mailbox permission restrictions
├── email/                   # Email functionality
│   ├── index.ts             # Email exports and tool schemas
│   ├── folder-utils.ts      # Folder resolution utilities
│   ├── list.ts              # List emails
│   ├── search.ts            # Search emails
│   ├── read.ts              # Read email
│   ├── send.ts              # Send email
│   ├── mark-as-read.ts      # Mark as read/unread
│   ├── categories.ts        # Email categories management
│   └── archive-delete.ts    # Archive and delete emails
├── folder/                  # Folder management
│   ├── index.ts             # Folder exports and tool schemas
│   ├── list.ts              # List folders
│   ├── create.ts            # Create folder
│   └── move.ts              # Move emails between folders
├── rules/                   # Inbox rules
│   ├── index.ts             # Rules exports and tool schemas
│   ├── list.ts              # List rules
│   └── create.ts            # Create rule
├── tests/                   # Test suite
│   ├── mailbox-permissions.test.ts
│   ├── tool-schemas.test.ts
│   ├── error-responses.test.ts
│   └── mock-mode.test.ts
└── utils/                   # Utility functions
    ├── graph-api.ts         # Microsoft Graph API helper
    └── mock-data.ts         # Test mode data

Features

App-only Authentication: Uses client credentials flow — no browser sign-in or user interaction required
Email Management: List, search, read, send, mark as read
Categories Management: Get master categories and set categories on emails
Archive & Delete: Archive emails to archive folder, soft/hard delete
Calendar Management: List upcoming events (recurring-aware), create, accept, decline, cancel, delete
Folder Management: List, create, move emails between folders
Inbox Rules: List, create, reorder rules
Mailbox Permission Restrictions: Configurable per-mailbox access control
Multi-mailbox: Access multiple mailboxes via the mailbox parameter on each tool
Test Mode: Simulated responses for testing without real API calls
TypeScript: Fully typed codebase with strict mode

Quick Start

Install dependencies: bun install
Azure setup: Register app in Azure Portal with Application permissions (see below)
Configure environment: Copy .env.example to .env and add your Azure credentials
Configure Claude: Update your Claude Desktop config with the server path
Start using: No auth server needed — credentials are loaded automatically from env

Installation

Prerequisites

Bun runtime — fast JavaScript/TypeScript runtime
Azure account for app registration

bun install

Bun natively supports TypeScript and auto-loads .env files, so no additional tooling is needed.

Azure App Registration & Configuration

This server uses app-only (client credentials) authentication. The app acts on behalf of your organization, not on behalf of a specific signed-in user. This requires admin consent for Application permissions.

1. App Registration

Open Azure Portal
Go to App registrations → New registration
Enter a name (e.g., "Outlook MCP Server")
Select Accounts in this organizational directory only (single tenant)
No redirect URI needed — client credentials flow has no browser redirect
Click Register
Copy the Application (client) ID → this is your MS_CLIENT_ID
Copy the Directory (tenant) ID from the Overview page → this is your MS_TENANT_ID

2. Application Permissions

⚠️ These are Application permissions (not Delegated). They require admin consent.

Go to API permissions → Add a permission → Microsoft Graph → Application permissions
Add the following permissions:

Permission	Purpose
`Mail.Read`	Read emails
`Mail.ReadWrite`	Move, archive, update emails
`Mail.Send`	Send emails
`Calendars.ReadWrite`	Read and modify calendar events
`MailboxSettings.ReadWrite`	Read and manage inbox rules

Click Add permissions
Click Grant admin consent for [your organization] — this is required for Application permissions

3. Client Secret

Go to Certificates & secrets → Client secrets → New client secret
Enter a description and select the longest expiration available
Click Add
⚠️ Copy the secret Value (not the Secret ID) immediately — it won't be shown again

Configuration

Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit .env:

MS_TENANT_ID=your-directory-tenant-id-here
MS_CLIENT_ID=your-application-client-id-here
MS_CLIENT_SECRET=your-client-secret-VALUE-here
USE_TEST_MODE=false

Important: Use the secret Value, not the Secret ID.

Claude Desktop Configuration

Copy from claude-config-sample.json and update paths and credentials:

{
  "mcpServers": {
    "outlook-assistant": {
      "command": "bun",
      "args": [
        "/absolute/path/to/outlook-mcp/index.ts"
      ],
      "env": {
        "USE_TEST_MODE": "false",
        "OUTLOOK_TENANT_ID": "your-tenant-id-here",
        "OUTLOOK_CLIENT_ID": "your-client-id-here",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

Authentication Flow

No browser sign-in or auth server is required. The server automatically fetches an access token using your app credentials when needed:

Claude starts the MCP server
Server reads MS_TENANT_ID, MS_CLIENT_ID, MS_CLIENT_SECRET from environment
On first API call, a token is fetched via POST /oauth2/v2.0/token (client credentials)
Token is cached in memory and refreshed automatically when it expires

You can verify credentials are working using the authenticate tool in Claude.

Mailbox Parameter

All tools that access Outlook data require a mailbox parameter specifying which mailbox to operate on (e.g., chi@desertservices.net). This is how the server knows which user's data to access in app-only mode.

Example: "List my last 10 emails from chi@desertservices.net"

Mailbox Permissions

Write operations (send, archive, delete, create/modify rules, move emails, create events) are restricted to specific mailboxes to prevent accidental modifications.

Allowed Mailboxes (Full Access)

Configured in config/mailbox-permissions.ts:

contracts@desertservices.net
chi@desertservices.net
dustpermits@desertservices.net

All other mailboxes are read-only. Attempting write operations from an unlisted mailbox returns an error.

Development

bun run start        # Start the MCP server
bun test             # Run tests (114 pass)
bun run typecheck    # TypeScript type checking
bun run lint         # Check formatting (Biome/Ultracite)
bun run lint:fix     # Auto-fix formatting
bun run inspect      # Open MCP Inspector for interactive testing

Test Mode

USE_TEST_MODE=true bun run start           # Start with mock data
USE_TEST_MODE=true bun test tests/mock-mode.test.ts  # Run integration tests

Troubleshooting

Authentication Errors

"Missing credentials" on startup

Set all three env vars: MS_TENANT_ID, MS_CLIENT_ID, MS_CLIENT_SECRET

"Invalid client secret" (AADSTS7000215)

You used the Secret ID instead of the Secret Value. Go to Azure Portal → Certificates & secrets and copy the Value column.

403 Forbidden on API calls

Admin consent has not been granted for Application permissions. Go to Azure Portal → API permissions → Grant admin consent.

403 on rules operations

Ensure MailboxSettings.ReadWrite Application permission is granted (not just Mail.ReadWrite).

"Sending is not allowed from this mailbox"

The mailbox is not in the canSend list in config/mailbox-permissions.ts. Add it or use an allowed mailbox.

API Errors

"cpim_sts_Unsupported_endpoint"

You have a stale version of the server — this error means me/ endpoints were used. Update to the latest version.

400 on search with attachments filter

This was a known bug in older versions — $search and $filter cannot be combined. Fixed in v2.1.0.

Extending the Server

Create new module directories (e.g., contacts/)
Implement tool handlers in separate .ts files with proper TypeScript types
Export tool definitions from module index.ts files
Import and add tools to TOOLS array in index.ts
Add any shared types to types.ts at the project root
Include a mailbox required parameter in all tool schemas that make API calls