Modular Outlook MCP Server

This is a modular implementation of the Outlook MCP (Model Context Protocol) server that connects Claude with Microsoft Outlook through the Microsoft Graph API.

Credits

This repository is built on the efforts and work of ryaker's outlook-mcp project.

Features

• Authentication: OAuth 2.0 authentication with Microsoft Graph API using PKCE flow
• Automatic Token Refresh: Tokens automatically refresh in the background - no manual re-authentication needed
• Email Management: List, search, read, send, and mark emails as read/unread
• Calendar Management: List, create, accept, decline, and delete calendar events
• Folder Management: List and manage email folders
• Rules Management: Create and manage email rules
• Modular Structure: Clean separation of concerns for better maintainability
• OData Filter Handling: Proper escaping and formatting of OData queries
• Test Mode: Simulated responses for testing without real API calls

Quick Start

Quick Run (No Install)

Step 1: Configure credentials (first time only)

npx outlook-mcp config

Enter your Azure credentials when prompted. They'll be saved to:

• macOS/Linux: ~/.outlook-mcp/config.json
• Windows: %USERPROFILE%\.outlook-mcp\config.json (e.g., C:\Users\YourName\.outlook-mcp\config.json)

Step 2: Authenticate

npx outlook-mcp auth

Browser will automatically open for Microsoft authentication. After successful authentication, tokens are saved to:

• macOS/Linux: ~/.outlook-mcp/tokens.json
• Windows: %USERPROFILE%\.outlook-mcp\tokens.json (e.g., C:\Users\YourName\.outlook-mcp\tokens.json)

Step 3: Test all tools (optional)

npx outlook-mcp test-all-tools

This runs a comprehensive test suite to verify all tools are working correctly.

Available Commands

# Start the MCP server (for use with Claude Desktop)
npx outlook-mcp

# Start the authentication server
npx outlook-mcp auth

# Configure Azure credentials interactively
npx outlook-mcp config

# Test all MCP tools with your stored tokens
npx outlook-mcp test-all-tools

# Show help message
npx outlook-mcp --help

Authentication & Token Management

Initial Authentication

1. Run npx outlook-mcp auth to start the authentication server
2. Your browser will automatically open to Microsoft's login page
3. Sign in and grant permissions
4. Tokens are automatically saved to:
   • macOS/Linux: ~/.outlook-mcp/tokens.json
   • Windows: %USERPROFILE%\.outlook-mcp\tokens.json (e.g., C:\Users\YourName\.outlook-mcp\tokens.json)

Automatic Token Refresh

You only need to authenticate once! The server automatically handles token refresh:

• When an access token expires (typically after 1 hour), the server automatically uses the refresh token to get a new one
• The new token is saved automatically - no user intervention needed
• This happens transparently in the background whenever any tool is called

You'll only need to manually authenticate again if:

• The refresh token expires (typically after 90 days of inactivity)
• The refresh token is revoked (password change, security event, etc.)
• You want to change permissions/scopes
• The token file is deleted

Token Storage

Files are saved in the .outlook-mcp directory in your home folder:

macOS/Linux: ~/.outlook-mcp/

• Config: ~/.outlook-mcp/config.json
• Tokens: ~/.outlook-mcp/tokens.json

Windows: %USERPROFILE%\.outlook-mcp\

• Config: %USERPROFILE%\.outlook-mcp\config.json (e.g., C:\Users\YourName\.outlook-mcp\config.json)
• Tokens: %USERPROFILE%\.outlook-mcp\tokens.json (e.g., C:\Users\YourName\.outlook-mcp\tokens.json)

Contents:

• config.json: Azure credentials (client ID, client secret, test mode setting)
• tokens.json: Access token, refresh token, expiration times, and granted scopes

Security: Never commit these files to version control (they're in .gitignore)

Installation

Prerequisites

• Node.js 14.0.0 or higher
• npm or yarn package manager
• Azure account for app registration

Install Dependencies

npm install

Configuration

Adding to MCP Client

To use this MCP server with an MCP client, you can either use the published npm package or a local installation:

Option 1: Using Published npm Package (Recommended)

To use the current package as-is, use @tgai96/outlook-mcp:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": [
        "-y",
        "@tgai96/outlook-mcp"
      ]
    }
  }
}

To create and publish your own version, replace @tgai96/outlook-mcp with your own package name and follow the Publishing to npm guide below.

Option 2: Using Local Installation

For local development or if the package isn't published yet:

macOS:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": [
        "file:///Users/john/outlook-mcp"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": [
        "file:///C:/Users/john/outlook-mcp"
      ]
    }
  }
}

Linux:

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": [
        "file:///home/john/outlook-mcp"
      ]
    }
  }
}

Note: Replace the path with the actual path to your outlook-mcp directory.

Server Configuration File

Credentials can be stored in:

• macOS/Linux: ~/.outlook-mcp/config.json
• Windows: %USERPROFILE%\.outlook-mcp\config.json (e.g., C:\Users\YourName\.outlook-mcp\config.json)

{
  "MS_CLIENT_ID": "your-client-id-here",
  "MS_CLIENT_SECRET": "your-client-secret-here",
  "USE_TEST_MODE": false
}

Environment Variables

Alternatively, you can use environment variables:

export MS_CLIENT_ID="your-client-id"
export MS_CLIENT_SECRET="your-client-secret"
export USE_TEST_MODE="false"

Priority: Environment variables > Config file > Defaults

Testing Tools

Method 1: Test All Tools (Recommended)

Run the comprehensive test suite:

npx outlook-mcp test-all-tools

This tests all available tools and provides a detailed report.

Method 2: Using MCP Inspector

The MCP Inspector provides an interactive way to test tools:

npm run inspect

This will:

• Start the MCP server
• Open an interactive inspector interface
• Allow you to:
  • List all available tools
  • Call tools with parameters
  • See responses in real-time

Example in Inspector:

> tools/list
> tools/call {"name": "list-emails", "arguments": {"count": 5}}

Available Tools

Authentication Tools

• about - Get server information
• authenticate - Authenticate with Microsoft (auto-refreshes if tokens exist)
• check-auth-status - Check authentication status with human-readable expiration times

Email Tools

• list-emails - List emails from a folder
• search-emails - Search emails with various criteria
• read-email - Read full email content
• send-email - Send a new email
• mark-as-read - Mark email as read or unread

Calendar Tools

• list-events - List calendar events
• create-event - Create a new calendar event
• accept-event - Accept a calendar event
• decline-event - Decline a calendar event
• cancel-event - Cancel a calendar event

Folder Tools

• list-folders - List email folders

Rules Tools

• list-rules - List email rules
• create-rule - Create a new email rule

Directory Structure

outlook-mcp/
├── index.js                 # Main entry point
├── config.js                # Configuration settings
├── cli.js                   # CLI command handler
├── auth/                    # Authentication modules
│   ├── index.js             # Authentication exports
│   ├── token-storage.js     # Token storage and automatic refresh
│   ├── token-manager.js     # Legacy token manager
│   └── tools.js             # Auth-related tools
├── calendar/                # Calendar functionality
│   ├── index.js             # Calendar exports
│   ├── list.js              # List events
│   ├── create.js            # Create event
│   ├── delete.js            # Delete event
│   ├── cancel.js            # Cancel event
│   ├── accept.js            # Accept event
│   └── decline.js           # Decline event
├── email/                   # Email functionality
│   ├── index.js             # Email exports
│   ├── list.js              # List emails
│   ├── search.js            # Search emails
│   ├── read.js              # Read email
│   ├── send.js              # Send email
│   ├── mark-as-read.js      # Mark email as read/unread
│   └── folder-utils.js     # Folder path resolution
├── folder/                  # Folder management
│   ├── index.js             # Folder exports
│   └── list.js              # List folders
├── rules/                   # Rules management
│   ├── index.js             # Rules exports
│   ├── list.js              # List rules
│   └── create.js            # Create rule
└── utils/                   # Utility functions
    ├── graph-api.js         # Microsoft Graph API helper
    ├── odata-helpers.js     # OData query building
    └── mock-data.js         # Test mode data

Troubleshooting

Token Refresh Issues

If you see "Access is denied" errors:

1. Check that your token includes Mail.ReadWrite scope (required for marking emails as read)
2. Re-authenticate:
   • macOS/Linux: rm ~/.outlook-mcp/tokens.json && npx outlook-mcp auth
   • Windows: del %USERPROFILE%\.outlook-mcp\tokens.json && npx outlook-mcp auth
3. Verify scopes in your tokens file include all needed permissions:
   • macOS/Linux: ~/.outlook-mcp/tokens.json
   • Windows: %USERPROFILE%\.outlook-mcp\tokens.json

Authentication Errors

• "MS_CLIENT_ID is not configured": Run npx outlook-mcp config or set environment variables
• "Token file not found": Run npx outlook-mcp auth to authenticate
• "Access is denied": Check Azure app permissions and re-authenticate

Search Errors

• "$orderBy is not supported with $search": This is fixed - the server now handles this correctly
• Search results are returned in relevance order (Microsoft Graph default) when using $search

Publishing to npm

To publish this package to npm under your own namespace:

1. Update package.json metadata:

   • Update the name field to your desired package name (e.g., @your-username/outlook-mcp or outlook-mcp)
   • Update the author field with your name/username
   • Optionally add repository, bugs, and homepage fields if you have a GitHub repo
   • Update the version field (following semantic versioning)

2. Login to npm:

   npm login

   Enter your npm username, password, and email when prompted.

3. Verify what will be published (recommended):

   npm pack --dry-run

   This shows which files will be included in the package (based on the files field in package.json).

4. Publish to npm:

   For scoped packages (packages starting with @username/), use:

   npm publish --access public

5. After publishing, users can use it in their MCP client configuration:

   {
     "mcpServers": {
       "outlook": {
         "command": "npx",
         "args": [
           "-y",
           "@your-username/outlook-mcp"
         ]
       }
     }
   }

   Replace @your-username/outlook-mcp with your actual published package name.

Note: Make sure to review the files field in package.json to ensure only necessary files are published (sensitive files, test files, and development scripts should be excluded).

License

MIT