outlook-mcp 0.1.0
MCP server for Microsoft Outlook integration to manage emails, calendar events, and contacts
License: MIT
Requires Python: >=3.12
Keywords: ai, assistant, calendar, contacts, email, graph, mcp, microsoft, outlook

# 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

```bash
# 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](https://portal.azure.com) → 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:

```bash
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)

```bash
pip install outlook-mcp
```

### Install from Source

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

## Quickstart

### 1. Configure Environment

Set up your environment variables in `.env`:

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

### 2. Test the Server

```bash
# 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`

```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)

```json
{
  "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

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

# Send an email
await send_email(
    to="recipient@example.com",
    subject="Hello from MCP",
    body="This email was sent through the MCP server!"
)
```

### Calendar Operations

```python
# 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=["team@example.com"]
)
```

### Contact Operations

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

# Create a contact
await create_contact(
    display_name="John Doe",
    email="john.doe@example.com",
    phone="+1-555-123-4567"
)
```

## 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:

```bash
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:

```bash
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:
```bash
uv sync
```

2. Build package distributions:
```bash
uv build
```

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

3. Publish to PyPI:
```bash
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](https://github.com/modelcontextprotocol/inspector).


You can launch the MCP Inspector via [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:

```bash
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.