# Outlook MCP

An MCP server that connects GitHub Copilot and other AI agents to Microsoft Outlook via the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview).

## Features

| Tool | Description |
|---|---|
| `list_emails` | List emails from any folder with filtering, sorting, and pagination |
| `read_email` | Read a full email (body + metadata) or its internet headers |
| `search_emails` | Search the mailbox using KQL queries |
| `list_folders` | List all mail folders, optionally including sub-folders |
| `list_attachments` | List attachments on a specific email |
| `send_email` | Send a new email (plain text or HTML, CC, BCC, importance) |
| `reply_email` | Reply or reply-all to an email |
| `move_email` | Move an email to a different folder |

## Requirements

- Python 3.12+
- A Microsoft 365 account with Outlook
- A Microsoft Graph API bearer token with `Mail.Read`, `Mail.Send`, and `Mail.ReadWrite` scopes

## Quick Start

```powershell
# 1. Clone the repository
git clone https://github.com/your-org/outlook-mcp.git
cd outlook-mcp

# 2. Create a virtual environment and install dependencies
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# 3. Run setup to configure VS Code
.\setup.ps1
```

## Configuration

The server reads these environment variables:

| Variable | Required | Description |
|---|---|---|
| `OUTLOOK_TOKEN` | **Yes** | Microsoft Graph API bearer token |
| `OUTLOOK_PROXY` | No | Corporate HTTP proxy URL |
| `OUTLOOK_VERIFY_SSL` | No | Set `true` to verify SSL certificates (default: `false`) |

### Getting an OUTLOOK_TOKEN

**For development / testing** — use [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer):
1. Sign in with your Microsoft 365 account.
2. Click **Access token** in the top panel.
3. Copy the token.

**For production** — register an Entra ID application with delegated permissions (`Mail.Read`, `Mail.Send`, `Mail.ReadWrite`) and implement OAuth 2.0 to obtain tokens programmatically.

## Running manually

```bash
export OUTLOOK_TOKEN=your_token_here
python server.py
```

## Docker

```bash
docker build -t outlook-mcp .
docker run -e OUTLOOK_TOKEN=your_token_here outlook-mcp
```

## VS Code MCP configuration

`.vscode/mcp.json` (generated by `setup.ps1`):

```json
{
  "servers": {
    "outlook-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["server.py"],
      "env": {
        "OUTLOOK_TOKEN": "your_token_here"
      }
    }
  }
}
```

## License

MIT