@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, mailbox settings, and Outlook categories.

GitHub repository | npm package

See the changelog for release notes and upgrade requirements.

Features

Module	Capabilities
Graph	Device-code authentication, auth status, signed-in profile
Teams	Teams, channels, channel messages, chats, chat members, self-chat messaging
Mail	Folders, message search, attachments, drafts, send/reply/forward, flags, categories, move/delete, Inbox rules
Calendar	Calendars, date-range event views, events, online meetings, invitations, free/busy, meeting suggestions
To Do	Task lists, tasks, recurrence, reminders, completion, checklist items, linked resources
Contacts	Contact folders and contacts, including common personal and business fields
Outlook	Mailbox settings, working hours, automatic replies, and master categories

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

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 account, register an app that supports personal Microsoft accounts and set MS_TENANT_ID to common.

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:

Module	Permissions
Core	User.Read, offline_access
Teams	Team.ReadBasic.All, Channel.ReadBasic.All, ChannelMessage.Read.All, ChannelMessage.Send, Chat.Read, ChatMessage.Send
Mail	Mail.ReadWrite, Mail.Send
Calendar	Calendars.ReadWrite, Calendars.ReadWrite.Shared
To Do	Tasks.ReadWrite
Contacts	Contacts.ReadWrite
Outlook settings, categories, and rules	MailboxSettings.ReadWrite

Some tenant policies require administrator consent. Use MS_GRAPH_SCOPES to request a smaller set when only selected modules are needed.

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.

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 offline_access"
  }
}

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_send_channel_message
teams_list_chats
teams_list_chat_messages
teams_list_chat_members
teams_find_self_chat
teams_send_chat_message
teams_send_self_message

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

Example Prompts

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.

Prefer draft tools before mail send tools so the recipients and content can be reviewed. Send, reply, forward, cancel, move, 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
|-- graph/
|   +-- client.ts
|-- modules/
|   |-- calendar.ts
|   |-- contacts.ts
|   |-- mail.ts
|   |-- outlook.ts
|   |-- shared.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.
• Contact filtering supports exact email address matching. Microsoft Graph does not expose general name search on the contacts collection.
• 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.