Simple Outlook MCP Server

Simple Outlook MCP Server

A clean, functional Model Context Protocol (MCP) server for Microsoft Outlook integration with Claude.

Features

• ✅ Send Emails - Send emails through your Outlook account
• ✅ List Emails - Retrieve emails from your inbox or other folders
• ✅ Search Emails - Search emails by criteria (sender, date, content)
• ✅ Read Emails - Get full email content by ID
• ✅ OAuth Authentication - Secure Microsoft Graph API authentication
• ✅ Simple Setup - Minimal configuration required

Prerequisites

1. Node.js (v18 or higher)
2. Microsoft Azure App Registration (for Graph API access)

Setup

1. Install Dependencies

cd /Users/ricardozhang/Desktop/AI_Agents/simple-outlook-mcp
npm install

2. Create Microsoft Azure App Registration

1. Go to Azure Portal
2. Navigate to Azure Active Directory > App registrations
3. Click New registration
4. Fill in:

• Name: Claude Outlook MCP
• Supported account types: Accounts in any organizational directory and personal Microsoft accounts
• Redirect URI: Web - http://localhost:3000/auth/callback

1. Click Register
2. Note down the Application (client) ID and Directory (tenant) ID
3. Go to Certificates & secrets > New client secret
4. Create a secret and note down the Value
5. Go to API permissions > Add a permission > Microsoft Graph > Delegated permissions
6. Add these permissions:

• Mail.ReadWrite
• Mail.Send

1. Click Grant admin consent (if you're an admin)

3. Configure Environment Variables

cp .env.example .env

Edit .env with your Azure app details:

MICROSOFT_CLIENT_ID=your_client_id_here
MICROSOFT_CLIENT_SECRET=your_client_secret_here
MICROSOFT_TENANT_ID=your_tenant_id_here

4. Build the Project

npm run build

Usage

1. Start the MCP Server

npm start

2. Available Tools

authenticate_outlook

Start the OAuth flow to authenticate with Microsoft Graph API.

send_email

Send an email through Outlook.

• to: Recipient email address (required)
• subject: Email subject (required)
• body: Email body content (required)
• cc: CC recipients (optional)
• bcc: BCC recipients (optional)

list_emails

List recent emails from your inbox.

• limit: Number of emails to retrieve (default: 10)
• folder: Folder to search in (default: "inbox")

search_emails

Search emails by criteria.

• query: Search query string
• from: Filter by sender email
• date_from: Filter emails from this date (YYYY-MM-DD)
• date_to: Filter emails until this date (YYYY-MM-DD)
• limit: Number of emails to retrieve (default: 10)

read_email

Read a specific email by ID.

• email_id: Email message ID (required)

Integration with Claude Desktop

Add this server to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "simple-outlook-mcp": {
      "command": "node",
      "args": ["/Users/ricardozhang/Desktop/AI_Agents/simple-outlook-mcp/build/index.js"],
      "env": {
        "MICROSOFT_CLIENT_ID": "your_client_id",
        "MICROSOFT_CLIENT_SECRET": "your_client_secret",
        "MICROSOFT_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

Example Usage with Claude

1. Authenticate:

   Please authenticate with Outlook

1. Send an email:

   Send an email to john@example.com with subject "Meeting Tomorrow" and body "Hi John, let's meet at 2 PM tomorrow."

1. List recent emails:

   Show me my last 5 emails

1. Search emails:

   Find emails from alice@example.com from the last week

Troubleshooting

Authentication Issues

• Ensure your Azure app has the correct permissions
• Check that the redirect URI matches exactly: http://localhost:3000/auth/callback
• Verify your client ID, secret, and tenant ID are correct

Build Issues

• Make sure you're using Node.js v18 or higher
• Run npm install to ensure all dependencies are installed
• Check that TypeScript compiles without errors: npm run build

Permission Issues

• Ensure the Azure app has Mail.ReadWrite and Mail.Send permissions
• Admin consent may be required for organizational accounts

Development

# Watch mode for development
npm run watch

# Build only
npm run build

# Start after build
npm start

License

MIT License - see LICENSE file for details.