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

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

Building the Application

Building the MCP Server

# 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

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

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

# 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

# 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

# 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

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

{
  "tool": "get_auth_url",
  "params": {}
}

Then retrieve calendar events:

{
  "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:

3. Set up a redirect URI to `http://localhost:1111/callback`

4. Create a client secret and update the configuration