@developer.k/ms-graph-mcp

A modular Model Context Protocol server for Microsoft Graph and Microsoft 365.

It uses delegated device-code authentication and exposes tools for Teams, Outlook mail, Calendar, Microsoft To Do, Contacts, OneDrive, SharePoint, and common Microsoft 365 file operations.

GitHub repository | npm package

See the changelog for release notes and upgrade requirements.

Features

Related MCP server: M365 Graph MCP Server

Requirements

• Node.js 18 or newer

• A Microsoft Entra app registration with public client flows enabled

• The delegated Microsoft Graph permissions required by the modules you use

• An Exchange Online or Outlook.com mailbox for Mail, Calendar, Contacts, and mailbox settings

• A Microsoft 365 or Office 365 license that includes Teams for Teams chat and channel APIs

• A provisioned OneDrive for OneDrive and common file tools

• SharePoint Online and a work or school account for SharePoint site, library, and List tools

• An MCP client with form elicitation support to send mail or delete files and folders

calendar_get_schedule and calendar_find_meeting_times are intended for work or school accounts and are not supported for personal Microsoft accounts.

For a personal Outlook.com or OneDrive account, register an app that supports personal Microsoft accounts and set MS_TENANT_ID to common. SharePoint site and List APIs are not available to personal Microsoft accounts.

Follow the screenshot-based Microsoft Graph API Setup Guide to register an app, add permissions, and enable public client flows.

Delegated Permissions

The default scope set requests the permissions needed by every included module:

The file scopes allow the MCP to operate on files the signed-in user can access, while Graph still enforces that user's permissions. Some tenant policies require administrator consent. Use MS_GRAPH_SCOPES to request a smaller set when only selected modules are needed; Files.ReadWrite is sufficient when only the signed-in user's own OneDrive files are required.

Quick Start

Configure your MCP client to run the published package with npx. Configuration values can be placed directly in the MCP client's env block; shell environment variables are not otherwise required.

{
  "mcpServers": {
    "ms-graph": {
      "command": "npx",
      "args": ["-y", "@developer.k/ms-graph-mcp"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_TENANT_ID": "organizations"
      }
    }
  }
}

Call graph_auth_device_code, open the returned login URL, enter the device code, and then call graph_auth_status. Use force: true after adding permissions or when an old device-code flow has expired.

Configuration

Required:

• MS_CLIENT_ID: Microsoft Entra Application (client) ID.

Optional:

• MS_TENANT_ID: organizations, common, or a Directory (tenant) ID. Default: organizations.

• MS_GRAPH_SCOPES: Comma- or space-separated delegated scopes that replace the default scope set.

• MS_GRAPH_TOKEN_CACHE_PATH: Local MSAL token cache path.

• MS_GRAPH_ACCOUNT_USERNAME: Cached account to select when more than one account is available.

• MS_GRAPH_ENABLE_BETA: Set to true to register isolated Microsoft Graph beta tools. Default: disabled.

Example of a read-focused custom scope set:

{
  "env": {
    "MS_CLIENT_ID": "your-entra-application-client-id",
    "MS_TENANT_ID": "organizations",
    "MS_GRAPH_SCOPES": "User.Read Mail.Read Calendars.Read Tasks.Read Contacts.Read MailboxSettings.Read Files.Read.All Sites.Read.All offline_access"
  }
}

Strict Confirmation

The following operations always require direct user confirmation through MCP form elicitation:

mail_send_draft
mail_send_message
mail_reply
mail_reply_all
mail_forward
files_delete_item

The server presents the exact recipients and message summary for mail operations. Before file or folder deletion, it reads and presents the current item name, type, path, size, URL when available, drive id, and item id. The user must accept the elicitation and explicitly enable its confirmation field before the Graph write request is sent. Confirmed draft messages and drive items are read again before execution; if their version changed while the confirmation was open, the operation stops and must be reviewed again.

This is enforced by the server rather than by a confirm: true tool argument. There is no model-settable bypass. Declining or cancelling returns a cancellation result without sending the destructive request. If the MCP client does not advertise form elicitation support, the operation fails closed and no mail is sent or file is deleted.

MCP elicitation is the trusted user-interaction boundary. The client must display the form to the user and return the user's response without automatically approving it.

Tools

Graph:

graph_auth_device_code
graph_auth_status
graph_get_me

Teams:

teams_list_joined_teams
teams_list_channels
teams_list_channel_messages
teams_list_channel_replies
teams_send_channel_message
teams_reply_channel_message
teams_list_chats
teams_list_chat_messages
teams_list_pinned_chat_messages
teams_list_chat_members
teams_find_self_chat
teams_send_chat_message
teams_reply_chat_messages_with_quote
teams_pin_chat_message
teams_send_self_message

Mention-capable send and reply tools accept caller-supplied Microsoft Entra user ids. Put {{mention:key}} in the HTML content, then provide a matching mentions entry with key, user_id, and display_name. The server intentionally does not search the tenant directory, so these tools require no additional directory permission.

Teams beta, registered only when MS_GRAPH_ENABLE_BETA=true:

teams_beta_forward_chat_message_to_chat
teams_beta_forward_channel_message_to_chat
teams_beta_forward_channel_reply_to_chat

The forwarding tools use Microsoft Graph beta endpoints and are isolated from the stable Teams module. Microsoft may change beta behavior without notice. The current Graph API accepts one source message and one target chat per call.

Mail:

mail_list_folders
mail_list_messages
mail_get_message
mail_list_attachments
mail_get_attachment
mail_add_attachment
mail_create_draft
mail_update_draft
mail_create_reply_draft
mail_create_forward_draft
mail_send_draft
mail_send_message
mail_reply
mail_reply_all
mail_forward
mail_update_message
mail_move_message
mail_delete_message
mail_list_rules
mail_create_rule
mail_update_rule
mail_delete_rule

Calendar:

calendar_list_calendars
calendar_get_calendar
calendar_create_calendar
calendar_update_calendar
calendar_delete_calendar
calendar_list_events
calendar_get_event
calendar_create_event
calendar_update_event
calendar_delete_event
calendar_cancel_event
calendar_respond_event
calendar_get_schedule
calendar_find_meeting_times

Microsoft To Do:

todo_list_task_lists
todo_get_task_list
todo_create_task_list
todo_update_task_list
todo_delete_task_list
todo_list_tasks
todo_get_task
todo_create_task
todo_update_task
todo_complete_task
todo_delete_task
todo_list_checklist_items
todo_create_checklist_item
todo_update_checklist_item
todo_delete_checklist_item
todo_list_linked_resources
todo_create_linked_resource
todo_delete_linked_resource

Contacts:

contacts_list_folders
contacts_get_folder
contacts_create_folder
contacts_update_folder
contacts_delete_folder
contacts_list
contacts_get
contacts_create
contacts_update
contacts_delete

Outlook settings and categories:

outlook_get_mailbox_settings
outlook_update_mailbox_settings
outlook_set_automatic_replies
outlook_list_categories
outlook_get_category
outlook_create_category
outlook_update_category
outlook_delete_category

Common files:

files_get_drive
files_list_children
files_get_item
files_get_item_by_path
files_search
files_download_content
files_create_folder
files_upload_content
files_update_item
files_move_item
files_copy_item
files_delete_item
files_list_permissions
files_create_share_link
files_delete_permission

OneDrive:

onedrive_get_default_drive
onedrive_list_drives
onedrive_get_root
onedrive_list_root
onedrive_get_item_by_path
onedrive_search
onedrive_resolve_share_url

SharePoint:

sharepoint_get_root_site
sharepoint_search_sites
sharepoint_get_site
sharepoint_get_site_by_path
sharepoint_list_site_drives
sharepoint_get_default_drive
sharepoint_list_lists
sharepoint_get_list
sharepoint_list_columns
sharepoint_list_items
sharepoint_get_list_item
sharepoint_create_list_item
sharepoint_update_list_item
sharepoint_delete_list_item

Use onedrive_get_default_drive or sharepoint_list_site_drives to discover a drive_id, then use the common files_* tools for file and folder operations in either storage system.

Example Prompts

List the latest messages and replies in channel CHANNEL_ID of team TEAM_ID.
Send "Please review" to channel CHANNEL_ID and mention user USER_OBJECT_ID as "Alex Kim".
Reply to channel message MESSAGE_ID and mention user USER_OBJECT_ID.
Reply in chat CHAT_ID while quoting messages MESSAGE_ID_1 and MESSAGE_ID_2.
Show the pinned messages in chat CHAT_ID, then pin MESSAGE_ID after I confirm.
Translate message MESSAGE_ID into Korean and show the translation without posting it.
Forward message MESSAGE_ID from chat SOURCE_CHAT_ID to TARGET_CHAT_ID. The beta tools must be enabled.

Show the 10 most recent unread messages in my Inbox.
Find messages containing "quarterly report" and summarize their subjects and senders.
Create a draft reply to this message, but do not send it.
Create a draft email to user@example.com with the subject "Project update".
Send draft MESSAGE_ID after showing me its current recipients and subject.
Move message MESSAGE_ID to folder FOLDER_ID.

Show my calendar events for next week in Asia/Seoul.
Find a 30-minute time when all three attendees are available.
Create a Teams online meeting tomorrow at 2 PM.
Accept event EVENT_ID and send a response.

List my Microsoft To Do task lists.
Add a high-priority task due Friday with a reminder one day earlier.
Add three checklist items to task TASK_ID.
Mark task TASK_ID as completed.

Find the contact with email user@example.com.
Create a business contact in folder FOLDER_ID.
Schedule automatic replies from Monday morning through Friday evening.
Create an Outlook category named "Customer" using preset7.

List the folders and files in my OneDrive root.
Search my OneDrive and files shared with me for "quarterly report".
Upload this text as notes.txt without sending it anywhere else.
Create a folder named "Release Notes" in drive DRIVE_ID.
Copy item ITEM_ID into folder FOLDER_ID and return the copy monitor URL.
Show the current sharing permissions for item ITEM_ID before creating a link.

Find the SharePoint site named "Engineering" and list its document libraries.
List the columns in SharePoint list LIST_ID before reading its items.
Create a SharePoint List Item with Title "Release" and Status "Ready".
Update item ITEM_ID in list LIST_ID to set Status to "Done".

Prefer draft tools before mail send tools so the recipients and content can be reviewed. Send, reply, forward, cancel, move, copy, share, upload, and delete tools modify real Microsoft 365 data.

Local Development

Use this section only when running from a local clone:

npm install
npm test

{
  "mcpServers": {
    "ms-graph": {
      "command": "node",
      "args": ["/path/to/ms-graph-mcp/build/index.js"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_TENANT_ID": "organizations"
      }
    }
  }
}

Project Structure

src/
|-- auth/
|   +-- msal.ts
|-- confirmation.ts
|-- graph/
|   +-- client.ts
|-- files/
|   +-- drive.ts
|-- modules/
|   |-- calendar.ts
|   |-- contacts.ts
|   |-- files.ts
|   |-- mail.ts
|   |-- onedrive.ts
|   |-- outlook.ts
|   |-- sharepoint.ts
|   |-- shared.ts
|   |-- teams-beta.ts
|   |-- teams-message.ts
|   |-- teams.ts
|   +-- todo.ts
|-- config.ts
|-- index.ts
|-- tools.ts
+-- types.ts

Current Limits

• Tools operate on the signed-in user's /me resources. Shared mailboxes and delegated shared folders are not yet exposed.

• Webhook subscriptions are not included because a stdio MCP server has no permanent public callback endpoint.

• Simple file attachments are limited to 3 MiB. Larger attachments require a Microsoft Graph upload session.

• files_upload_content is limited to 4 MiB and creates or replaces a file at the selected path. Large-file upload sessions are not yet exposed.

• files_download_content defaults to a 4 MiB response limit and allows at most 10 MiB to keep MCP responses bounded.

• SharePoint tools operate on existing sites and lists; site, list, and column schema creation are not exposed.

• Contact filtering supports exact email address matching. Microsoft Graph does not expose general name search on the contacts collection.

• Teams mentions require a known Microsoft Entra user object id because directory search is intentionally not exposed.

• Chat pin listing and pinning are supported. Unpinning is omitted because it requires the additional Chat.ReadWrite delegated permission, and channel-message pinning is not exposed by the stable Graph API.

• Teams forwarding is disabled by default and uses isolated Microsoft Graph beta tools when MS_GRAPH_ENABLE_BETA=true.

• Teams message translation is performed by the MCP client or model before sending; Microsoft Graph does not expose a native Teams message translation operation.

• Mail sending and file deletion are unavailable in MCP clients that do not support form elicitation because strict confirmation fails closed.

• Event and message bodies can contain external HTML supplied by Microsoft Graph.

This package contains no credentials, tenant identifiers, account identifiers, or other personalized configuration.