M365 MCP
Microsoft 365 MCP exposes 17 tools for reading your M365 data via Graph, with an optional Work IQ tool that can perform write-capable actions.
Check/auth connection status and inspect server metadata/tools.
View your profile, manager, reports, groups, and photo.
Read calendar events/calendars and check people’s free/busy schedules.
Read/search mail, folders, attachments, and full message bodies.
Read Teams chats, joined teams, channels, and message threads.
Browse/search OneDrive files, shared files, and item metadata.
Fetch Teams meeting transcripts with previews and pagination.
Search/browse SharePoint sites, lists, and list items.
Read Microsoft To Do lists/tasks and Planner tasks.
Search the org directory; inspect user details, managers, reports, and memberships.
Search across mail, chats, calendar, OneDrive, and SharePoint in one call.
Get recent, shared, or trending document insights.
Assemble a daily or person-focused catch-up brief.
Optionally enable Work IQ to ask its agent, read Graph paths under your own permissions, or call Work IQ tools including create/update/delete/send actions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@M365 MCP show my calendar events for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
M365 MCP
MCP server for Microsoft 365 via the Microsoft Graph API. 17 tools covering your profile, calendar, email, Teams chats and channels, OneDrive files, SharePoint, tasks, the org directory, and meeting transcripts from any MCP client.
Sixteen of the seventeen are read-only. The seventeenth, ms_workiq, is off unless MS365_MCP_WORKIQ_SCOPE is set, and can write — see ms_workiq.
Installation
Claude Code
claude mcp add m365-mcp -e MS365_MCP_CLIENT_ID=your-client-id -e MS365_MCP_TENANT_ID=your-tenant-id -- npx -y @masonator/m365-mcpClaude Desktop
Add to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"m365-mcp": {
"command": "npx",
"args": ["-y", "@masonator/m365-mcp"],
"env": {
"MS365_MCP_CLIENT_ID": "your-azure-ad-client-id",
"MS365_MCP_TENANT_ID": "your-azure-ad-tenant-id"
}
}
}
}First Run
On first use, the server opens your browser to sign in with Microsoft. After granting consent, tokens are stored locally at ~/.config/m365-mcp/tokens.json (permissions 600) and refreshed automatically.
Related MCP server: Microsoft 365 MCP Server
Environment Variables
Variable | Required | Description |
| Yes | Azure AD application (client) ID |
| Yes | Azure AD tenant ID |
| No | Azure AD client secret (confidential clients only) |
| No | Timezone for calendar (default: system timezone) |
| No | OAuth redirect URI (default: dynamic port, |
| No | Set to |
| No | Override the requested scopes, e.g. |
| No | Token filename within the config directory (default: |
| No | Enables |
MS365_MCP_CLIENT_TYPE
Leave this unset unless your app registration uses the Single-Page Application
platform. Only SPA registrations may redeem a token cross-origin; every other
platform — Web, and "Mobile and desktop applications" — rejects the Origin header
with AADSTS9002326. The absence of a client secret is not a reliable signal here,
because a Mobile-and-desktop registration has no secret either.
MS365_MCP_SCOPES
By default the server requests an explicit scope list, so a first-time consent prompt shows exactly what is being asked for.
Set this to https://graph.microsoft.com/.default offline_access if your
registration has more permissions configured than consented. Naming an unconsented
scope fails the entire request with AADSTS65001, whereas .default asks for
whatever is already consented and adapts on its own as that changes.
Whatever the token ends up carrying, the tools adapt: a tool whose permission is
missing explains what is unavailable and what still works, rather than returning a
bare 403. ms_auth_status lists exactly what was granted.
MS365_MCP_TOKEN_FILE
Use this when running more than one app registration. One token file holds one registration's tokens, so signing in with a second client would otherwise silently evict the first.
Azure AD Setup
Register an application in Azure AD with these settings:
App registration > New registration
Redirect URI:
http://localhost(Web platform) — or set a fixed URI viaMS365_MCP_REDIRECT_URLCertificates & secrets > New client secret
API permissions > Add the following delegated permissions:
Permission | Used by |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
All permissions are delegated and read-only: the server acts as the signed-in user and cannot reach anyone else's mailbox, chats or files.
Confidential vs public clients. If the registration uses the Web platform with a client secret, the token request must not carry an
Originheader — Azure rejects cross-origin token redemption for anything but SPA clients (AADSTS9002326). The server detects this fromMS365_MCP_CLIENT_SECRETand omits the header automatically.
Tools
ms_auth_status
Check connection status. If not connected, opens browser to sign in.
ms_profile
Fetch your Microsoft 365 profile — display name, email, job title, office location.
ms_calendar
Fetch calendar events. Defaults to today.
Parameter | Description |
| Specific date (YYYY-MM-DD) |
| Start of range (ISO 8601) |
| End of range (ISO 8601) |
| Summarise each event, omitting the body. Good for scanning. |
ms_mail
Read recent emails with optional keyword search.
Parameter | Description |
| Keyword to filter emails |
| Number of emails (1-25, default 10) |
ms_chat
Read Teams chats. Without chat_id lists recent chats; with chat_id returns messages from that thread.
Parameter | Description |
| Specific chat thread ID |
| Number of items (1-25, default 10) |
ms_files
Browse or search OneDrive files.
Parameter | Description |
| Folder path (e.g., |
| Search across OneDrive |
| Max items (1-50, default 20) |
ms_transcripts
Fetch Teams meeting transcripts. Returns previews (~3000 chars) with a transcript_id for drill-down to the full transcript.
Parameter | Description |
| Date (YYYY-MM-DD) |
| Start of range (ISO 8601) |
| End of range (ISO 8601) |
| ID from a previous list call for full content |
ms_teams
Browse joined Teams, their channels, and channel messages. Progressive drill-down:
no arguments lists teams, team_id lists channels, team_id + channel_id reads messages.
Parameter | Description |
| Team ID to list its channels |
| Channel ID (with |
| Message ID (with both above) to read its reply thread |
| Max results (1-50, default 20) |
ms_tasks
Read Microsoft To Do and Planner tasks. Completed tasks are hidden unless asked for.
Parameter | Description |
| To Do list ID to read its tasks |
| Return assigned Planner tasks instead |
| Include finished tasks (default |
| Max results (1-50, default 25) |
ms_people
Look people up in the organisation directory. search resolves a name to the email
address that ms_schedule needs.
Parameter | Description |
| Name or partial name to search for |
| Email or object ID — returns details, manager, direct reports |
| List the signed-in user's group and team memberships |
| Max results (1-50, default 20) |
ms_search
Search across mail, Teams chats, calendar, OneDrive and SharePoint in one call. Use this
when you don't already know where something lives. Supports KQL, so from:jane subject:budget
works.
Parameter | Description |
| What to search for (required) |
| Limit to |
| Max results per area (1-25, default 5) |
ms_insights
Documents you recently worked with, or that were shared with you.
Parameter | Description |
|
|
| Max results (1-50, default 15) |
trendingis disabled by policy in many tenants; the tool says so plainly rather than returning an error.
ms_brief
One call that assembles a catch-up, composed from the tools above.
With no arguments: today's meetings, unread mail, recent chats, open Planner tasks and
yesterday's meeting transcripts. With person: who they are, plus your recent mail and
chats involving them.
Parameter | Description |
| Catch up on one person — name or email |
| Date for the brief (YYYY-MM-DD, defaults to today) |
| Max items per section (1-15, default 5) |
A section that fails is marked as unavailable rather than taking the whole brief down.
ms_workiq
Not read-only. Off unless MS365_MCP_WORKIQ_SCOPE is set.
Reaches the Microsoft Work IQ agent over its remote MCP server. Work IQ is a separate OAuth resource from Graph, so it redeems its own access token from the same sign-in.
With no parameters it lists the tools Work IQ exposes, marking which ones change
data. question puts a question to the agent. entity_urls reads Graph paths
using your own M365 permissions rather than the app registration's consented
scopes, which is the main reason to enable it: paths the Graph token is refused,
such as /me/manager and /teams/{id}/channels, are readable this way.
tool plus arguments calls any Work IQ tool by name.
Two things to understand before enabling it:
The scope is all-or-nothing.
WorkIQAgent.Askcarries Work IQ's entire tool surface, includingcreate_entity,update_entity,delete_entityanddo_action(documented for sending mail). There is no read-only subset, so holding the token means holding write capability regardless of which tools are called.askandcall_functionalso delegate to an agent that can act.It gives prompt injection something to aim at. This server wraps everything a third party wrote in an untrusted-content fence precisely because mail, chat and transcripts are attacker-controllable. Without Work IQ the worst case is a false report; with it, an instruction smuggled into an email has an action available to it. The fencing is mitigation, not a guarantee.
Everything Work IQ returns is fenced, agent responses included.
ms_server_info
Server metadata: version, registered tools, and which environment variables are set.
Development
git clone https://github.com/StuMason/m365-mcp.git
cd m365-mcp
npm install
npm run build
npm testContributing
See CONTRIBUTING.md for details.
License
MIT - Stu Mason
Available Tools
17 toolsms_auth_statusConnection StatusA
Check Microsoft 365 connection status. If not connected, opens browser to sign in.
Inputs: no named parameters.
ms_briefDaily BriefARead-onlyIdempotent
One call that assembles a catch-up. With no arguments: today’s meetings, unread mail, recent chats, open tasks and yesterday’s meeting transcripts. With person: who they are and your recent mail and chats involving them. Use this instead of calling four or five tools separately.
Inputs: date, count, person.
ms_calendarCalendarARead-onlyIdempotent
Fetch the user's Microsoft 365 calendar events. Defaults to today if no date params given. Can also list calendars or drill down into a specific event.
Inputs: end, date, start, compact, +2 more.
ms_chatTeams ChatsARead-onlyIdempotent
Read the user's recent Microsoft Teams chats. Without chat_id lists recent chats; with chat_id returns messages from that chat.
Inputs: count, chat_id, members.
ms_filesOneDrive FilesCRead-onlyIdempotent
Browse or search the user's OneDrive files.
Inputs: path, count, search, shared, +1 more.
ms_insightsDocument InsightsARead-onlyIdempotent
Documents the user recently worked with or had shared with them, from Microsoft Graph item insights. Good for "what was I working on" and "what did someone send me" without knowing a filename. Defaults to recently used.
Inputs: kind, count.
ms_mailMailARead-onlyIdempotent
Read the user's recent emails from Microsoft 365. Without message_id: lists emails with preview text. With message_id: returns the full email body. Use folders: true to list mail folders, folder to read from a specific folder, attachments with message_id to list attachments, or filter for quick filters.
Inputs: count, filter, folder, search, +3 more.
ms_peoplePeople DirectoryARead-onlyIdempotent
Look people up in the organisation directory. Use search to resolve a name to an email address (the input ms_schedule needs), user to read one person’s details plus their manager and direct reports, or groups to list the groups and teams the signed-in user belongs to.
Inputs: user, count, groups, search.
ms_profileMy ProfileBRead-onlyIdempotent
Fetch the user's Microsoft 365 profile. Optionally include manager, reports, groups, or photo.
Inputs: include.
ms_scheduleFree/Busy ScheduleARead-onlyIdempotent
Check people's availability / free-busy status for a given time window. Accepts one or more email addresses and returns their schedule with time slots showing free, busy, tentative, out of office, or working elsewhere.
Inputs: emails (required), end, date, start, +1 more.
ms_searchSearch EverythingARead-onlyIdempotent
Search across Microsoft 365 in one call — mail, Teams chats, calendar events, OneDrive files and SharePoint. Use this when you do not already know where something lives; use the per-area tools (ms_mail, ms_chat, ms_files) when you do. Supports KQL, so "from:jane subject:budget" works.
Inputs: query (required), count, types.
ms_server_infoServer InfoARead-onlyIdempotent
Returns m365-mcp server metadata: version, available tools, and runtime info. Useful for debugging.
Inputs: no named parameters.
ms_tasksTo Do & PlannerARead-onlyIdempotent
Read Microsoft To Do and Planner tasks. Without parameters lists To Do task lists; with list_id returns the tasks in that list; with planner=true returns Planner tasks assigned to the user.
Inputs: count, list_id, planner, include_completed.
ms_teamsTeams & ChannelsARead-onlyIdempotent
Browse Microsoft Teams the user has joined. Without parameters lists joined teams; with team_id lists that team’s channels; with team_id + channel_id returns recent channel messages. Distinct from ms_chat, which covers private/group chats rather than team channels.
Inputs: count, team_id, channel_id, message_id.
ms_transcriptsMeeting TranscriptsARead-onlyIdempotent
Fetch meeting transcripts from Microsoft Teams. Without transcript_id: lists meetings with ~3000 char previews. With transcript_id: returns transcript content in chunks (default 10,000 chars). Use offset to paginate through long transcripts.
Inputs: end, date, start, length, +2 more.
ms_workiqWork IQADestructive
Reach the Microsoft Work IQ agent. Without parameters lists the tools Work IQ exposes; with question asks the agent directly; with entity_urls reads Graph paths using your own M365 permissions, which covers directory and channel lookups the other tools are refused. tool + arguments calls any Work IQ tool by name, including ones that create, update, delete or send. Not read-only.
Inputs: tool, question, arguments, entity_urls.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Tools are mostly partitioned by M365 surface (mail, chat, teams, calendar, files, SharePoint, tasks, people), and descriptions explicitly draw the tricky boundaries, e.g. ms_teams vs ms_chat and ms_search vs the per-area tools. The remaining soft spots are ms_search/ms_brief/ms_insights overlapping with the individual tools, and ms_workiq's directory lookups overlapping ms_people, but each is explained in-line so misselection risk is limited.
Every tool follows the same ms_<resource> convention with a uniform lowercase prefix and noun-based names. No mixed verb styles or casing, and the few compound names (ms_auth_status, ms_server_info) still fit the pattern. An agent can reliably infer tool names from the domain vocabulary.
17 tools is on the heavy side but justified by the breadth of Microsoft 365 (mail, calendar, Teams, files, SharePoint, tasks, people, search, composite helpers). No tool looks redundant enough to cut outright, though the composite helpers (ms_brief, ms_server_info, ms_workiq) push it toward the upper bound.
Read/lifecycle coverage is strong across nearly every M365 surface, plus cross-cutting search, item insights, and a catch-up composite. Write operations (send, create, update, delete, channel posts) have no dedicated tools and are only reachable through ms_workiq's generic pass-through, which is a real gap for agents needing mutation workflows but workable as an escape hatch.
Maintenance
Related MCP Connectors
Permissioned access to Outlook, OneDrive and Teams via the user's own Microsoft account
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Hosted MCP server for your Gmail, Outlook and IMAP mail, with mailboxes and scopes set per agent.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA production-ready MCP server that provides secure, delegated access to Microsoft 365 services including Email, SharePoint, OneDrive, and Calendar. It enables AI models to search messages, browse files, manage calendar events, and parse document contents using OAuth 2.1 authentication.MIT
- AlicenseCqualityNot gradedmaintenanceAn MCP server that enables interaction with Microsoft 365 services like Outlook, OneDrive, Teams, and SharePoint via the Microsoft Graph API. It supports comprehensive operations including email management, file access, and organizational collaboration for personal and work accounts.78-
- FlicenseNot gradedqualityBmaintenanceMCP server providing access to Microsoft Teams chats/channels, Outlook emails, calendar events, and SharePoint files via Microsoft Graph API.-
- AlicenseNot gradedqualityDmaintenanceRemote MCP server for Microsoft Graph with delegated OAuth support, enabling interaction with Microsoft 365 services like mail, calendar, OneDrive, SharePoint, Teams, and more via natural language.MIT