Microsoft 365

What is ms-365-mcp-server?

ms-365-mcp-server is a Model Context Protocol (MCP) server that enables interaction with various Microsoft 365 and Microsoft Office services via the Microsoft Graph API. It acts as a bridge, allowing applications to programmatically access and manage data within the Microsoft 365 ecosystem.

How to use ms-365-mcp-server?

To use ms-365-mcp-server, you need Node.js (>= 14) installed. You can integrate it with MCP clients like Claude Desktop or Claude Code CLI. For Claude Desktop, you add a configuration to its settings. For Claude Code CLI, you use a command to add the server. Authentication is required and can be done via Device Code Flow (default), OAuth Authorization Code Flow (for HTTP mode), or by providing your own token (BYOT).

Key Features of ms-365-mcp-server

• Authentication: Supports Microsoft Authentication Library (MSAL) with Device Code Flow, OAuth Authorization Code Flow, and Bring Your Own Token (BYOT).
• Comprehensive Microsoft 365 Service Integration: Provides access to a wide range of Microsoft 365 services.
• Read-only Mode: Allows safe operations by disabling write functionalities.
• Tool Filtering: Offers granular access control by enabling specific tools based on a regex pattern.
• Flexible Deployment: Can be run as a standard I/O server or an HTTP server.

Supported Services & Tools

• Email (Outlook): List, get, send, and delete mail messages and folders.
• Calendar: List, get, create, update, and delete calendar events.
• OneDrive & SharePoint Files: List, get, download, upload, and delete files and folders.
• Excel Operations: List worksheets, get ranges, create charts, format, and sort ranges.
• OneNote: List notebooks, sections, and pages; get page content; create pages.
• To Do Tasks: List, get, create, update, and delete tasks and task lists.
• Planner: List and get planner tasks and plans.
• Contacts: List, get, create, update, and delete Outlook contacts.
• Teams & Chats: List, get, send, and reply to chat messages; list joined teams, channels, and members (Work/School accounts only).
• SharePoint Sites: Search, get, and list sites, drives, items, and lists (Work/School accounts only).
• User Profile: Get current user information.

Use Cases of ms-365-mcp-server

• Automation of Microsoft 365 Workflows: Automate tasks like sending emails, managing calendar events, or organizing files.
• Building Custom Integrations: Develop custom applications that interact with Microsoft 365 data.
• Data Management: Programmatically access and manage data across various Microsoft 365 services.
• Productivity Tools: Create tools that enhance productivity by streamlining interactions with Microsoft 365.

FAQ from ms-365-mcp-server

• How to handle Work Scopes Issues for Teams/SharePoint? If you encounter issues accessing work/school features, pass the --force-work-scopes flag when running the server. This ensures proper scope permissions from the start.
• What are the authentication methods supported? The server supports Device Code Flow (default for interactive login), OAuth Authorization Code Flow (for HTTP mode), and Bring Your Own Token (BYOT) for pre-existing tokens.
• Can I run the server in read-only mode? Yes, you can start the server in read-only mode by using the --read-only flag or setting the READ_ONLY environment variable to true or 1.
• How can I filter the available tools? You can filter tools using the --enabled-tools <pattern> flag or the ENABLED_TOOLS environment variable, providing a regex pattern to enable specific tools (e.g., excel|contact).
• How do I set up Azure AD for OAuth testing? You need to create an Azure AD App Registration in the Azure Portal, configure redirect URIs, get client ID and secret, and then set these as environment variables (MS365_MCP_CLIENT_ID, MS365_MCP_CLIENT_SECRET, MS365_MCP_TENANT_ID).

ms-365-mcp-server

Microsoft 365 MCP Server

A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Microsoft Office services through the Graph API.

Prerequisites

• Node.js >= 14

Features

• Authentication via Microsoft Authentication Library (MSAL)
• Comprehensive Microsoft 365 service integration
• Read-only mode support for safe operations
• Tool filtering for granular access control

Supported Services & Tools

Email (Outlook)
list-mail-messages, list-mail-folders, list-mail-folder-messages, get-mail-message, send-mail, delete-mail-message

Calendar
list-calendars, list-calendar-events, get-calendar-event, get-calendar-view, create-calendar-event, update-calendar-event, delete-calendar-event

OneDrive & SharePoint Files
list-drives, get-drive-root-item, list-folder-files, download-onedrive-file-content, upload-file-content, upload-new-file, delete-onedrive-file

Excel Operations
list-excel-worksheets, get-excel-range, create-excel-chart, format-excel-range, sort-excel-range

OneNote
list-onenote-notebooks, list-onenote-notebook-sections, list-onenote-section-pages, get-onenote-page-content, create-onenote-page

To Do Tasks
list-todo-task-lists, list-todo-tasks, get-todo-task, create-todo-task, update-todo-task, delete-todo-task

Planner
list-planner-tasks, get-planner-plan, list-plan-tasks, get-planner-task, create-planner-task

Contacts
list-outlook-contacts, get-outlook-contact, create-outlook-contact, update-outlook-contact, delete-outlook-contact

Teams & Chats (Work/School accounts only)
list-chats, get-chat, list-chat-messages, get-chat-message, send-chat-message, list-chat-message-replies, reply-to-chat-message, list-joined-teams, get-team, list-team-channels, get-team-channel, list-channel-messages, get-channel-message, send-channel-message, list-team-members

SharePoint Sites (Work/School accounts only)
search-sharepoint-sites, get-sharepoint-site, get-sharepoint-site-by-path, list-sharepoint-site-drives, get-sharepoint-site-drive-by-id, list-sharepoint-site-items, get-sharepoint-site-item, list-sharepoint-site-lists, get-sharepoint-site-list, list-sharepoint-site-list-items, get-sharepoint-site-list-item, get-sharepoint-sites-delta

Work Scopes Issues

If you're having issues accessing work/school features (Teams, SharePoint, etc.), you should pass the --force-work-scopes flag!

{
  "mcpServers": {
    "ms365": {
      "command": "npx",
      "args": [
        "-y",
        "@softeria/ms-365-mcp-server",
        "--force-work-scopes"
      ]
    }
  }
}

While the server should attempt to force a re-login when work scopes are needed, passing the flag explicitly is safer and ensures proper scope permissions from the start.

User Profile
get-current-user

Quick Start Example

Test login in Claude Desktop:

Examples

Integration

Claude Desktop

To add this MCP server to Claude Desktop:

Edit the config file under Settings > Developer:

{
  "mcpServers": {
    "ms365": {
      "command": "npx",
      "args": [
        "-y",
        "@softeria/ms-365-mcp-server"
      ]
    }
  }
}

Claude Code CLI

claude mcp add ms365 -- npx -y @softeria/ms-365-mcp-server

For other interfaces that support MCPs, please refer to their respective documentation for the correct integration method.

Authentication

⚠️ You must authenticate before using tools.

The server supports three authentication methods:

1. Device Code Flow (Default)

For interactive authentication via device code:

• MCP client login:
  • Call the login tool (auto-checks existing token)
  • If needed, get URL+code, visit in browser
  • Use verify-login tool to confirm
• CLI login:

  npx @softeria/ms-365-mcp-server --login
  

  Follow the URL and code prompt in the terminal.

Tokens are cached securely in your OS credential store (fallback to file).

2. OAuth Authorization Code Flow (HTTP mode only)

When running with --http, the server requires OAuth authentication:

npx @softeria/ms-365-mcp-server --http 3000

This mode:

• Advertises OAuth capabilities to MCP clients
• Provides OAuth endpoints at /auth/* (authorize, token, metadata)
• Requires Authorization: Bearer <token> for all MCP requests
• Validates tokens with Microsoft Graph API
• Disables login/logout tools by default (use --enable-auth-tools to enable them)

MCP clients will automatically handle the OAuth flow when they see the advertised capabilities.

Setting up Azure AD for OAuth Testing

To use OAuth mode with custom Azure credentials (recommended for production), you'll need to set up an Azure AD app registration:

1. Create Azure AD App Registration:

   • Go to Azure Portal
   • Navigate to Azure Active Directory → App registrations → New registration
   • Set name: "MS365 MCP Server"

2. Configure Redirect URIs: Add these redirect URIs for testing with MCP Inspector:

   • http://localhost:6274/oauth/callback
   • http://localhost:6274/oauth/callback/debug
   • http://localhost:3000/callback (optional, for server callback)

3. Get Credentials:

   • Copy the Application (client) ID from Overview page
   • Go to Certificates & secrets → New client secret → Copy the secret value

4. Configure Environment Variables: Create a .env file in your project root:

   MS365_MCP_CLIENT_ID=your-azure-ad-app-client-id-here
   MS365_MCP_CLIENT_SECRET=your-azure-ad-app-client-secret-here
   MS365_MCP_TENANT_ID=common
   

With these configured, the server will use your custom Azure app instead of the built-in one.

3. Bring Your Own Token (BYOT)

If you are running ms-365-mcp-server as part of a larger system that manages Microsoft OAuth tokens externally, you can provide an access token directly to this MCP server:

MS365_MCP_OAUTH_TOKEN=your_oauth_token npx @softeria/ms-365-mcp-server

This method:

• Bypasses the interactive authentication flows
• Uses your pre-existing OAuth token for Microsoft Graph API requests
• Does not handle token refresh (token lifecycle management is your responsibility)

Note: HTTP mode requires authentication. For unauthenticated testing, use stdio mode with device code flow.

Authentication Tools: In HTTP mode, login/logout tools are disabled by default since OAuth handles authentication. Use --enable-auth-tools if you need them available.

CLI Options

The following options can be used when running ms-365-mcp-server directly from the command line:

--login           Login using device code flow
--logout          Log out and clear saved credentials
--verify-login    Verify login without starting the server
--force-work-scopes Force inclusion of work account scopes during login (includes Teams, SharePoint, etc.)

Server Options

When running as an MCP server, the following options can be used:

-v                Enable verbose logging
--read-only       Start server in read-only mode, disabling write operations
--http [port]     Use Streamable HTTP transport instead of stdio (optionally specify port, default: 3000)
                  Starts Express.js server with MCP endpoint at /mcp
--enable-auth-tools Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)
--enabled-tools <pattern> Filter tools using regex pattern (e.g., "excel|contact" to enable Excel and Contact tools)

Environment variables:

• READ_ONLY=true|1: Alternative to --read-only flag
• ENABLED_TOOLS: Filter tools using regex pattern (alternative to --enabled-tools flag)
• MS365_MCP_FORCE_WORK_SCOPES=true|1: Force inclusion of work account scopes (alternative to --force-work-scopes flag)
• LOG_LEVEL: Set logging level (default: 'info')
• SILENT=true|1: Disable console output
• MS365_MCP_CLIENT_ID: Custom Azure app client ID (defaults to built-in app)
• MS365_MCP_TENANT_ID: Custom tenant ID (defaults to 'common' for multi-tenant)
• MS365_MCP_OAUTH_TOKEN: Pre-existing OAuth token for Microsoft Graph API (BYOT method)

Support

If you're having problems or need help:

• Create an issue
• Start a discussion
• Email: eirikb@eirikb.no
• Discord: https://discord.gg/WvGVNScrAZ or @eirikb

License

MIT © 2025 Softeria