# Outlook Calendar MCP Server

This is an MCP (Model Context Protocol) server that provides read-only access to your Outlook/Microsoft 365 calendar.

## Prerequisites

- Go 1.21 or higher
- Microsoft 365 account with calendar access
- Registered application in Azure AD with appropriate permissions

## Project Structure

- `outlook/outlook_api.go` - Internal API for interacting with Outlook calendar
- `cmd/mcp/main.go` - MCP server implementation for use with AI assistants
- `cmd/cli/main.go` - Command-line interface for testing
- `config.example.yaml` - Example configuration file

## Installation

```bash
git clone https://github.com/your-username/outlookmcp.git
cd outlookmcp
go mod download
```

## Building the Application

### Building the MCP Server

```bash
# Build for the current platform
go build -o outlook-mcp ./cmd/mcp

# Cross-compile for Windows
GOOS=windows GOARCH=amd64 go build -o outlook-mcp.exe ./cmd/mcp

# Cross-compile for macOS
GOOS=darwin GOARCH=amd64 go build -o outlook-mcp-mac ./cmd/mcp

# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o outlook-mcp-linux ./cmd/mcp
```

### Building the CLI Client

```bash
# Build for the current platform
go build -o outlook-cli ./cmd/cli

# Cross-compile for Windows
GOOS=windows GOARCH=amd64 go build -o outlook-cli.exe ./cmd/cli

# Cross-compile for macOS
GOOS=darwin GOARCH=amd64 go build -o outlook-cli-mac ./cmd/cli

# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o outlook-cli-linux ./cmd/cli
```

## Configuration

There are two ways to configure the application:

1. Using a YAML config file (see `config.example.yaml`)
2. Using environment variables

### Config File

Create a `config.yaml` file based on the example:

```yaml
outlook:
  me: "John Doe"
  max_attendees: 10
  max_event_count: 50
  skip_all_day_events: true
```

### Environment Variables

Create a `.env` file with your Azure AD application credentials:

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

## Running the Applications

Both the MCP server and CLI application accept optional command-line arguments:
- First argument: Path to the config file (optional)
- Second argument: Path to the .env file (optional)

### Running from Source

#### Running the MCP Server

```bash
# With default configuration
go run cmd/mcp/main.go

# With custom config file
go run cmd/mcp/main.go config.yaml

# With custom config and env file
go run cmd/mcp/main.go config.yaml .env.production
```

#### Running the CLI Client

```bash
# With default configuration
go run cmd/cli/main.go

# With custom config file
go run cmd/cli/main.go config.yaml

# With custom config and env file
go run cmd/cli/main.go config.yaml .env.production
```

### Running the Built Binaries

#### Running the MCP Server Binary

```bash
# With default configuration
./outlook-mcp

# With custom config file
./outlook-mcp config.yaml

# With custom config and env file
./outlook-mcp config.yaml .env.production
```

#### Running the CLI Client Binary

```bash
# With default configuration
./outlook-cli

# With custom config file
./outlook-cli config.yaml

# With custom config and env file
./outlook-cli config.yaml .env.production
```

## Authentication

The server implements on-demand authentication:

1. When a calendar tool is called, it checks if you're already authenticated
2. If not authenticated, it returns an error with an authentication URL
3. You must first call the `get_auth_url` tool to start the auth flow
4. The authentication URL opens in your browser
5. After successful auth, the callback is captured and the token is stored

## Available Tools

### get_auth_url

Initiates the authentication flow with Microsoft.

**Parameters:** None

**Returns:**
Authentication URL to open in browser

### get_calendar_events

Retrieves events from your Outlook calendar for a specified time period.

**Parameters:**
- `start_date` (optional): Start date in format YYYY-MM-DD. If not provided, defaults to today.
- `end_date` (optional): End date in format YYYY-MM-DD. If not provided, defaults to today.

**Returns:**
A JSON array of calendar events with the following properties:
- `subject`: The event title
- `startTime`: Event start time
- `endTime`: Event end time
- `isAllDay`: Whether the event is an all-day event
- `isAccepted`: Whether the event is accepted
- `isCancelled`: Whether the event is cancelled
- `location`: Event location (if available)
- `organizer`: Name of the event organizer (if available)
- `description`: Brief description/preview of the event body (if available)
- `attendees`: List of attendees

## Example Usage

First authenticate:
```json
{
  "tool": "get_auth_url",
  "params": {}
}
```

Then retrieve calendar events:
```json
{
  "tool": "get_calendar_events",
  "params": {
    "start_date": "2023-11-01",
    "end_date": "2023-11-07"
  }
}
```

## CLI Usage

The CLI application provides a simple interactive interface:

1. Select `get_auth_url` to authenticate
2. Open the provided URL in your browser to authorize the application
3. After authorization, use `get_calendar_events` to retrieve calendar data

## Security Considerations

- Store your client secret securely (use environment variables)
- The server only provides read-only access to calendar data
- No write operations are implemented
- Token is stored in memory only for the duration of the server's execution

## Azure AD Application Setup

1. Register a new application in the Azure portal
2. Add the following permissions:
   - Calendars.Read
   - Calendars.Read.Shared
   - Calendars.ReadBasic
3. Set up a redirect URI to `http://localhost:1111/callback`
4. Create a client secret and update the configuration