# Microsoft Outlook MCP Server

MCP server for Microsoft Outlook — search, send, and manage mail and calendar with browser-session auth; no Azure AD app registration.

Clone the repo, build it, point your AI tool at `dist/index.js`. Uses the same OWA REST API that Outlook Web App calls internally. Auth is your normal Outlook browser login; access matches what your account can already do.

## Prerequisites

- Node.js 18+
- Microsoft 365 / Outlook.com account
- Chrome (macOS/Linux) or Edge (Windows)

## Setup

```bash
git clone https://github.com/hickeroar/outlook-mcp.git
cd outlook-mcp
npm install
npm run build
```

Register as a local stdio MCP server:

```json
{
  "mcpServers": {
    "Outlook": {
      "command": "node",
      "args": ["/absolute/path/to/outlook-mcp/dist/index.js"]
    }
  }
}
```

Session files: `~/.outlook-mcp-server/` (macOS/Linux) or `%APPDATA%\outlook-mcp-server\` (Windows).

### First login

Call `outlook_login` (use `forceNew: true` if session is dead). Browser opens for Microsoft sign-in. After that, tools use cached OWA tokens with automatic refresh.

## Commands

```bash
npm run build
npm run typecheck
npm run cli -- status
npm run cli -- login
npm run cli -- inbox
npm run cli -- search "quarterly report"
npm run cli -- calendar
```

## MCP Resources

| URI | Description |
|-----|-------------|
| `outlook://me/profile` | Signed-in user profile |
| `outlook://status` | Token and session status |
| `outlook://me/inbox` | Recent inbox messages (last 10) |

## Tools

### Authentication

| Tool | Description |
|------|-------------|
| `outlook_login` | Login via browser (headless SSO first) |
| `outlook_status` | Auth and token diagnostics |

### Mail

| Tool | Description |
|------|-------------|
| `outlook_list_folders` | List mail folders |
| `outlook_list_messages` | List messages in a folder |
| `outlook_search_messages` | Search mail by keyword |
| `outlook_get_message` | Get full message by ID |
| `outlook_send_message` | Send email immediately |
| `outlook_create_draft` | Create draft without sending |
| `outlook_create_reply_draft` | Create reply draft (set `send=true` to send) |
| `outlook_create_reply_all_draft` | Create reply-all draft |
| `outlook_create_forward_draft` | Create forward draft |
| `outlook_update_message` | Update draft or message properties |
| `outlook_add_attachment` | Attach a local file to a draft/message (does not send) |
| `outlook_mark_read` | Mark read/unread |
| `outlook_send_draft` | Send existing draft |
| `outlook_move_message` | Move to another folder |
| `outlook_delete_message` | Delete (moves to Deleted Items) |

### Calendar

| Tool | Description |
|------|-------------|
| `outlook_list_calendars` | List calendars |
| `outlook_get_calendar_view` | Events in date range |
| `outlook_get_event` | Single event by ID |
| `outlook_create_event` | Create event |
| `outlook_update_event` | Update event |
| `outlook_delete_event` | Delete event |
| `outlook_cancel_event` | Cancel meeting (organiser) |
| `outlook_respond_event` | Accept/decline/tentative RSVP |
| `outlook_list_event_instances` | Recurring event instances |

Write tools (`send`, `reply`, `delete`, `cancel`, etc.) execute immediately. Confirm with the user before calling.

## Architecture

```
src/
├── auth/           # Token extraction, refresh, encryption
├── browser/        # Playwright login (persistent profile)
├── api/            # OWA REST clients (mail, calendar, service.svc)
├── tools/          # MCP tool handlers
├── utils/          # HTTP, parsers, api-config
└── server.ts       # OutlookServer MCP class
```

See `docs/API-REFERENCE.md` and `docs/SESSION-DATA-REFERENCE.md` for API and session details.

## License

MIT