ms-365-mcp-server

Implements Microsoft Authentication Library (MSAL) device code flow to authenticate users without requiring interactive browser login, storing tokens securely in the OS credential store via Keytar for persistence across sessions. The flow generates a device code that users enter on a browser, while the server polls Microsoft's token endpoint until authentication completes, then caches the refresh token locally for subsequent API calls without re-authentication.

Implements the Model Context Protocol (MCP) server specification to expose Microsoft 365 capabilities as callable tools through stdin/stdout communication. The server registers a tool registry containing Graph API wrappers, handles tool invocation requests from MCP clients (like Claude), marshals parameters, executes Graph API calls, and returns formatted responses back through the MCP protocol, enabling any MCP-compatible client to access Microsoft 365 services.

Implements a Graph API HTTP client that handles authentication header injection, request formatting, response parsing, and error handling. Includes retry logic for transient failures (429 rate limits, 5xx errors) with exponential backoff, and structured error responses that map Graph API errors to user-friendly messages. Manages token refresh automatically when access tokens expire.

Serves as the main orchestration component that initializes the MCP server, sets up authentication, registers all Graph API tools, and manages the server lifecycle. Coordinates between the CLI parser, authentication manager, Graph client, and MCP protocol handler. Implements tool registration by wrapping Graph API operations with parameter validation and response formatting.

Wraps Microsoft Graph API email endpoints to enable reading message lists with filtering/pagination, retrieving full message bodies with attachments, sending emails with recipients and attachments, and managing folder operations (move, delete, archive). Implements Graph API query syntax for filtering by sender, subject, date ranges, and read status, with support for attachment streaming and MIME message composition.

Exposes Microsoft Graph Calendar API to create, read, update, and delete calendar events with support for attendees, meeting times, reminders, and recurrence patterns. Implements event creation with automatic meeting invitation sending, attendee response tracking, and conflict detection through Graph API's calendar view queries. Supports recurring event patterns (daily, weekly, monthly) and timezone-aware scheduling.

Wraps Microsoft Graph DriveItem API to list files and folders, upload/download files, create folders, and manage file metadata. Implements path-based file access (e.g., '/Documents/Report.xlsx') that translates to Graph API's drive item hierarchy navigation, supporting file streaming for large uploads/downloads and metadata queries for file properties (size, modified date, sharing status).

Exposes Microsoft Graph Excel API to read and write cell values, create worksheets, and execute formulas within Excel files stored in OneDrive. Implements OneNote API access to read notebook structure, create pages, and append content. Both services use Graph API's workbook sessions for transactional consistency and support batch operations for multiple cell updates.

Wraps Microsoft Graph To Do API and Planner API to create, read, update, and complete tasks within task lists and plans. Implements hierarchical task organization through Planner plans (team-level) and To Do lists (personal), with support for task assignments, due dates, priority levels, and completion tracking. Supports batch task operations and task status transitions (not started, in progress, completed).

Exposes Microsoft Graph Contacts API to read, create, update, and delete contacts in the user's Outlook address book. Implements contact property management (email addresses, phone numbers, organization, job title) and supports searching contacts by name or email. Integrates with the organizational directory for looking up colleagues and external contacts.

Implements optional read-only mode that prevents all write operations (email sending, file uploads, task creation, contact modifications) while preserving read access to Microsoft 365 data. Enforced at the tool level by validating operation type before executing Graph API calls, returning error responses for write attempts when read-only mode is enabled. Configuration via CLI flag or environment variable.

Uses Commander.js to parse command-line arguments and options for server startup, including authentication parameters, read-only mode, and logging configuration. Implements configuration validation and defaults, enabling flexible deployment across different environments (local development, Docker containers, cloud services). Supports both CLI flags and environment variable overrides.