Give Claude full access to your Outlook email, calendar, and contacts.

A Model Context Protocol (MCP) server that connects Claude and other AI assistants with Microsoft Outlook through the Microsoft Graph API. 20 consolidated tools across 9 modules for managing email, calendar, contacts, folders, rules, categories, settings, and more.

Outlook MCP is designed with safety-first principles for AI-driven email access:

Destructive action safeguards — Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so AI clients can auto-approve safe reads and prompt for confirmation on destructive operations like sending email or deleting events.

Send-email protections — The send-email tool includes:

• Dry-run mode (dryRun: true) — preview composed emails without sending
• Session rate limiting — configurable via OUTLOOK_MAX_EMAILS_PER_SESSION (default: unlimited)
• Recipient allowlist — restrict sending to approved addresses/domains via OUTLOOK_ALLOWED_RECIPIENTS

Token-optimised architecture — Tools are consolidated using the STRAP (Single Tool, Resource, Action Pattern) approach. 20 tools instead of 55 reduces per-turn overhead by ~11,000 tokens (~64%), keeping more of the AI's context window available for your actual conversation. Fewer tools also means the AI selects the right tool more accurately — research shows tool selection degrades beyond ~40 tools.

Important: These safeguards are defence-in-depth measures that reduce risk, but they are not a guarantee against unintended actions. AI-driven access to your email is inherently sensitive — always review tool calls before approving, particularly for sends and deletes. No automated guardrail is foolproof, and you remain responsible for actions taken through your mailbox.

npm install -g @littlebearapps/outlook-mcp

Or run directly without installing:

npx @littlebearapps/outlook-mcp

You need a Microsoft Azure app registration to authenticate. See the Azure Setup Guide for a detailed walkthrough (including first-time Azure account creation), or if you've done this before:

1. Create a new app registration at portal.azure.com
2. Set redirect URI to http://localhost:3333/auth/callback
3. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)
4. Create a client secret and copy the Value (not the Secret ID)

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-mcp"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

1. Start the auth server: outlook-mcp-auth (or npx @littlebearapps/outlook-mcp-auth)
2. In Claude, use the auth tool with action=authenticate to get an OAuth URL
3. Open the URL, sign in with your Microsoft account, and grant permissions
4. Tokens are saved locally and refresh automatically

20 tools total — consolidated from 55 for optimal AI performance. See the Tools Reference for complete parameter details.

Export emails and conversations to multiple formats:

• Node.js 18.0.0 or higher
• npm (included with Node.js)
• Azure account for app registration (free tier works)

npm install -g @littlebearapps/outlook-mcp

git clone https://github.com/littlebearapps/outlook-mcp.git
cd outlook-mcp
npm install

First time with Azure? The Azure Setup Guide covers everything from creating an account to your first authentication, including billing setup and common pitfalls.

1. Open Azure Portal
2. Sign in with a Microsoft Work or Personal account
3. Search for App registrations and click New registration
4. Enter a name (e.g. "Outlook MCP Server")
5. Select Accounts in any organizational directory and personal Microsoft accounts
6. Set redirect URI: platform Web, URI http://localhost:3333/auth/callback
7. Click Register
8. Copy the Application (client) ID

1. Go to API permissions > Add a permission > Microsoft Graph > Delegated permissions
2. Add these permissions:
   • offline_access
   • User.Read
   • Mail.Read, Mail.ReadWrite, Mail.Send
   • Mail.Read.Shared (for shared mailbox access)
   • Calendars.Read, Calendars.ReadWrite
   • Contacts.Read, Contacts.ReadWrite
   • MailboxSettings.Read, MailboxSettings.ReadWrite
   • People.Read (for people search)
   • Place.Read.All (for meeting room search)
3. Click Add permissions

1. Go to Certificates & secrets > New client secret
2. Enter a description and select expiration
3. Click Add
4. Copy the secret Value immediately — you won't be able to see it again. Use the Value, not the Secret ID.

Create a .env file from the example:

cp .env.example .env

Edit with your Azure credentials:

OUTLOOK_CLIENT_ID=your-application-client-id
OUTLOOK_CLIENT_SECRET=your-client-secret-VALUE
USE_TEST_MODE=false

Note: The server also accepts MS_CLIENT_ID and MS_CLIENT_SECRET for backwards compatibility.

Add to your Claude Desktop config:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-mcp"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/path/to/outlook-mcp/index.js"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

npm run auth-server

This starts a local server on port 3333 to handle the OAuth callback.

1. In Claude, use the auth tool with action=authenticate
2. Open the provided URL in your browser
3. Sign in with your Microsoft account and grant permissions
4. Tokens are saved to ~/.outlook-mcp-tokens.json and refresh automatically

outlook-mcp/
├── index.js                 # Main entry point (20 tools)
├── config.js                # Configuration settings
├── outlook-auth-server.js   # OAuth server (port 3333)
├── auth/                    # Authentication module (1 tool)
├── email/                   # Email module (6 tools)
│   ├── headers.js           # Email header retrieval
│   ├── mime.js              # Raw MIME/EML content
│   ├── conversations.js     # Thread listing/export
│   ├── attachments.js       # Attachment operations
│   └── ...
├── calendar/                # Calendar module (3 tools)
├── contacts/                # Contacts module (2 tools)
├── categories/              # Categories module (3 tools)
├── settings/                # Settings module (1 tool)
├── folder/                  # Folder module (1 tool)
├── rules/                   # Rules module (1 tool)
├── advanced/                # Advanced module (2 tools)
└── utils/
    ├── graph-api.js         # Microsoft Graph API client
    ├── safety.js            # Rate limiting, recipient allowlist, dry-run
    ├── odata-helpers.js     # OData query building
    ├── field-presets.js     # Token-efficient field selections
    ├── response-formatter.js # Verbosity levels
    └── mock-data.js         # Test mode data

npm install

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 and copy the Value column.

Start the auth server first: npm run auth-server

Check authentication status with the auth tool (action=status). Tokens may have expired — re-authenticate if needed.

npm test                     # Jest unit tests
npm run inspect              # MCP Inspector (interactive)

Run with mock data (no real API calls):

USE_TEST_MODE=true npm start

1. Create a new module directory (e.g. tasks/)
2. Implement tool handlers in separate files
3. Export tool definitions from the module's index.js
4. Import and add tools to the TOOLS array in main index.js
5. Add tests in test/
6. Update docs/quickrefs/tools-reference.md

Full documentation: docs/

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

For security concerns, please see our Security Policy. Do not open public issues for vulnerabilities.

See CHANGELOG.md for version history.

Built and maintained by Little Bear Apps. Outlook MCP is open source under the MIT License.