MCP M365 Server

A Microsoft 365 MCP (Model Context Protocol) server built with the mcp-framework, providing access to calendar, contacts, and authentication services.

Overview

This server implements the Model Context Protocol to allow AI assistants to interact with Microsoft 365 services, specifically:

• Calendar Operations: List, create, update, and delete calendar events (including recurring events)
• Contacts Operations: Manage contacts, contact folders, and search contacts
• Authentication Status: Check current authentication state
• Calendar Management: Access to user calendars

Architecture

Built using the mcp-framework, this server follows a provider-based architecture:

• CalendarToolProvider: Handles all calendar-related tools (8 tools total)
• ContactsToolProvider: Handles all contacts-related tools (7 tools total)
• AuthToolProvider: Handles authentication and session management
• M365ResourceProvider: Provides access to M365 resources (calendars, contacts, auth status)
• FrameworkServer: Orchestrates providers and handles MCP protocol

Features

Calendar Tools

• list_calendars - List all user calendars
• get_calendar_details - Get details of a specific calendar
• list_events - ENHANCED: List events with powerful server-side filtering, search, projection, sorting, and pagination
  • Advanced Filtering: Filter by organizer, subject, location, attendees, categories, response status, sensitivity
  • Full-text Search: Search event content and metadata using Microsoft Graph search
  • Projection: Specify exactly which fields to return (reduces token usage)
  • Pagination: Opaque cursor-based paging with deterministic sorting
  • Metadata: Returns applied filters, search terms, and query transparency
• create_event - Create new calendar events (single or recurring)
• update_event - Update existing events (can add/modify recurrence)
• delete_event - Delete calendar events
• get_event - Get single event details
• get_upcoming_events - Get events for the next 7 days

Contacts Tools

• list_contacts - List contacts from default or specified folder
• get_contact - Get a specific contact by ID
• create_contact - Create new contacts with full details (name, email, phone, address, company info)
• update_contact - Update existing contact information
• delete_contact - Delete a contact
• search_contacts - Search contacts by name or email
• list_contact_folders - List all contact folders

Resources

• https://mcp.m365/calendars - Access to calendar metadata
• https://mcp.m365/contacts - Access to contacts metadata
• https://mcp.m365/auth/status - Current authentication status

Enhanced list_events Contract

The list_events tool has been upgraded with a powerful unified contract supporting advanced filtering, search, and pagination. This replaces the previous simple parameter-based approach.

New Contract Structure

{
  "target": {
    "scope": "me | user | group | calendar",
    "id": "userId | groupId",
    "resourceId": "calendarId"
  },
  "range": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-12-31T23:59:59Z",
    "timezone": "UTC"
  },
  "query": {
    "organizer": "me | [email protected]",
    "subject.contains": "meeting",
    "location.contains": "Building A",
    "attendee.contains": "[email protected]",
    "includeCancelled": false,
    "isAllDay": true,
    "categories": ["Project X", "Planning"],
    "response": "accepted | tentative | declined",
    "sensitivity": "normal | private | confidential",
    "freeText": "quarterly review"
  },
  "fields": ["id", "subject", "start", "end", "organizer"],
  "sort": { "field": "start.dateTime", "dir": "asc" },
  "page": { "size": 50, "cursor": "opaque-cursor" },
  "limit": 500
}

Response Format

{
  "items": [
    {
      "id": "AAMk...",
      "subject": "Sprint Planning",
      "start": { "dateTime": "2025-10-01T10:00:00Z", "timeZone": "UTC" },
      "end": { "dateTime": "2025-10-01T11:00:00Z", "timeZone": "UTC" },
      "organizer": { "emailAddress": { "address": "[email protected]" } }
    }
  ],
  "meta": {
    "returned": 1,
    "nextCursor": null,
    "moreAvailable": false,
    "applied": {
      "filter": "isCancelled eq false and contains(subject,'meeting')",
      "search": "\"quarterly review\"",
      "select": ["id", "subject", "start", "end", "organizer"],
      "orderby": "start/dateTime asc, id asc"
    },
    "source": {
      "endpoint": "/me/calendarView?startDateTime=...&endDateTime=...",
      "headers": ["Prefer: outlook.timezone=\"UTC\""]
    }
  }
}

Migration Guide

Breaking Changes:

• Old: list_events({ calendar_id: "id", start_date: "2025-01-01T00:00:00Z", end_date: "2025-01-31T23:59:59Z" })
• New: list_events({ range: { start: "2025-01-01T00:00:00Z", end: "2025-01-31T23:59:59Z" }, target: { resourceId: "id" } })

Backward Compatibility: Legacy parameter format still supported for existing integrations, but new features require the unified contract.

Installation

npm install
npm run build

Usage

Development

npm run dev

Production

npm run build
node dist/server.js

Configuration

The server uses environment variables for configuration:

• LOG_LEVEL - Logging level (default: "info")
• Microsoft Graph API credentials (CLIENT_ID, TENANT_ID, etc.)
• M365_CACHE_FILE / M365_CACHE_DIR / M365_CACHE_FILENAME / M365_CACHE_SUBDIR - Override where the encrypted MSAL token cache is stored (defaults to ~/.mcp-m365/msal-cache.json)

Testing

npm test

MCP Inspector

Test the server with the MCP Inspector:

npm install -g @modelcontextprotocol/inspector
mcp-inspector npx tsx src/index.ts

Migration from Custom Implementation

This server was refactored from a custom MCP implementation to use the mcp-framework:

• ✅ Replaced custom MCP protocol handling with FrameworkServer
• ✅ Migrated to ToolProvider and ResourceProvider abstractions
• ✅ Simplified server setup and configuration
• ✅ Maintained all existing functionality
• ✅ Improved maintainability and extensibility

License

This project is part of the mcp-framework ecosystem.