What is Outlookmcp

outlookmcp is an MCP (Model Context Protocol) server that provides read-only access to Outlook/Microsoft 365 calendar events via an API.

Use cases

Use cases include retrieving calendar events for personal scheduling, integrating calendar data into productivity applications, and enabling AI assistants to access and manage calendar events.

How to use

To use outlookmcp, clone the repository, install the necessary dependencies, build the MCP server and CLI client, and configure the application using either a YAML config file or environment variables.

Key features

Key features include read-only access to calendar events, support for multiple platforms (Windows, macOS, Linux), and customizable configurations through YAML files or environment variables.

Where to use

outlookmcp can be used in applications that require integration with Outlook/Microsoft 365 calendars, such as scheduling tools, personal assistants, or any AI-driven applications needing calendar data.

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