outlook-mcp 0.1.0

MCP server for Microsoft Outlook integration to manage emails, calendar events, and contacts

Outlook MCP Server

Model Context Protocol (MCP) server for Microsoft Outlook integration that enables AI assistants to interact with emails, calendar events, and contacts through Microsoft Graph API.

Features

• Email Management: Read, send, and manage emails
• Calendar Operations: View and create calendar events
• Contact Management: Access and create contacts
• Real-time Integration: Direct connection to Microsoft Graph API
• Secure Authentication: Azure AD authentication support

Components

Resources

The server provides access to Outlook data through custom URI schemes:

• email://: Access email messages with metadata and content
• calendar://: Access calendar events with details and attendees
• contact://: Access contact information and details

Each resource provides structured data in JSON format with appropriate metadata.

Tools

The server implements six powerful tools for Outlook integration:

Email Tools

• get-emails: Retrieve emails from specified folder (inbox, sent, drafts, etc.)

  • Parameters: folder (optional, defaults to "inbox"), limit (optional, defaults to 10)
  • Returns: List of emails with subject, sender, date, and preview

• send-email: Send a new email message

  • Parameters: to (required), subject (required), body (required), cc (optional), bcc (optional)
  • Returns: Confirmation with message ID

Calendar Tools

• get-calendar-events: Retrieve calendar events for a date range

  • Parameters: start_date (optional), end_date (optional), limit (optional, defaults to 20)
  • Returns: List of events with title, time, location, and attendees

• create-calendar-event: Create a new calendar event

  • Parameters: subject (required), start_time (required), end_time (required), location (optional), attendees (optional), body (optional)
  • Returns: Confirmation with event ID

Contact Tools

• get-contacts: Retrieve contacts from address book

  • Parameters: limit (optional, defaults to 50)
  • Returns: List of contacts with name, email, and phone information

• create-contact: Create a new contact

  • Parameters: display_name (required), email (optional), phone (optional), company (optional)
  • Returns: Confirmation with contact ID

Prompts

The server provides three AI-powered prompts for enhanced productivity:

• summarize-emails: Generate intelligent email summaries

  • Analyzes recent emails and creates structured summaries
  • Identifies action items, important information, and priorities

• schedule-summary: Create calendar overviews

  • Summarizes upcoming meetings and events
  • Provides scheduling insights and conflict detection

• compose-email: AI-assisted email composition

  • Helps draft professional emails with proper tone
  • Suggests improvements and formatting

Configuration

The server requires Azure AD app registration and configuration through environment variables:

Required Environment Variables

# Azure AD Configuration
OUTLOOK_TENANT_ID=your-tenant-id
OUTLOOK_CLIENT_ID=your-client-id

# Choose one authentication method:
# Option 1: Client Secret (App-only authentication)
OUTLOOK_CLIENT_SECRET=your-client-secret

# Option 2: Username/Password (Delegated authentication)  
OUTLOOK_USERNAME=your-username
OUTLOOK_PASSWORD=your-password

Azure AD App Registration

1. Go to Azure Portal → Azure Active Directory → App registrations

2. Create a new registration with these settings:

   • Name: Outlook MCP Server
   • Supported account types: Accounts in this organizational directory only
   • Redirect URI: Not required for this server type

3. Configure API permissions:

   • Microsoft Graph → Application permissions (for client secret auth):
     • Mail.Read, Mail.Send, Calendars.Read, Calendars.ReadWrite, Contacts.Read, Contacts.ReadWrite
   • Microsoft Graph → Delegated permissions (for username/password auth):
     • Mail.Read, Mail.Send, Calendars.Read, Calendars.ReadWrite, Contacts.Read, Contacts.ReadWrite

4. Grant admin consent for the permissions

5. Create a client secret (if using client secret authentication)

Configuration File

Create a .env file in the project root:

cp .env.example .env
# Edit .env with your Azure AD credentials

Installation & Setup

Prerequisites

• Python 3.8 or higher
• Microsoft 365 or Outlook.com account
• Azure AD app registration (see Configuration section)

Install from PyPI (when published)

pip install outlook-mcp

Install from Source

git clone <repository-url>
cd outlook-mcp
uv sync

Quickstart

1. Configure Environment

Set up your environment variables in .env:

OUTLOOK_TENANT_ID=your-tenant-id
OUTLOOK_CLIENT_ID=your-client-id
OUTLOOK_CLIENT_SECRET=your-client-secret

2. Test the Server

# Run the server directly for testing
uv run outlook-mcp

# Or test with MCP Inspector
npm install -g @modelcontextprotocol/inspector
mcp-inspector uv run outlook-mcp

3. Configure with Claude Desktop

Development Configuration

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "outlook-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/annmariyajoshy/vibecoding/outlook-mcp",
        "run",
        "outlook-mcp"
      ],
      "env": {
        "OUTLOOK_TENANT_ID": "your-tenant-id",
        "OUTLOOK_CLIENT_ID": "your-client-id", 
        "OUTLOOK_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Production Configuration (when published)

{
  "mcpServers": {
    "outlook-mcp": {
      "command": "uvx",
      "args": ["outlook-mcp"],
      "env": {
        "OUTLOOK_TENANT_ID": "your-tenant-id",
        "OUTLOOK_CLIENT_ID": "your-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Usage Examples

Email Operations

# Get recent emails
emails = await get_emails(folder="inbox", limit=5)

# Send an email
await send_email(
    to="[e-mail]",
    subject="Hello from MCP",
    body="This email was sent through the MCP server!"
)

Calendar Operations

# Get upcoming events
events = await get_calendar_events(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

# Create a meeting
await create_calendar_event(
    subject="Team Standup",
    start_time="2024-01-15T09:00:00",
    end_time="2024-01-15T09:30:00",
    attendees=["[e-mail]"]
)

Contact Operations

# Get contacts
contacts = await get_contacts(limit=10)

# Create a contact
await create_contact(
    display_name="John Doe",
    email="[e-mail]",
    phone="[phone]"
)

Error Handling

The server includes comprehensive error handling for common scenarios:

• Authentication failures: Clear error messages for expired tokens or invalid credentials
• Permission errors: Helpful guidance when API permissions are insufficient
• Rate limiting: Automatic retry logic with exponential backoff
• Network issues: Graceful degradation and error reporting

Security Considerations

• Credential Storage: Never commit credentials to version control
• Token Management: Tokens are handled securely by Azure Identity library
• Scope Limitation: Request only necessary permissions for your use case
• Network Security: All communication uses HTTPS with Microsoft Graph API

Troubleshooting

Common Issues

1. Authentication Error: Verify your tenant ID, client ID, and credentials
2. Permission Denied: Check that required permissions are granted and admin consented
3. Module Not Found: Ensure all dependencies are installed with uv sync
4. Rate Limiting: Implement delays between requests if hitting API limits

Debug Mode

Enable detailed logging:

export PYTHONPATH=/path/to/outlook-mcp/src
export MCP_LOG_LEVEL=DEBUG
uv run outlook-mcp

MCP Inspector

For advanced debugging, use the MCP Inspector:

npm install -g @modelcontextprotocol/inspector
mcp-inspector uv run outlook-mcp

Development

Building and Publishing

To prepare the package for distribution:

1. Sync dependencies and update lockfile:

uv sync

2. Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /Users/annmariyajoshy/vibecoding/outlook-mcp run outlook-mcp

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.