microsoft365-mcp-server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MS365_PRESETS | No | Load only selected areas: personal, collaboration, productivity, rag, or all. | |
| MS365_ORG_MODE | No | Set to true to expose the tools that need a work or school tenant. | false |
| MS365_AUTH_MODE | No | The sign-in mode: interactive, oauth-proxy, client-token, client-secret, or certificate. | interactive |
| MS365_CLIENT_ID | Yes | The application (client) ID of the Microsoft Entra ID app registration. | |
| MS365_READ_ONLY | No | Set to true to hide every tool that writes. | false |
| MS365_TENANT_ID | No | The Microsoft Entra tenant ID. Use common for multi-tenant/personal accounts, or a tenant ID to lock sign-in to one organization. | |
| MS365_CLIENT_SECRET | No | The client secret used for oauth-proxy hosting or client-secret automation. | |
| MS365_ENABLED_TOOLS | No | Load only the tools whose names match this regex. | |
| MS365_REQUIRE_DRAFT | No | Set to true to remove direct email sending; the assistant can only create drafts for review or approval with send_draft. | false |
| MS365_OAUTH_BASE_URL | No | The public base URL for oauth-proxy mode; required when hosting remotely with MS365_CLIENT_ID and MS365_CLIENT_SECRET. | |
| MS365_USE_DEVICE_CODE | No | Set to true on a headless machine to use device-code sign-in instead of opening a browser. | false |
| MS365_ALLOWED_MAILBOXES | No | Limit which other people's or shared mailboxes the server may open. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
A Microsoft 365 MCP server via Microsoft Graph API.
Available capabilities:
Authentication: Check auth status and manage tokens
Mail: List, read, send, reply, search, and draft email messages; edit and delete drafts
Calendar: List, view, create, update, and delete events; accept or decline invitations
Contacts: List, view, create, update, delete, search, and export contacts
Files: List, view, search, download OneDrive files; create folders; upload files (see Upload workflows below)
Documents: Extract readable text from PDF, DOCX, XLSX and text files — in OneDrive, SharePoint, or attached to a message
Chats: List Teams chats and messages; send chat messages, starting a chat by email if needed
Teams: List teams, channels, and messages; send channel messages and thread replies
Meetings: List Teams meeting transcripts and read their text
Users: View profiles and list users
Groups: List groups and group members
Planner: List plans and tasks; create and update tasks
OneNote: List notebooks, sections, pages; read page content
To Do: List and create task lists; list, create, update, and delete tasks, including repeating ones
Graph Query: Execute arbitrary Microsoft Graph API queries
Upload workflows:
Text content → upload_file (inline text, any transport)
Binary files from the server's local disk → upload_file_from_path (requires absolute path on this machine)
Binary files generated in a cloud container (e.g., claude.ai) → first save to the user's local filesystem using Desktop Commander's write_file, then call upload_file_from_path with that local path
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| logging | {} |
| prompts | {} |
| resources | {} |
| completions | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_auth_statusA | Get current authentication status, mode, and scopes |
| list_accountsB | List all registered accounts and show which is the default |
| switch_accountB | Switch the default account for subsequent tool calls |
| set_access_tokenB | Set or update the access token (client-token auth mode only) |
| list_messagesA | List email messages, newest first. Covers every folder (Inbox, Sent Items, Archive, ...) unless folder is set. Each line shows the sender's name and address, the received time, the Graph message ID and the internetMessageId. |
| scan_messagesA | Scan message headers compactly as ref|received|from|subject|flags. Scope with folder and narrow with filter or search. Pass refs to get_message, list_attachments, move_message or batch_move_messages. Both filter and search scans page using Graph nextLink cursors: when a result says INCOMPLETE, call scan_messages with the returned cursor alone until no cursor remains. A short or empty page can still have a continuation. Search returns at most 1,000 results, so use filter and exhaust its cursors when mailbox coverage matters. A header is not a message: open messages and attachments the subject cannot rule out. |
| get_messageA | Get a specific email message with full body content. Pass body_format:'text' for marketing or newsletter mail — Graph converts server-side, avoiding tens of thousands of characters of HTML and CSS. |
| list_mail_foldersA | List mail folders with item and unread counts, for resolving move destinations. Top-level folders only — a folder reporting subfolders has children this does not list. |
| list_attachmentsA | List a message's attachments with name, content type and size. Returns a read_document path for file attachments so their text can be extracted (PDF, Office, etc); cloud links and embedded Outlook items are marked as not readable that way. |
| move_messageA | Move a message to another mail folder. Destination accepts a well-known name (archive, deleteditems, inbox, junkemail), a top-level folder display name, or a folder ID. A well-known name always wins over a custom folder of the same name, and the confirmation says which was used. Subfolders cannot be resolved by name — pass their ID. Moving to deleteditems is recoverable; use list_mail_folders to see what exists. |
| batch_move_messagesA | Move several messages to the same folder in one call. Resolves the destination once and returns a single summary instead of one result per message. Reports any failures individually. |
| save_attachmentA | Save a mail attachment to a local file and return its path. Use for anything read_document cannot extract text from — scanned PDFs, photographed documents, images — and for handing a file to another tool. Read the saved file directly: PDFs and images are viewable without text extraction. Omit attachment_id when the message has exactly one attachment; otherwise get IDs from list_attachments. |
| summarize_sendersA | Count a folder's messages by sender, server-side, without listing them. Returns one row per sender (count, unread, first and last date, address, name, latest subject), most frequent first — the starting point for cleaning a large inbox: newsletters, promotions and notifications show up as a few hundred senders repeating. Reads every matching message in the folder (paged internally, up to ~50,000) so the counts are complete; only the summary is returned. Narrow with filter (OData, e.g. a receivedDateTime range) when only part of a folder matters. Use group_by: domain to see families of senders, then group_by: address to get the addresses move_messages_matching needs. |
| move_messages_matchingA | Move every message in a folder that matches a sender list and/or an OData filter — the bulk step of an inbox clean-up. Pass senders (addresses from summarize_senders) and/or filter; a whole folder with no condition is refused. Destination deleteditems is how to bulk-delete: it is reversible from Deleted Items, and a hard delete is deliberately not offered. SAFE BY DEFAULT: dry_run is true unless set to false. A dry run fetches the matching set and reports the count, date range, sender breakdown and newest subjects, moving nothing — read it before re-running with dry_run: false. A live run refuses to move more than limit messages (default 1000) so a mis-scoped filter cannot empty a folder; raise limit explicitly when the dry-run count is intended. Moves go through Graph JSON batching (20 per round-trip, throttling retried), so thousands of messages take seconds, not minutes, and no message IDs pass through the caller. |
| send_messageC | Send a new email message |
| send_replyA | Reply to the sender of an email and send immediately. Threads into the conversation and quotes the original. Use create_reply_draft to review before sending. |
| send_reply_allA | Reply to all recipients of an email and send immediately. Threads into the conversation and quotes the original. Use create_reply_all_draft to review before sending. |
| send_forwardA | Forward an email to new recipients and send immediately. Quotes the original. Use create_forward_draft to review before sending. |
| create_reply_draftA | Create a reply draft (to the sender) in the Drafts folder. Threads into the conversation with the original quoted underneath. Review, then send with send_draft. |
| create_reply_all_draftA | Create a reply-all draft (to all recipients) in the Drafts folder. Threads into the conversation with the original quoted underneath. Review, then send with send_draft. |
| create_forward_draftA | Create a forward draft in the Drafts folder with the original quoted underneath. Review, then send with send_draft. |
| search_messagesC | Search email messages |
| create_draftB | Create a new email draft in the Drafts folder |
| send_draftC | Send an existing email draft |
| update_draftA | Edit an unsent draft: its subject, body or recipients. Only fields you pass change. Refuses any message that is not a draft. Send it afterward with send_draft. |
| delete_draftA | Delete an unsent draft. Refuses any message that is not a draft. |
| list_calendarsA | List the calendars you can see: your own, and any shared with you. Returns each calendar's ID for the calendar_id parameter of the event tools, and marks the default calendar and any you cannot edit. |
| list_eventsA | List calendar event resources (/me/events). Returns series masters for recurring meetings, NOT individual occurrences. For 'what's on my calendar between X and Y' use list_calendar_view instead — it expands recurrences into instances. |
| list_calendar_viewA | List event instances on the calendar between start_date_time and end_date_time. Expands recurring series into individual occurrences (unlike list_events which returns series masters). Use this for 'what's on my calendar this week'. |
| find_meeting_availabilityA | Find meeting time suggestions where all participants are free, ranked by confidence. Searches between after_date_time and before_date_time for a slot of duration_minutes. Read-only: suggests times only — use create_event to book one. |
| get_eventB | Get detailed information about a calendar event. The body comes back as plain text by default; a Teams invite's text still includes its join link and any meeting ID and passcode. |
| create_eventC | Create a new calendar event |
| update_eventC | Update an existing calendar event |
| delete_eventC | Delete a calendar event |
| respond_to_eventA | Accept, decline or tentatively accept a meeting invitation. By default the organizer gets the response by email, with the comment if one is given. |
| list_contactsC | List contacts |
| get_contactC | Get detailed contact information |
| create_contactC | Create a new contact |
| update_contactA | Update fields on an existing contact. Only the fields passed are changed. List fields (email_addresses, business_phones, home_phones, categories) REPLACE the whole list — read the contact first and pass the complete new list; an empty list clears it. |
| delete_contactA | Delete a contact. Intended for duplicates: first copy anything the duplicate holds that the kept contact lacks (emails, phones, notes, birthday) onto the kept contact with update_contact, then delete. Returns the deleted contact's details so they are not lost from the conversation. |
| search_contactsB | Search contacts by name or email |
| export_contactsA | Export every contact in the signed-in mailbox to a local JSON file and return its path. Covers the default Contacts folder and every contact folder beneath it, with all fields (emails, phones, addresses, categories, birthday, notes, folder path). Use this to reconcile or bulk-process contacts; use list_contacts or search_contacts to look one up. |
| list_drive_itemsC | List files and folders in OneDrive |
| get_drive_itemC | Get file or folder metadata |
| search_filesA | Search OneDrive/SharePoint files. Search results show folders without item counts or sizes, which search does not report; use list_drive_items or get_drive_item for those. |
| download_fileA | Get a file's metadata and download URL. Returns content inline for text files under 100KB. For a SharePoint file, pass drive_id as well — without it the item is looked up in your own OneDrive and will not be found. For readable text from PDF/DOCX/XLSX, use read_document instead; come here when extraction fails (scanned PDFs, unsupported types, files over the extraction cap) or you need raw bytes. |
| read_documentA | Download a file from SharePoint or OneDrive and return its readable text content. Supports DOCX, PDF, XLSX, and text-based files. Use instead of download_file when you need document contents. Pair with search_site_files (SharePoint) or search_files (OneDrive) to get IDs, then pass /drives/{driveId}/items/{itemId}/content or /me/drive/items/{id}/content. Text extraction only, no OCR: scanned PDFs return no text — for those, and for images, use save_attachment and read the file. |
| create_folderC | Create a new folder in OneDrive |
| upload_fileA | Upload TEXT content (plain text, markdown, CSV, JSON, HTML, XML) to OneDrive inline via this tool call. For binary files (docx, pdf, images, etc.), use get_upload_config (HTTP/SSE) or upload_file_from_path (stdio/local) — never base64-encode binary into this tool's content param. Max ~4 MB text. |
| upload_file_from_pathA | Upload a local file to OneDrive by reading it from disk on the server. The file must exist on this machine's filesystem. If you generated the file in a cloud container (e.g., claude.ai), first use Desktop Commander's write_file to save it to the user's local filesystem, then call this tool with that local path. Supports files up to 250 MB (chunked session upload above 4 MB). Intermediate folders are auto-created. |
| list_sitesA | List SharePoint sites. Without a query, returns followed sites. With a query, searches all sites. |
| get_siteC | Get SharePoint site details |
| list_site_drivesB | List document libraries (drives) in a SharePoint site |
| list_site_itemsB | List files and folders in a SharePoint site's document library |
| search_site_filesA | Search files within a SharePoint site. Search results show folders without item counts or sizes, which search does not report; use list_drive_items or get_drive_item for those. |
| list_chatsA | List your Teams chats (1:1, group, and meeting chats), most recent message first. Each line names the chat by its topic or its members and shows when the last message was sent and by whom. Note: the self-chat (notes to self) is not listed here — use chat_id '48:notes' to send to it directly. |
| list_chat_messagesA | List messages in a Teams chat, newest first. Each message is a line '- () [You] [App] [Urgent|High importance] [Mentions you] (ID: )' (flags only when they apply), followed by its text on a ' > ' line. System events (joins, renames) and deleted messages are left out. |
| send_chat_messageA | Send a Teams chat message, either in an existing chat (chat_id) or to people by email (to). With to, one person reuses your one-on-one chat with them, or starts it; two or more start a new group chat every call, so reuse the returned chat_id for follow-ups. Use chat_id '48:notes' to send to the user's self-chat (notes to self). |
| list_teamsB | List teams you are a member of |
| list_channelsC | List channels in a team |
| list_channel_messagesC | List recent messages in a channel |
| send_channel_messageB | Send a message to a Teams channel, or reply in a thread with reply_to_message_id |
| list_meeting_transcriptsA | List the transcripts of a Teams meeting. Identify the meeting by meeting_id, or by join_web_url taken from a calendar event's onlineMeeting.joinUrl. Returns transcript IDs for get_meeting_transcript. |
| get_meeting_transcriptA | Get the text of one Teams meeting transcript, as timestamped WebVTT utterances. Works for attendees, not just the organizer. Falls back to a speaker-less transcript automatically when the tenant has speaker attribution disabled. |
| get_meB | Get the authenticated user's profile |
| list_usersC | List users in the organization |
| get_userC | Get a specific user's profile |
| list_groupsB | List groups in the organization |
| get_groupC | Get detailed group information |
| list_group_membersC | List members of a group |
| list_plansA | List all Planner plans visible to you, aggregated across your group memberships |
| list_planner_tasksC | List tasks in a Planner plan |
| get_planner_taskC | Get detailed Planner task information |
| list_planner_bucketsA | List the buckets (columns) in a Planner plan. Use a bucket ID with create_planner_task. |
| create_planner_bucketC | Create a new bucket (column) in a Planner plan |
| create_planner_taskC | Create a new Planner task |
| update_planner_taskA | Update a Planner task (title, percent_complete — 100 closes it — due date, priority). The ETag is auto-fetched if omitted; pass one only to enforce optimistic concurrency. |
| update_planner_task_detailsA | Update a Planner task's details: description, checklist items, and references (links). The ETag is fetched automatically. Add, update, or remove entries — updates merge (omitted fields keep their current value); update/remove of a missing item is reported as skipped, not a silent no-op. Checklist items are addressed by their GUID (from get_planner_task); references by their URL. |
| list_onenote_notebooksC | List OneNote notebooks |
| list_onenote_sectionsC | List sections in a OneNote notebook |
| list_onenote_pagesC | List pages in a OneNote section |
| get_onenote_page_contentB | Get OneNote page content as HTML |
| create_onenote_pageA | Create a OneNote page in a section. Content is HTML — OneNote supports a constrained subset and silently drops unsupported CSS/tags. |
| update_onenote_page_contentB | Append to or modify a OneNote page's content without rewriting it. Targets an element (default 'body') and applies an action. Content is HTML. |
| create_onenote_sectionC | Create a new section in a OneNote notebook |
| create_onenote_notebookC | Create a new OneNote notebook |
| copy_onenote_pageB | Copy a OneNote page to another section. Runs asynchronously in OneNote. |
| delete_onenote_pageA | Delete a OneNote page. This cannot be undone via the API. |
| list_todo_listsC | List Microsoft To Do task lists |
| create_todo_listA | Create a new To Do list. Graph cannot share a list — the new list is private until someone shares it in the To Do app |
| delete_todo_listA | Delete a To Do list and every task in it. There is no API to restore it, so treat it as permanent. A list that still holds tasks needs force: true. The built-in Tasks and Flagged Emails lists can't be deleted. |
| list_todo_tasksA | List tasks in a To Do list, or what changed in it since your last call. For changes, call once with delta: true, which returns every task and a 'Delta token: …' line; keep the token and pass it as delta_token next time to get only the tasks added, changed or removed since (removed ones as 'Removed: ()' lines), and a new token. Completing a repeating task makes Graph keep the series and split off the finished occurrence as a new, already-completed task with a new id, so an unseen completed task is a done occurrence, not new work. Your own writes come back as changes too. The Flagged Emails list (wellknownListName flaggedEmails) holds the emails flagged in Outlook; each of its tasks carries (Mail: ), the id the mail tools use, when its Outlook link parses |
| create_todo_taskA | Create a new To Do task, optionally recurring. With linked_resource, the task is tagged with its source, and a create whose external_id is already on a task in the list returns that task instead of a second copy, so a retry is safe. That check reads the whole list first |
| update_todo_taskC | Update a To Do task |
| set_todo_task_stateA | Set only a To Do task's status, importance and your own extension fields, for unattended use. It can't change the title, notes, dates or repeat pattern, or delete. The same call twice changes nothing more, so a failed call is safe to repeat. Completing a repeating task is refused; use update_todo_task. Complete only tasks you created, and change importance only on tasks carrying your extension, so the person's own choices are never overwritten |
| delete_todo_taskA | Delete a To Do task. There is no API to restore it, so treat it as permanent. Deleting a repeating task ends the whole series and needs force: true. |
| graph_queryA | Execute an arbitrary Microsoft Graph API query. Use this for operations not covered by other tools. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 97 tools
The set covers many distinct M365 workloads, but several tools overlap heavily: list_messages, scan_messages, search_messages, and summarize_senders all operate on mail, while download_file, read_document, get_drive_item, and search_files overlap in file access. Descriptions usually clarify when to use each, but the sheer number of near-neighbors makes misselection likely.
Names are uniformly snake_case and almost always follow a verb_noun pattern such as list_messages, create_event, update_todo_task, and search_site_files. Variants like graph_query and get_me are minor exceptions but do not break the overall convention.
97 tools is far too many for reliable agent selection, even for a broad Microsoft 365 server. The surface covers many domains, but operations could be consolidated or grouped to reduce context burden and selection error.
Coverage is broad across mail, calendar, contacts, OneDrive, SharePoint, Teams, Planner, OneNote, To Do, users/groups, and auth, with graph_query as an escape hatch. Some lifecycle gaps remain, such as file/folder delete or move, planner task deletion, and team/channel creation, but core workflows are covered.