io.github.nitin27may/ms-graph-mcp

Ask Microsoft Graph to suggest meeting times when the given attendees are free, ranked by how likely everyone is to attend. Returns candidate slots with a confidence percentage and per-attendee availability. This reads calendars and books nothing — pass a chosen slot to calendar_create_event to actually schedule it. Requires Calendars.Read.Shared.

Get one calendar event in full by its id: subject, times, organiser, location, agenda preview, the Teams join URL and the complete attendee list with each person's response status. Takes an event id from calendar_list_upcoming_events or calendar_list_events_in_range. Use calendar_get_event_attendees when only the attendee list is needed. Requires Calendars.Read.

List who was invited to a calendar event and how each person replied — accepted, declined, tentative or no response. Returns email, display name and response status per attendee. Use this when the question is about who is coming; calendar_get_event returns the same list alongside the event's other detail. Requires Calendars.Read.

Look up whether people are free or busy across a time window, without seeing what their meetings are. Returns per-person busy periods and a slot-by-slot free/tentative/busy/out of office breakdown. Use to answer 'when is X available'; calendar_find_meeting_times is better when the goal is a slot that suits a whole group. Requires Calendars.ReadBasic.

List calendar events between two dates, in chronological order. Use for any window that is not simply 'the next few days' — last week's meetings, a specific month, or a range the user names. Dates are ISO 8601 (2026-01-15) and the whole of both end days is included. Returns id, subject, times and organiser. Requires Calendars.Read.

List the signed-in user's upcoming calendar events for the next N days, soonest first. Returns id, subject, start and end times, organiser and whether it is online. This is the tool for 'what's on my calendar'. Use calendar_list_events_in_range for a specific window, and calendar_get_event for full detail including the join URL. Requires Calendars.Read.

Read the text content of a file in OneDrive or SharePoint, given a drive id and item id from files_search or files_list_recent. Works for text, Office documents and PDFs; binary files return a placeholder instead of bytes. Output is truncated to a caller-specified character limit. Requires Files.Read.All.

Get the document library backing a Microsoft 365 group or Teams team, given a group id from directory_search_groups. Returns the drive id and web URL, which is what the other file tools need to read or write inside a team's shared files. Requires Files.Read.All and Group.Read.All.

List files the signed-in user has recently opened or edited, most recent first. Returns id, name, drive id and web URL. Use for 'the document I was working on yesterday' — files_search is better when the name or a keyword is known, and files_list_trending covers what colleagues are working on. Requires Files.Read.

List files other people have shared directly with the signed-in user, with the owner and web URL for each. Covers items shared via OneDrive or SharePoint that do not live in the user's own drive, which is why files_list_recent and files_search may not surface them. Requires Files.Read.All.

List documents currently trending around the signed-in user — files their colleagues are actively working on, ranked by Microsoft 365 activity signals rather than by the user's own history. Use for 'what is the team working on'. files_list_recent is the tool for what this user personally touched. Requires Files.Read.All.

Search the signed-in user's OneDrive and the SharePoint sites they can reach, by filename or content keyword. Returns id, name, drive id, size, last-modified date and web URL. OneDrive and SharePoint document libraries are the same underlying resource, so one search covers both. Requires Files.Read.All.

Read every message in one email conversation, oldest first, given a conversation id from any of the mail listing tools. Returns full message bodies rather than previews, so it is the tool for understanding what was actually discussed before replying or summarising. Requires Mail.Read.

List the file attachments on one email — name, content type and size in bytes. Returns metadata only and never file contents, so it is safe to call on messages with very large attachments. Inline images such as signature logos are excluded. Requires Mail.Read.

List emails the signed-in user has flagged for follow-up, newest first. Returns id, subject, sender, date and preview. Flags are the user's own marker for 'come back to this', so use it for 'what do I still need to deal with' rather than mail_list_recent, which returns everything regardless of state. Requires Mail.Read.

List the signed-in user's most recent emails from the last N days, newest first. Returns id, subject, sender, date and a preview snippet. Use for 'what came in today' or catching up after time away; mail_search is the tool when specific keywords or a sender are known. Requires Mail.Read.

Search the signed-in user's mailbox by keyword, subject or sender name. Returns id, subject, sender, date and a preview snippet, newest first. Searchable folders are inbox, sentitems, drafts, or all. Use mail_list_recent when the ask is time-based rather than keyword-based, and mail_get_thread to read a whole conversation. Requires Mail.Read.

Look up one person in the organisation by their exact email address and return their profile: display name, job title, department, office location and phone numbers. Use when the address is already known — people_search is the tool for finding someone by partial or approximate name. Fails if the address does not belong to a tenant account. Requires User.Read.All.

Get the signed-in user's own profile — their name, email address, job title, department and office. Call this first when a request says 'me', 'my' or 'I' and the user's own identity or email address is needed to answer it, for example before filtering a calendar or addressing a message. Takes no arguments. Requires User.Read.

List the signed-in user's saved Outlook contacts, with names, email addresses and phone numbers. This is the user's personal address book and is the only place external contacts live — people with no account in the tenant, invisible to people_search and directory_search_users. Use it for phone numbers. Requires Contacts.Read.

Find colleagues the signed-in user actually works with, ranked by relevance from their own mail and meeting history — so it finds the right 'Priya' without exact spelling. Returns name, email, title and department. Use directory_search_users to search the whole tenant instead, or people_list_contacts for the saved address book. Requires People.Read.

Search the signed-in user's saved Outlook contacts by name or company, returning emails and phone numbers. Searches the personal address book only — use people_search for colleagues the user works with, or directory_search_users to search the whole tenant. This is the one that finds external contacts. Requires Contacts.Read.

Search across Microsoft 365 in one call — email, calendar events, files, SharePoint sites and lists, and people. Best first move for a vague request, since it spans workloads no other single tool covers. Supports KQL such as 'budget filetype:xlsx'. Each entity type needs its own permission. Requires Mail.Read, Calendars.Read, Files.Read.All, Sites.Read.All and People.Read.