outlookmcp

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