MCP Email Server (Beta)

A Model Context Protocol (MCP) server for Microsoft 365/Outlook email and calendar integration. This beta version enables Claude to read emails, draft responses, search for attachments, and manage calendar events through Microsoft Graph API.

Beta Status

This is a beta release. While functional, it may have:

• Incomplete features
• Breaking changes in future updates
• Need for additional error handling
• Areas for performance optimization

Please report any issues or suggestions through the repository's issue tracker.

Features

• Read emails from any Outlook folder
• Draft email responses
• Search email content
• Manage calendar events and meetings
• Integrate with filesystem MCP for attachments

Installation

For Users

The server is automatically managed by Claude Desktop through the configuration. You don't need to run it manually.

# The package will be installed and run automatically by Claude Desktop
# You only need to set up the configuration directory and credentials

For Development

# Clone the repository
git clone [repository-url]
cd email-server

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
node build/index.js

Setup

1. Register an Azure AD Application:

   • Go to Azure Portal
   • Navigate to Azure Active Directory > App registrations
   • Create a new registration
   • Add Microsoft Graph API permissions:
     • Mail.ReadWrite
     • Mail.Send
     • Calendars.ReadWrite
     • User.Read

2. Get Credentials:

   • Copy Application (client) ID
   • Generate a new client secret
   • Copy Directory (tenant) ID

3. Create Configuration Directory and .env File:

# Create a directory in your home folder
mkdir ~/email-config  # Mac/Linux
mkdir %USERPROFILE%\email-config  # Windows

# Navigate to the directory
cd ~/email-config  # Mac/Linux
cd %USERPROFILE%\email-config  # Windows

# Create .env file
touch .env  # Mac/Linux
copy nul .env  # Windows

# Add your credentials to .env:
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
TENANT_ID=your_tenant_id

4. Generate Access Token:

# Make sure you're in the email-config directory
cd ~/email-config  # Mac/Linux
cd %USERPROFILE%\email-config  # Windows

# Generate token (this will use credentials from your .env file)
npx @disocodes/server-email-beta/get-token.js

# The token will be displayed in the terminal - copy it for the next step

5. Configure Claude Desktop:

# Configuration file location:
# Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# Linux: ~/.config/Claude/claude_desktop_config.json

# Add this to your configuration:
{
  "mcpServers": {
    "email": {
      "command": "npx",
      "args": ["-y", "@disocodes/server-email-beta"],
      "env": {
        "MS_ACCESS_TOKEN": "token_from_get_token",
        "MS_EMAIL": "[email protected]"
      }
    }
  }
}

Token Management

The access token expires periodically (usually after 1 hour). When it expires:

1. Generate a new token:

# Navigate to your config directory
cd ~/email-config  # Mac/Linux
cd %USERPROFILE%\email-config  # Windows

# Generate new token
npx @disocodes/server-email-beta/get-token.js

# Copy the new token displayed in the terminal

2. Update the MS_ACCESS_TOKEN in your Claude Desktop configuration
3. Restart Claude Desktop

Usage

Example commands in Claude:

• "Show my recent emails"
• "Search emails about project updates"
• "Draft a response to the latest email"
• "Schedule a meeting for tomorrow"
• "Find and attach the budget report"

Security

• Never share your client secret or access tokens
• Store credentials securely in .env file
• Regularly rotate client secrets
• Keep access tokens private
• Monitor Azure AD application activity

Beta Feedback

We welcome your feedback on this beta release! Please:

• Report bugs through GitHub issues
• Suggest features or improvements
• Share your experience using the server
• Help us improve documentation

License

MIT

Contributing

Contributions welcome! Please read our Contributing Guide for details.