Summary
A comprehensive personal Outlook integration via Microsoft Graph API with 62 tools spanning mail, calendar, contacts, to-do lists, and drafts. Supports all the operations you'd expect: reading and searching messages, managing Focused Inbox classification, sending and replying to mail, creating calendar events with recurring expansion, CRUD on contacts and tasks, plus batch operations and attachment handling including large file upload sessions. Designed for personal Microsoft accounts only (Outlook.com, Hotmail, Live), not Entra ID work accounts. You bring your own Azure app registration, tokens live in your OS keyring, and there's optional read-only mode plus granular category permissions. Built for agent builders who need typed MCP tool schemas instead of parsing CLI stdout.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
51 tools
OUTLOOK_ADD_EVENT_ATTACHMENTAdds an attachment to a specific Outlook calendar event. Use when you need to attach a file or nested item to an existing event.6 params
Adds an attachment to a specific Outlook calendar event. Use when you need to attach a file or nested item to an existing event.
Parameters* required
itemobjectThe nested item payload; required when '@odata.type' is itemAttachment.
namestringThe display name of the attachment.
user_idstringThe user's email address or 'me' for the authenticated user.default: me
event_idstringThe unique identifier of the calendar event to which the attachment will be added.
odata_typestringAttachment type: '#microsoft.graph.fileAttachment' requires 'contentBytes'; '#microsoft.graph.itemAttachment' requires 'item'.one of
#microsoft.graph.fileAttachment · #microsoft.graph.itemAttachmentcontentBytesstringBase64-encoded file contents; required when '@odata.type' is fileAttachment.
OUTLOOK_ADD_MAIL_ATTACHMENTTool to add an attachment to an email message. Use when you have a message ID and need to attach a small (<3 MB) file or reference.10 params
Tool to add an attachment to an email message. Use when you have a message ID and need to attach a small (<3 MB) file or reference.
Parameters* required
itemobjectEmbedded item (e.g., message, event) for itemAttachment; must include its own '@odata.type'.
namestringDisplay name of the attachment (e.g., file name).
user_idstringThe user's principal name or 'me' for the authenticated user.default: me
isInlinebooleanSet to true if the attachment should appear inline in the message body.
contentIdstringContent ID for inline attachments, used in HTML body references.
message_idstringUnique identifier of the email message to attach to.
odata_typestringThe OData type of the attachment. For file attachments, use '#microsoft.graph.fileAttachment'.
contentTypestringMIME type of the attachment (e.g., 'application/pdf').
contentBytesstringBase64-encoded content of the file attachment (max size 3 MB).
contentLocationstringURL location or path for reference attachments.
OUTLOOK_CALENDAR_CREATE_EVENTCreates a new Outlook calendar event, ensuring `start_datetime` is chronologically before `end_datetime`.13 params
Creates a new Outlook calendar event, ensuring `start_datetime` is chronologically before `end_datetime`.
Parameters* required
bodystringThe body of the event. This can be in plain text or HTML format, as specified by the 'is_html' field.
is_htmlbooleanSpecifies whether the 'body' content is HTML. Set to true for HTML content; otherwise, it's treated as plain text.default: false
show_asstringThe status to show on the calendar for the duration of the event. Valid values are: 'free', 'tentative', 'busy', 'oof' (out of office), 'workingElsewhere', 'unknown'.default: busy
subjectstringThe subject of the calendar event.
user_idstringThe UPN (User Principal Name) or object ID of the user whose calendar the event will be created in. Use 'me' for the currently authenticated user.default: me
locationstringThe physical location of the event.default:
time_zonestringThe time zone for the start and end times of the event. Uses Windows time zone names (e.g., 'Pacific Standard Time') or IANA time zone names (e.g., 'America/Los_Angeles'). UTC is also a valid input.
categoriesarrayA list of categories associated with the event. These categories must already exist in the user's mailbox.
end_datetimestringThe end date and time of the event in ISO 8601 format. Time zone is specified in 'time_zone'.
attendees_infoarrayA list of attendees for the event. Each attendee object requires an 'email'. 'name' and 'type' ('required', 'optional', 'resource') are optional.
start_datetimestringThe start date and time of the event in ISO 8601 format. Time zone is specified in 'time_zone'.
is_online_meetingbooleanSet to true to indicate that the event is an online meeting. This will automatically generate an online meeting link if 'online_meeting_provider' is set (e.g., a Microsoft Teams link).default: false
online_meeting_providerstringSpecifies the online meeting provider. Currently, only 'teamsForBusiness' is supported. If 'is_online_meeting' is true and this is set, a meeting link for the provider will be created.
OUTLOOK_CREATE_ATTACHMENT_UPLOAD_SESSIONTool to create an upload session for large (>3 MB) message attachments. Use when you need to upload attachments in chunks.3 params
Tool to create an upload session for large (>3 MB) message attachments. Use when you need to upload attachments in chunks.
Parameters* required
user_idstringUser ID or user principal name; use 'me' for the signed-in user.default: me
message_idstringThe unique identifier of the message to attach to.
attachmentItemobjectAttachmentItem object describing the attachment in the upload session.
OUTLOOK_CREATE_CALENDARTool to create a new calendar in the signed-in user's mailbox. Use when organizing events into a separate calendar.4 params
Tool to create a new calendar in the signed-in user's mailbox. Use when organizing events into a separate calendar.
Parameters* required
namestringThe display name of the new calendar.
colorstringThe theme color to assign to the calendar. Supported values: auto, lightBlue, lightGreen, lightOrange, lightGray, lightYellow, lightTeal, lightPink, lightBrown, lightPurple, lightRed.one of
auto · lightBlue · lightGreen · lightOrange · lightGray · lightYellowuser_idstringThe UPN (User Principal Name) or object ID of the user where the calendar will be created. Use 'me' for the signed-in user.default: me
hexColorstringAn optional hexadecimal color code for the calendar in the format '#RRGGBB'.
OUTLOOK_CREATE_CONTACTCreates a new contact in a Microsoft Outlook user's contacts folder.15 params
Creates a new contact in a Microsoft Outlook user's contacts folder.
Parameters* required
notesstringPersonal notes about the contact. These notes are stored as 'personalNotes' in the Outlook contact details.default:
surnamestringThe contact's surname (last name).default:
user_idstringIdentifier for the user whose contact list will be modified. Use 'me' for the authenticated user, or provide the user's principal name (e.g., 'user@example.com').default: me
birthdaystringThe contact's birthday in 'YYYY-MM-DD' format. The time component will be set to midnight UTC (e.g., '1990-01-01' becomes '1990-01-01T00:00:00Z' in the API request).default:
jobTitlestringThe contact's job title.default:
givenNamestringThe contact's given (first) name.default:
homePhonestringThe contact's home phone number. If provided, this will be stored in Outlook as a list containing this single number.default:
categoriesarrayA list of categories to assign to the contact.
departmentstringThe department the contact belongs to within their company.default:
companyNamestringThe name of the company the contact is associated with.default:
displayNamestringThe contact's display name, typically their full name.default:
mobilePhonestringThe contact's mobile phone number.default:
businessPhonesarrayA list of business phone numbers for the contact. Each number should be a string.
emailAddressesarrayA list of email addresses for the contact.
officeLocationstringThe contact's office location.default:
OUTLOOK_CREATE_CONTACT_FOLDERTool to create a new contact folder in the user's mailbox. Use when needing to organize contacts into custom folders.3 params
Tool to create a new contact folder in the user's mailbox. Use when needing to organize contacts into custom folders.
Parameters* required
user_idstringThe user's principal name or object ID. Use 'me' for the authenticated user.default: me
displayNamestringThe display name of the new contact folder.
parentFolderIdstringThe ID of the parent contact folder. If omitted, created under the default contacts folder.
OUTLOOK_CREATE_DRAFTCreates an Outlook email draft with subject, body, recipients, and an optional attachment. Supports creating drafts as part of existing conversation threads by specifying a conversationId; attachments require a name, mimetype, and content.8 params
Creates an Outlook email draft with subject, body, recipients, and an optional attachment. Supports creating drafts as part of existing conversation threads by specifying a conversationId; attachments require a name, mimetype, and content.
Parameters* required
bodystringContent of the email draft; use `is_html` to specify if HTML or plain text.
is_htmlbooleanSpecifies if the `body` is HTML. If `False`, `body` is plain text.default: false
subjectstringSubject line for the email draft.
attachmentstringOptional file to attach. If provided, must include the file's content, name, and mimetype.
cc_recipientsarrayOptional list of CC (carbon copy) recipient email addresses.
to_recipientsarrayList of primary 'To' recipient email addresses.
bcc_recipientsarrayOptional list of BCC (blind carbon copy) recipient email addresses.
conversation_idstringOptional conversation ID to create the draft as part of an existing email conversation thread. If provided, the draft will be part of the specified conversation instead of starting a new one.
OUTLOOK_CREATE_DRAFT_REPLYCreates a draft reply in the specified user's Outlook mailbox to an existing message (identified by a valid `message_id`), optionally including a `comment` and CC/BCC recipients.5 params
Creates a draft reply in the specified user's Outlook mailbox to an existing message (identified by a valid `message_id`), optionally including a `comment` and CC/BCC recipients.
Parameters* required
commentstringPlain text comment to include in the body of the reply draft.
user_idstringUser's mailbox identifier (email or 'me') for the original message and new draft location.default: me
cc_emailsarrayList of email addresses to add as CC recipients to the draft reply.
bcc_emailsarrayList of email addresses to add as BCC recipients to the draft reply.
message_idstringUnique ID of the message to reply to, typically obtained from actions like 'List Messages' or 'Get Message'.
OUTLOOK_CREATE_EMAIL_RULECreate email rule filter with conditions and actions5 params
Create email rule filter with conditions and actions
Parameters* required
actionsobjectActions to take when the rule conditions are met.
sequenceintegerOrder in which the rule is executed (lower numbers execute first).default: 1
isEnabledbooleanWhether the rule is enabled.default: true
conditionsobjectConditions that must be met for the rule to apply.
displayNamestringDisplay name for the email rule.
OUTLOOK_CREATE_MAIL_FOLDERTool to create a new mail folder. Use when you need to organize email into a new folder.3 params
Tool to create a new mail folder. Use when you need to organize email into a new folder.
Parameters* required
user_idstringIdentifier for the user whose mailbox the folder will be created in. Use 'me' for the authenticated user or provide the user's principal name or ID.default: me
isHiddenbooleanIndicates whether the new folder is hidden. Default is false. Once set, this property cannot be updated.default: false
displayNamestringThe display name of the new mail folder.
OUTLOOK_CREATE_MASTER_CATEGORYTool to create a new category in the user's master category list. Use after selecting a unique display name.2 params
Tool to create a new category in the user's master category list. Use after selecting a unique display name.
Parameters* required
colorstringA pre-set color constant for the category. Allowed values: preset0 through preset24.one of
preset0 · preset1 · preset2 · preset3 · preset4 · preset5displayNamestringUnique name that identifies the category in the user's mailbox.
OUTLOOK_DELETE_CONTACTPermanently deletes an existing contact, using its `contact_id` (obtainable via 'List User Contacts' or 'Get Contact'), from the Outlook contacts of the user specified by `user_id`.2 params
Permanently deletes an existing contact, using its `contact_id` (obtainable via 'List User Contacts' or 'Get Contact'), from the Outlook contacts of the user specified by `user_id`.
Parameters* required
user_idstringThe UPN (User Principal Name) or ID of the user; use 'me' for the signed-in user.default: me
contact_idstringIdentifier of the contact to be deleted, typically obtained from 'List User Contacts' or 'Get Contact'.
OUTLOOK_DELETE_EMAIL_RULEDelete an email rule1 params
Delete an email rule
Parameters* required
ruleIdstringID of the email rule to delete.
OUTLOOK_DELETE_EVENTDeletes an existing calendar event, identified by its unique `event_id`, from a specified user's Microsoft Outlook calendar, with an option to send cancellation notifications to attendees.3 params
Deletes an existing calendar event, identified by its unique `event_id`, from a specified user's Microsoft Outlook calendar, with an option to send cancellation notifications to attendees.
Parameters* required
user_idstringUser's email address or 'me' for the current user.default: me
event_idstringUnique identifier of the calendar event to delete, typically obtained from event listing or retrieval actions.
send_notificationsbooleanIf `True`, sends cancellation notifications to event attendees upon deletion.default: true
OUTLOOK_DELETE_MAIL_FOLDERDelete a mail folder from the user's mailbox. Use when you need to remove an existing mail folder.2 params
Delete a mail folder from the user's mailbox. Use when you need to remove an existing mail folder.
Parameters* required
user_idstringIdentifier for the user whose mailbox contains the folder to delete. Use 'me' for the authenticated user or provide the user's principal name or ID.default: me
folder_idstringThe unique identifier or well-known name of the mail folder to delete (e.g., folder ID or 'Drafts', 'SentItems').
OUTLOOK_DOWNLOAD_OUTLOOK_ATTACHMENTDownloads a specific file attachment from an email message in a Microsoft Outlook mailbox; the attachment must contain 'contentBytes' (binary data) and not be a link or embedded item.4 params
Downloads a specific file attachment from an email message in a Microsoft Outlook mailbox; the attachment must contain 'contentBytes' (binary data) and not be a link or embedded item.
Parameters* required
user_idstringThe user's UPN (User Principal Name) or 'me' for the authenticated user. This identifies the mailbox where the message is located.default: me
file_namestringThe desired filename for the downloaded attachment. This name will be assigned to the `FileDownloadable` object.
message_idstringThe unique identifier of the email message that contains the attachment to be downloaded. This ID is typically obtained when listing or retrieving messages.
attachment_idstringThe unique identifier of the attachment to be downloaded. This ID is typically obtained from the message's details when an email message object is retrieved.
OUTLOOK_GET_CALENDAR_VIEWGet events ACTIVE during a time window (includes multi-day events). Use for "what's on my calendar today/this week" or availability checks. Returns events overlapping the time range. For keyword search or filters by category, use OUTLOOK_LIST_EVENTS instead.7 params
Get events ACTIVE during a time window (includes multi-day events). Use for "what's on my calendar today/this week" or availability checks. Returns events overlapping the time range. For keyword search or filters by category, use OUTLOOK_LIST_EVENTS instead.
Parameters* required
topintegerMaximum number of events to retrieve. Default is 100.default: 100
selectarrayList of specific event properties to return (e.g., ['subject', 'start', 'end']). If omitted, returns default properties.
user_idstringEmail address of the target user (or 'me' for authenticated user).default: me
timezonestringIANA or Windows timezone for event times (e.g., 'America/New_York'). Defaults to UTC.default: UTC
calendar_idstringOptional ID of a specific calendar to query. If not provided, uses the primary calendar. Get calendar IDs using LIST_CALENDARS action.
end_datetimestringEnd of the time window in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Events active during this window will be returned.
start_datetimestringStart of the time window in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Events active during this window will be returned.
OUTLOOK_GET_CONTACTRetrieves a specific Outlook contact by its `contact_id` from the contacts of a specified `user_id` (defaults to 'me' for the authenticated user).2 params
Retrieves a specific Outlook contact by its `contact_id` from the contacts of a specified `user_id` (defaults to 'me' for the authenticated user).
Parameters* required
user_idstringUser's principal name (e.g., 'AdeleV@contoso.onmicrosoft.com') or 'me' for the authenticated user. Using 'me' is recommended for accessing one's own contacts.default: me
contact_idstringUnique identifier for the contact within the specified user's Outlook address book.
OUTLOOK_GET_CONTACT_FOLDERSTool to retrieve a list of contact folders in the signed-in user's mailbox. Use after authentication when you need to browse or select among contact folders.7 params
Tool to retrieve a list of contact folders in the signed-in user's mailbox. Use after authentication when you need to browse or select among contact folders.
Parameters* required
topintegerMaximum number of contact folders to return.
skipintegerNumber of contact folders to skip for pagination.
expandarrayRelated entities to expand inline, e.g., ['contacts'].
filterstringOData filter expression, e.g., startswith(displayName,'A').
selectarrayList of properties to include in the response, e.g., ['id','displayName'].
orderbyarrayList of properties to order results by, e.g., ['displayName asc'].
user_idstringUser principal name or ID. Use 'me' for the authenticated user.default: me
OUTLOOK_GET_EVENTRetrieves the full details of a specific calendar event by its ID from a user's Outlook calendar, provided the event exists.2 params
Retrieves the full details of a specific calendar event by its ID from a user's Outlook calendar, provided the event exists.
Parameters* required
user_idstringThe user's primary SMTP address, user principal name (UPN), or the alias 'me' (for the signed-in user) to identify the calendar owner.default: me
event_idstringThe unique identifier of the calendar event to retrieve.
OUTLOOK_GET_MAILBOX_SETTINGSTool to retrieve mailbox settings. Use when you need to view settings such as automatic replies, time zone, and working hours for the signed-in or specified user.3 params
Tool to retrieve mailbox settings. Use when you need to view settings such as automatic replies, time zone, and working hours for the signed-in or specified user.
Parameters* required
expandarrayOData $expand query to include related entities.
selectarrayOData $select query to specify mailbox settings properties to include.
user_idstringThe user's unique identifier or principal name. Use 'me' for the signed-in user.default: me
OUTLOOK_GET_MAIL_DELTARetrieve incremental changes (delta) of messages in a mailbox. FIRST RUN: Returns ALL messages in folder (use top=50 to limit). Response has @odata.deltaLink. SUBSEQUENT: Pass stored deltaLink to get only NEW/UPDATED/DELETED messages since last sync. Properties available: id,...7 params
Retrieve incremental changes (delta) of messages in a mailbox. FIRST RUN: Returns ALL messages in folder (use top=50 to limit). Response has @odata.deltaLink. SUBSEQUENT: Pass stored deltaLink to get only NEW/UPDATED/DELETED messages since last sync. Properties available: id,...
Parameters* required
topintegerMaximum number of items to return per page. For first run without delta_token, use top=50 or top=100 to limit results. First delta call without token returns all messages in folder. Paginate through results using @odata.nextLink, then store @odata.deltaLink for next sync.
expandarrayList of related entities to expand (e.g. ['attachments']).
selectarrayList of message properties to include (e.g. ['subject','receivedDateTime']). Delta sync has property limitations due to response size constraints. Not available in delta: internetMessageHeaders, body (full), attachments (full content). Available: id, subject, from, toRecipients, ccRecipients, bccRecipients, receivedDateTime, sentDateTime, isRead, isDraft, importance, hasAttachments, categories, conversationId, flag, webLink, bodyPreview (first 255 chars).
user_idstringUser identifier: 'me' for the signed-in user or the user's email/UPN.default: me
folder_idstringMail folder identifier to scope the delta query to that folder (e.g., 'Inbox' or folder ID GUID). Defaults to Inbox when omitted.
skip_tokenstringSkip token for paging through large result sets during initial sync. Automatically provided in response '@odata.nextLink' when there are more results. Extract from nextLink URL and pass here for next page. Keep paginating until you receive '@odata.deltaLink' instead of nextLink.
delta_tokenstringDelta token from a previous call to get only changes since that state. If delta_token is not provided, the API returns all messages in the folder (initial sync). Use top parameter (e.g., top=50) on first run to limit results. Response includes @odata.deltaLink - extract and store this for next call to get only new changes. Subsequent calls with deltaLink return only: new messages, updated messages, deleted message IDs.
OUTLOOK_GET_MAIL_TIPSTool to retrieve mail tips such as automatic replies and mailbox full status. Use when you need to check recipient status before sending mail.3 params
Tool to retrieve mail tips such as automatic replies and mailbox full status. Use when you need to check recipient status before sending mail.
Parameters* required
user_idstringUser principal name (UPN) or 'me' for the signed-in user.default: me
EmailAddressesarrayCollection of SMTP addresses of recipients to get MailTips for.
MailTipsOptionsarrayList of mail tip types to retrieve for each recipient.
OUTLOOK_GET_MASTER_CATEGORIESTool to retrieve the user's master category list. Use when you need to get all categories defined for the user.6 params
Tool to retrieve the user's master category list. Use when you need to get all categories defined for the user.
Parameters* required
topintegerMaximum number of master categories to return (OData $top).
skipintegerNumber of master categories to skip for pagination (OData $skip).
filterstringOData $filter query to filter master categories.
selectarrayOData $select query to specify properties to include.
orderbyarrayOData $orderby query to order master categories by property values.
user_idstringThe user's unique identifier or principal name. Use 'me' for the signed-in user.default: me
OUTLOOK_GET_MESSAGERetrieves a specific email message by its ID from the specified user's Outlook mailbox. Use the 'select' parameter to include specific fields like 'internetMessageHeaders' for filtering automated emails.3 params
Retrieves a specific email message by its ID from the specified user's Outlook mailbox. Use the 'select' parameter to include specific fields like 'internetMessageHeaders' for filtering automated emails.
Parameters* required
selectarrayList of message properties to include in the response. Each item is a property name. MUST be provided as a list. Reduces data transfer and improves performance. Common fields: id, subject, from, toRecipients, ccRecipients, receivedDateTime, sentDateTime, body, bodyPreview, hasAttachments, webLink, internetMessageHeaders, isRead, importance, categories. Leave empty to return all fields.
user_idstringUser's email address, UPN, or 'me' for the currently authenticated user.default: me
message_idstringUnique ID of the Outlook email message to retrieve.
OUTLOOK_GET_PROFILERetrieves the Microsoft Outlook profile for a specified user.1 params
Retrieves the Microsoft Outlook profile for a specified user.
Parameters* required
user_idstringThe user's unique identifier or principal name. Use 'me' to get the profile of the authenticated user.default: me
OUTLOOK_GET_SCHEDULERetrieves free/busy schedule information for specified email addresses within a defined time window.4 params
Retrieves free/busy schedule information for specified email addresses within a defined time window.
Parameters* required
EndTimeobjectThe end date, time, and time zone for the period for which to retrieve schedules. The period can be up to 62 days.
SchedulesarrayA list of SMTP email addresses for users, distribution lists, or resources whose schedules are to be retrieved. Maximum of 20 addresses.
StartTimeobjectThe start date, time, and time zone for the period for which to retrieve schedules.
availabilityViewIntervalstringThe duration of each time slot in the availability view, specified in minutes. Minimum: 5, Maximum: 1440. Default: 30.default: 30
OUTLOOK_GET_SUPPORTED_LANGUAGESTool to retrieve supported languages in the user's mailbox. Use when you need to display or select from available mailbox languages.1 params
Tool to retrieve supported languages in the user's mailbox. Use when you need to display or select from available mailbox languages.
Parameters* required
user_idstringThe user's unique identifier or principal name. Use 'me' for the signed-in user.default: me
OUTLOOK_GET_SUPPORTED_TIME_ZONESTool to retrieve supported time zones in the user's mailbox. Use when you need a list of time zones to display or choose from for event scheduling.1 params
Tool to retrieve supported time zones in the user's mailbox. Use when you need a list of time zones to display or choose from for event scheduling.
Parameters* required
timeZoneStandardstringSpecifies the time zone format to return. Supported values: 'Windows' or 'Iana'. Default is 'Windows' if not specified.one of
Windows · IanaOUTLOOK_LIST_CALENDARSTool to list calendars in the signed-in user's mailbox. Use when you need to retrieve calendars with optional OData queries.6 params
Tool to list calendars in the signed-in user's mailbox. Use when you need to retrieve calendars with optional OData queries.
Parameters* required
topintegerMaximum number of calendars to return (OData $top).
skipintegerNumber of calendars to skip (OData $skip).
filterstringOData filter expression (OData $filter).
selectarrayProperties to include (OData $select).
orderbyarrayOrder by expressions (OData $orderby).
user_idstringUser ID or userPrincipalName. Use 'me' for the signed-in user.default: me
OUTLOOK_LIST_CONTACTSRetrieves a user's Microsoft Outlook contacts, from the default or a specified contact folder.6 params
Retrieves a user's Microsoft Outlook contacts, from the default or a specified contact folder.
Parameters* required
topintegerMaximum number of contacts to retrieve.default: 10
filterstringOData V4 filter expression for targeted retrieval.
selectarrayList of specific contact properties to retrieve. Each item is a property name. MUST be provided as a list. If empty, a default set of properties is returned.
orderbyarrayList of properties to sort results by. Each item is a string like 'displayName asc' or 'createdDateTime desc'. MUST be provided as a list, even for single sort criteria. 'asc' is default.
user_idstringUser Principal Name (UPN) or ID of the user. 'me' refers to the authenticated user.default: me
contact_folder_idstringID of a specific contact folder. If omitted, contacts are retrieved from the default contact folder.
OUTLOOK_LIST_EMAIL_RULESList all email rules from inbox1 params
List all email rules from inbox
Parameters* required
topintegerNumber of rules to retrieve. Default is 100.
OUTLOOK_LIST_EVENT_ATTACHMENTSTool to list attachments for a specific Outlook calendar event. Use when you have an event ID and need to view its attachments.7 params
Tool to list attachments for a specific Outlook calendar event. Use when you have an event ID and need to view its attachments.
Parameters* required
topintegerMaximum number of attachments to return (OData $top).
skipintegerNumber of attachments to skip (OData $skip).
filterstringOData filter string to filter the attachments (OData $filter).
selectarrayList of attachment properties to include (OData $select).
orderbyarrayOrder by clauses to sort the results (OData $orderby).
user_idstringThe user's primary SMTP address, UPN, or 'me' for the signed-in user.default: me
event_idstringThe unique identifier of the calendar event to retrieve attachments for.
OUTLOOK_LIST_EVENTSRetrieves events from a user's Outlook calendar via Microsoft Graph API. Supports primary/secondary/shared calendars, pagination, filtering, property selection, sorting, and timezone specification. Use calendar_id to access non-primary calendars.9 params
Retrieves events from a user's Outlook calendar via Microsoft Graph API. Supports primary/secondary/shared calendars, pagination, filtering, property selection, sorting, and timezone specification. Use calendar_id to access non-primary calendars.
Parameters* required
topintegerMaximum number of events to retrieve per page for pagination.default: 10
skipintegerNumber of initial events to bypass, used for pagination.default: 0
filterstringOData query string to filter events (e.g., "start/dateTime ge 'YYYY-MM-DDTHH:MM:SSZ'"); string literals use single quotes.default:
selectarrayList of specific event property names to return. Each item is a property name like 'subject' or 'start'. MUST be provided as a list. If omitted, a default set of properties is returned.
orderbyarrayList of properties to sort results by. Each item is a string like 'start/dateTime desc' or 'subject asc'. MUST be provided as a list, even for single sort criteria. Use 'asc' (default) or 'desc' for order.
user_idstringEmail address of the target user (or 'me' for authenticated user), identifying the calendar for event listing.default: me
timezonestringPreferred IANA or Windows timezone for event start/end times (e.g., 'America/New_York'); defaults to UTC if unspecified/invalid.default: UTC
calendar_idstringOptional ID of a specific calendar to retrieve events from.If not provided, uses the primary calendar. Get calendar IDs using LIST_CALENDARS action. Useful for accessing secondary calendars, shared calendars, or team calendars.
expand_recurring_eventsbooleanWhen true, automatically expands recurring events to show actual occurrences within the filtered date range instead of series masters. When false (default), returns series masters as before.default: false
OUTLOOK_LIST_MAIL_FOLDERSTool to list a user's top-level mail folders. Use when you need folders like Inbox, Drafts, Sent Items; set include_hidden_folders=True to include hidden folders.2 params
Tool to list a user's top-level mail folders. Use when you need folders like Inbox, Drafts, Sent Items; set include_hidden_folders=True to include hidden folders.
Parameters* required
user_idstringUser's id, userPrincipalName, or 'me' for the signed-in user.default: me
include_hidden_foldersbooleanInclude hidden mail folders (isHidden=true) when set to true.default: false
OUTLOOK_LIST_MESSAGESRetrieves a list of email messages from a specified mail folder in an Outlook mailbox, with options for filtering (including by conversationId to get all messages in a thread), pagination, and sorting; ensure 'user_id' and 'folder' are valid, and all date/time strings are in I...22 params
Retrieves a list of email messages from a specified mail folder in an Outlook mailbox, with options for filtering (including by conversationId to get all messages in a thread), pagination, and sorting; ensure 'user_id' and 'folder' are valid, and all date/time strings are in I...
Parameters* required
topintegerMaximum number of messages to return per request (1-1000). Always check response['@odata.nextLink'] for pagination. If present, make additional requests with that URL (includes $skiptoken). Repeat until '@odata.nextLink' is absent. For large mailboxes (1000+ messages), always paginate.default: 10
skipintegerNumber of messages to skip from the beginning of the result set, for pagination.default: 0
folderstringID or well-known name of the mail folder. Well-known names: inbox, sentitems, drafts, deleteditems, outbox, junkemail. Or use a valid folder ID.default: inbox
selectarrayList of message properties to include. Valid properties: id, subject, from, toRecipients, ccRecipients, bccRecipients, receivedDateTime, sentDateTime, hasAttachments, importance, isRead, body, bodyPreview, categories, conversationId, conversationIndex, flag, internetMessageHeaders, parentFolderId, replyTo, sender, webLink, isDraft, isReadReceiptRequested, isDeliveryReceiptRequested, changeKey, createdDateTime, lastModifiedDateTime, inferenceClassification, size, internetMessageId. Note: attachments is not selectable.
is_readbooleanFilter by read status: 'true' for read, 'false' for unread. Unspecified means no filter by read status.
orderbyarrayList of properties to sort results by, with direction. Each item is a string like 'receivedDateTime desc' or 'subject asc'. Default is 'receivedDateTime desc'. Cannot be used with sentDateTime filters in Sent folder.
subjectstringFilter by exact match of the subject line. Special characters like apostrophes, brackets will be automatically escaped. For complex subject searches, consider using 'Search Messages' instead.
user_idstringTarget user's email or 'me' for authenticated user. For delegated access, use shared mailbox or delegated user's email.default: me
categoriesarrayFilter by categories (case-sensitive); matches if tagged with any specified category.
importancestringFilter by importance: 'low', 'normal', or 'high'.
from_addressstringFilter by the sender's exact email address. NOTE: This filter is applied client-side on the returned results, not server-side.
conversationIdstringFilter messages by conversation ID to retrieve all messages in a specific email thread.
has_attachmentsbooleanFilter by attachment presence: 'true' for messages with attachments, 'false' for those without. NOTE: This filter is applied client-side on the returned results.
subject_containsstringFilter messages where the subject contains the specified case-insensitive substring. NOTE: This filter is applied client-side on the returned results. For better performance, use 'Search Messages' instead.
subject_endswithstringFilter messages where the subject ends with the specified case-insensitive string. NOTE: This filter is applied client-side on the returned results. For better performance, use 'Search Messages' instead.
sent_date_time_gtstringFilter messages sent after this ISO 8601 timestamp.
sent_date_time_ltstringFilter messages sent before this ISO 8601 timestamp.
subject_startswithstringFilter messages where the subject starts with the specified case-insensitive string.
received_date_time_gestringFilter messages received on or after this ISO 8601 timestamp.
received_date_time_gtstringFilter messages received after this ISO 8601 timestamp (e.g., '2023-01-01T00:00:00Z').
received_date_time_lestringFilter messages received on or before this ISO 8601 timestamp.
received_date_time_ltstringFilter messages received before this ISO 8601 timestamp.
OUTLOOK_LIST_OUTLOOK_ATTACHMENTSLists metadata (like name, size, and type, but not `contentBytes`) for all attachments of a specified Outlook email message.2 params
Lists metadata (like name, size, and type, but not `contentBytes`) for all attachments of a specified Outlook email message.
Parameters* required
user_idstringThe unique identifier of the user. Use the user's UPN (e.g., 'AdeleV@contoso.onmicrosoft.com') or 'me' for the currently authenticated user. This specifies the mailbox to query.default: me
message_idstringThe unique identifier of the email message from which to retrieve attachments. This ID is specific to the Outlook message.
OUTLOOK_LIST_REMINDERSTool to retrieve reminders for events occurring within a specified time range. Use when you need to see upcoming reminders between two datetimes.3 params
Tool to retrieve reminders for events occurring within a specified time range. Use when you need to see upcoming reminders between two datetimes.
Parameters* required
userIdstringUser Principal Name or ID. Use 'me' to indicate the signed-in user.default: me
endDateTimestringThe end date and time in ISO 8601 format defining the window for reminders. Example: '2023-10-26T20:00:00.0000000'.
startDateTimestringThe start date and time in ISO 8601 format defining the window for reminders. Example: '2023-10-26T19:00:00.0000000'.
OUTLOOK_LIST_USERSTool to list users in Microsoft Entra ID. Use when you need to retrieve a paginated list of users, optionally filtering or selecting specific properties.4 params
Tool to list users in Microsoft Entra ID. Use when you need to retrieve a paginated list of users, optionally filtering or selecting specific properties.
Parameters* required
topintegerMaximum number of users to return (OData $top). Default page size is 100, maximum is 999.
skipintegerNumber of users to skip (OData $skip) for pagination.
filterstringOData filter expression to restrict returned users (OData $filter).
selectarrayList of user properties to include in the response (OData $select).
OUTLOOK_MOVE_MESSAGEMove a message to another folder within the specified user's mailbox. This creates a new copy of the message in the destination folder and removes the original message.3 params
Move a message to another folder within the specified user's mailbox. This creates a new copy of the message in the destination folder and removes the original message.
Parameters* required
user_idstringUser's email address, UPN, or 'me' for the currently authenticated user.default: me
message_idstringUnique ID of the Outlook email message to move.
destination_idstringThe destination folder ID, or a well-known folder name (e.g., 'inbox', 'deleteditems', 'drafts', 'sentitems').
OUTLOOK_QUERY_EMAILSPrimary tool for querying Outlook emails with custom OData filters. Build precise server-side filters for dates, read status, importance, subjects, attachments, and conversations. Best for structured queries on message metadata. Returns up to 100 messages per request with pagi...7 params
Primary tool for querying Outlook emails with custom OData filters. Build precise server-side filters for dates, read status, importance, subjects, attachments, and conversations. Best for structured queries on message metadata. Returns up to 100 messages per request with pagi...
Parameters* required
topintegerMaximum number of messages to return per request (1-1000). Default is 100. IMPORTANT: For large mailboxes, always check response['@odata.nextLink'] to fetch remaining messages. Pagination example: 1) Call with top=100, 2) Check if '@odata.nextLink' exists in response, 3) If present, make a new request to that full URL (includes $skiptoken), 4) Repeat until '@odata.nextLink' is absent.default: 100
skipintegerNumber of messages to skip for pagination. NOTE: For large result sets, prefer using '@odata.nextLink' from responses instead of manual skip.default: 0
filterstringOData $filter query string to filter email messages. Syntax: 'field operator value' combined with 'and', 'or', 'not'.
**Operators:** eq, ne, lt, le, gt, ge, startswith(), endswith(), contains() (limited support), any()
**Common Fields (Server-Side Filterable):**
- `isRead` - Boolean: true/false
- `importance` - String: 'low', 'normal', 'high'
- `subject` - String (exact match or startswith)
- `hasAttachments` - Boolean: true/false
- `receivedDateTime`, `sentDateTime` - DateTime (ISO 8601: '2025-10-01T00:00:00Z')
- `conversationId` - String (exact match)
- `categories` - Array (use any() operator)
- `toRecipients`, `ccRecipients`, `bccRecipients` - Arrays of recipients (use any())
- `isDraft`, `isRead`, `flag/flagStatus` - Boolean/String flags
**Collection Filtering (LIMITED SUPPORT):**
- ⚠️ Recipients (toRecipients, ccRecipients): NOT supported without advanced query headers
**Date Filtering:**
- Dates MUST be in ISO 8601 format with time zone: '2025-10-01T00:00:00Z'
- Use ge (>=), gt (>), le (<=), lt (<) operators
- Example: `receivedDateTime ge 2025-10-01T00:00:00Z and receivedDateTime lt 2025-10-02T00:00:00Z`
**String Filtering:**
- Exact match: `subject eq 'Meeting Notes'`
- Starts with: `startswith(subject, '[Action Required]')`
- Escape single quotes by doubling: `subject eq 'Owner''s Manual'`
**Complex Nested Properties (NOT directly filterable):**
- `from/emailAddress/address` - Use OUTLOOK_SEARCH_MESSAGES or client-side filtering instead
- `body/content` - Use OUTLOOK_SEARCH_MESSAGES for body text search
**Combining Conditions:**
- AND: `isRead eq false and importance eq 'high'`
- OR: `importance eq 'high' or importance eq 'low'`
- NOT: `not (isRead eq true)`
- Grouping: `(isRead eq false or importance eq 'high') and hasAttachments eq true`
folderstringID or well-known name of the mail folder. Well-known names: 'inbox', 'sentitems', 'drafts', 'deleteditems', 'outbox', 'junkemail' (case-insensitive). Or use a valid folder ID.default: inbox
selectarrayList of message properties to include in the response. Reduces data transfer and improves performance. Common fields: id, subject, from, toRecipients, ccRecipients, receivedDateTime, sentDateTime, hasAttachments, importance, isRead, body, bodyPreview, categories, conversationId, webLink, internetMessageHeaders, isDraft, flag. Leave empty to return all fields.
orderbystringComma-separated sort keys with direction. Format: 'field asc' or 'field desc'. Common fields: receivedDateTime, sentDateTime, subject, importance, from. NOTE: Ordering may be automatically disabled by Microsoft Graph API when using certain filters (e.g., subject exact match, conversationId) to avoid 'InefficientFilter' errors. In those cases, results will be unsorted.default: receivedDateTime desc
user_idstringTarget user's email or 'me' for authenticated user. IMPORTANT: 'me' uses the currently connected account. For cross-mailbox access, ensure you have Mail.Read or Mail.ReadWrite permissions on the target mailbox. 403 errors indicate insufficient delegated/application permissions.default: me
OUTLOOK_REPLY_EMAILSends a plain text reply to an Outlook email message, identified by `message_id`, allowing optional CC and BCC recipients.5 params
Sends a plain text reply to an Outlook email message, identified by `message_id`, allowing optional CC and BCC recipients.
Parameters* required
commentstringThe plain text body of the reply email.
user_idstringThe user's email address or 'me' to indicate the authenticated user. This specifies the mailbox from which the reply will be sent.default: me
cc_emailsarrayList of email addresses for CC recipients.
bcc_emailsarrayList of email addresses for BCC recipients.
message_idstringThe unique ID of the message to reply to. This ID can be obtained from the `OUTLOOK_LIST_MESSAGES` action.
OUTLOOK_SEARCH_MESSAGESSearch Outlook messages using powerful KQL syntax. Supports sender (from:), recipient (to:, cc:), subject, date filters (received:, sent:), attachments, and boolean logic. Only works with Microsoft 365/Enterprise accounts (no @hotmail.com/@outlook.com). Examples: 'from:user@ex...7 params
Search Outlook messages using powerful KQL syntax. Supports sender (from:), recipient (to:, cc:), subject, date filters (received:, sent:), attachments, and boolean logic. Only works with Microsoft 365/Enterprise accounts (no @hotmail.com/@outlook.com). Examples: 'from:user@ex...
Parameters* required
sizeintegerThe maximum number of search results to return per page. Use with from_index for pagination.default: 25
querystringKQL (Keyword Query Language) search query string. Supports advanced syntax for precise searches.
**Basic Syntax:**
- Simple keywords: 'budget report'
- Exact phrases: '"quarterly review"'
- Boolean operators: 'urgent AND deadline' or 'invoice OR receipt'
**Property Filters (prefix:value):**
- from: Sender email - 'from:user@example.com' or 'from:example.com'
- to: Recipient email - 'to:info@jcdn.nl'
- cc: CC recipient - 'cc:manager@example.com'
- subject: Subject line - 'subject:invoice'
- received: Date received - 'received:2025-10-01' or 'received>=2025-10-01'
- sent: Date sent - 'sent:2025-10-01' or 'sent>=2025-10-01'
- hasattachment: Has files - 'hasattachment:yes' or 'hasattachment:no'
**Date Operators:**
- Exact: 'received:2025-10-01'
- Greater/equal: 'received>=2025-10-01'
- Less/equal: 'received<=2025-10-31'
- Range: 'received:2025-10-01..2025-10-31'
- Relative: 'received>today-7' (last 7 days)
**Combining Filters:**
- AND: 'from:user@example.com AND subject:invoice'
- OR: 'to:sales@example.com OR to:support@example.com'
- Complex: 'from:example.com AND (subject:urgent OR subject:important) AND received>=2025-10-01'
Note: Can be empty if using fromEmail, subject, hasAttachments parameters (legacy support).default:
subjectstringText to search for within the message subject line. Legacy parameter - prefer using 'subject:text' in the query parameter for more control. Example: Instead of subject='invoice', use query='subject:invoice AND received>=2025-10-01'
fromEmailstringFilter messages by sender email address or domain. Supports exact email ('user@example.com') or domain matching ('example.com'). Legacy parameter - prefer using 'from:email@example.com' in the query parameter for more flexibility. Note: Only Microsoft 365/Enterprise accounts are supported (no @hotmail.com or @outlook.com).
from_indexintegerThe 0-based starting index for pagination. To paginate: check response['value'][0]['hitsContainers'][0]['moreResultsAvailable']. If true, call again with from_index += size (e.g., 0 → 25 → 50). Message ID is in hits[]['hitId'], not hits[]['resource']['id'].default: 0
hasAttachmentsbooleanFilters messages based on the presence of attachments. Legacy parameter - prefer using 'hasattachment:yes' or 'hasattachment:no' in the query parameter.
enable_top_resultsbooleanIf `true`, sorts results by relevance; otherwise, sorts by date in descending order (newest first).default: false
OUTLOOK_SEND_DRAFTTool to send an existing draft message. Use after creating a draft when you want to deliver it to recipients immediately. Example: Send a draft message with ID 'AAMkAG…'.2 params
Tool to send an existing draft message. Use after creating a draft when you want to deliver it to recipients immediately. Example: Send a draft message with ID 'AAMkAG…'.
Parameters* required
user_idstringThe user's email address or 'me' to represent the authenticated user.default: me
message_idstringThe unique identifier of the draft message to send.
OUTLOOK_SEND_EMAILSends an email with subject, body, recipients, and an optional attachment via Microsoft Graph API. Supports comma-separated email addresses in the to_email field for multiple recipients. Attachments require a non-empty file with valid name and mimetype.11 params
Sends an email with subject, body, recipients, and an optional attachment via Microsoft Graph API. Supports comma-separated email addresses in the to_email field for multiple recipients. Attachments require a non-empty file with valid name and mimetype.
Parameters* required
bodystringThe content of the email body, plain text or HTML based on `is_html`.
fromstringOptional From address to set on the message (send as/on behalf). Provide a single email address. Requires appropriate mailbox permissions.
is_htmlbooleanSpecifies if the email body is HTML; `True` for HTML, `False` for plain text.default: false
subjectstringThe subject line of the email.
to_namestringThe display name of the primary recipient.
user_idstringThe user's email address or the alias 'me' to represent the authenticated user.default: me
to_emailstringThe primary recipient's email address(es). You can provide a single email or multiple emails separated by commas. For CC/BCC recipients, use the respective fields.
cc_emailsarrayList of email addresses for CC recipients. Each email should be a separate string in the array. Do NOT pass comma-separated values as a single string.
attachmentstringOptional file to attach. If provided, its name, mimetype, and content must be valid and non-empty.
bcc_emailsarrayList of email addresses for BCC recipients. Each email should be a separate string in the array. Do NOT pass comma-separated values as a single string.
save_to_sent_itemsbooleanIndicates if the email should be saved in 'Sent Items'.default: true
OUTLOOK_UPDATE_CALENDAR_EVENTUpdates specified fields of an existing Outlook calendar event. Implementation note: To avoid unintentionally clearing properties, the action first fetches the existing event, merges only the provided fields, and then PATCHes the merged updates. Unspecified fields remain uncha...11 params
Updates specified fields of an existing Outlook calendar event. Implementation note: To avoid unintentionally clearing properties, the action first fetches the existing event, merges only the provided fields, and then PATCHes the merged updates. Unspecified fields remain uncha...
Parameters* required
bodyobjectEvent body with content type ('Text' or 'HTML') and the content. If omitted, the existing body remains unchanged.
show_asstringAvailability status for the event. Valid values: 'free', 'tentative', 'busy', 'oof'. If omitted, the existing status remains unchanged.
subjectstringNew subject for the event. If provided as an empty string, the subject will be cleared. If omitted, the existing subject remains unchanged.
user_idstringThe identifier of the user whose calendar event is to be updated. Accepts the user's principal name, ID, or 'me' for the currently authenticated user.default: me
event_idstringThe unique identifier of the calendar event to be updated. This ID can be obtained from the OUTLOOK_LIST_EVENTS action.
locationobjectEvent location as a dictionary. If provided, replaces the existing primary location. Omit to leave unchanged.
attendeesarrayAttendee list for the event. If provided, replaces the existing attendees. If omitted, attendees remain unchanged.
time_zonestringTime zone for the provided start_datetime and/or end_datetime (IANA or Windows time zone names). If omitted, the existing event's time zone is used.
categoriesarrayCategory names to associate with the event. If provided (even empty), replaces the existing categories. If omitted, categories remain unchanged.
end_datetimestringNew end date and time for the event. Provide together with a time zone, or the current event's time zone will be used. Must be after start_datetime if both are provided. If omitted, the end time remains unchanged.
start_datetimestringNew start date and time for the event. Provide together with a time zone, or the current event's time zone will be used. If omitted, the start time remains unchanged.
OUTLOOK_UPDATE_CONTACTUpdates an existing Outlook contact, identified by `contact_id` for the specified `user_id`, requiring at least one other field to be modified.16 params
Updates an existing Outlook contact, identified by `contact_id` for the specified `user_id`, requiring at least one other field to be modified.
Parameters* required
notesstringPersonal notes about the contact (maps to 'personalNotes' in Microsoft Graph API).default:
surnamestringContact's surname (last name).default:
user_idstringUser's identifier; 'me' for the signed-in user, or user's principal name/ID.default: me
birthdaystringContact's birthday (YYYY-MM-DD format).default:
jobTitlestringContact's job title.default:
givenNamestringContact's given (first) name.default:
categoriesarrayCategories for organizing the contact.
contact_idstringUnique identifier of the contact to update.
departmentstringContact's department.default:
homePhonesarrayContact's home phone numbers.
companyNamestringContact's company name.default:
displayNamestringContact's full display name.default:
mobilePhonestringContact's mobile phone number.default:
businessPhonesarrayContact's business phone numbers.
emailAddressesarrayContact's email addresses.
officeLocationstringContact's office location.default:
OUTLOOK_UPDATE_EMAILUpdates specified properties of an existing email message; `message_id` must identify a valid message within the specified `user_id`'s mailbox.9 params
Updates specified properties of an existing email message; `message_id` must identify a valid message within the specified `user_id`'s mailbox.
Parameters* required
bodyobjectNew body content (Text or HTML). If omitted, the existing message body remains unchanged.
is_readbooleanMark message as read (True) or unread (False). If omitted, read status remains unchanged.
subjectstringNew subject line. If omitted, the existing subject remains unchanged. Provide empty string to clear the subject.
user_idstringThe UPN (User Principal Name) of the user whose mailbox contains the message, or 'me' for the currently authenticated user. This determines whose message is updated.default: me
importancestringNew importance level ('low', 'normal', 'high'). If omitted, importance is set to 'normal'.default: normal
message_idstringThe unique identifier of the email message to be updated. This ID is typically obtained from listing messages or creating/sending a message.
cc_recipientsarrayList of CC recipients; replaces all existing CCs. Omitting this field removes all current CC recipients.
to_recipientsarrayList of TO recipients; replaces all existing TOs. Omitting this field removes all current TO recipients.
bcc_recipientsarrayList of BCC recipients; replaces all existing BCCs. Omitting this field removes all current BCC recipients.
OUTLOOK_UPDATE_EMAIL_RULEUpdate an existing email rule6 params
Update an existing email rule
Parameters* required
ruleIdstringID of the email rule to update.
actionsobjectUpdated actions to take when the rule conditions are met.
sequenceintegerUpdated order in which the rule is executed (lower numbers execute first).
isEnabledbooleanWhether the rule should be enabled or disabled.
conditionsobjectUpdated conditions that must be met for the rule to apply.
displayNamestringUpdated display name for the email rule.
OUTLOOK_UPDATE_MAILBOX_SETTINGSTool to update mailbox settings for the signed-in user. Use when you need to configure automatic replies, default time zone, language, or working hours. Example: schedule automatic replies for vacation.4 params
Tool to update mailbox settings for the signed-in user. Use when you need to configure automatic replies, default time zone, language, or working hours. Example: schedule automatic replies for vacation.
Parameters* required
languageobjectLocale preferences for date/time formatting.
timeZonestringDefault mailbox time zone (e.g., 'Pacific Standard Time').
workingHoursobjectWorking hours configuration for the user.
automaticRepliesSettingobjectConfiguration for automatic replies.
outlook-mcp
MCP server for Microsoft Outlook personal accounts via Microsoft Graph API.
Personal Microsoft accounts only —
@outlook.com,@hotmail.com,@live.com. Work/school accounts (Entra ID) are not supported in v1.
Disclaimer: Independent open-source project. Not affiliated with, endorsed by, or supported by Microsoft Corporation. "Outlook" and "Microsoft Graph" are trademarks of Microsoft.
Who this is for
You'll like this if you're:
- An agent builder wiring Outlook into your own infra (OpenClaw, Claude Code, Cursor, custom MCP host) and want a typed tool surface — not stdout you have to parse
- Building on personal Microsoft accounts (Outlook.com / Hotmail / Live) and want full control: BYO Azure app, no enterprise consent flow, no shared client ID
- Looking for real coverage — mail, calendar, contacts, to-do, drafts, folders, batch ops, threading — instead of a mail-only or calendar-only wrapper
- Security-conscious: tokens in the OS keyring (Keychain on macOS), granular
allow_categories, optionalread_onlymode, zero telemetry
This isn't for you if you need work/school M365 accounts (use Microsoft's official tooling — Entra ID auth and admin-consent flows are out of scope here), or if a basic mail-only client would suffice (this has 62 tools — way more than you need for "read my inbox").
How it differs from other Outlook tools you'll find
This is the only first-class MCP server in the personal-Outlook space — most alternatives are bash scripts or skill-shaped CLI wrappers the agent shells out to. That distinction matters: the agent gets typed tool schemas with structured args/returns, not stdout it has to parse. Other things you won't find elsewhere: /$batch-optimized triage (10-20× faster on bulk ops), recursive folder ops with name resolution, granular per-category permissions, multi-account support, and full attachment write paths including >3MB upload sessions for drafts.
What This Enables
Give your AI agent full Outlook access. Example prompts that just work:
- "Summarize my unread email from the past 24 hours and flag anything time-sensitive."
- "What's in my Focused Inbox right now? Anything in Other that looks like it belongs up top?"
- "Any shipping updates in my inbox? Track what I'm waiting on and when it's supposed to arrive."
- "Scan my email for upcoming subscription renewals — what's about to auto-charge in the next two weeks?"
- "I've got a trip to Seattle next week — check my calendar for the itinerary and create a To Do task with a packing checklist."
- "Draft a reply to the last message from my sister saying I'll call her this weekend."
- "Move all newsletter and promotional email from this week to a 'Read Later' folder — batch 20 at a time."
The server exposes 62 discrete tools so the agent can compose its own workflow — read, triage, write, schedule, track tasks — without hardcoded macros.
Works With
- OpenClaw — native MCP support, available via ClawHub
- Claude Code — add to
~/.claude/settings.jsonundermcpServers - Cursor — MCP-compatible
- Any MCP client — it's a standard stdio MCP server
Listed on the official MCP Registry as io.github.mpalermiti/outlook-mcp.
Features
62 tools across 13 categories:
- Auth (1) -- auth status check (login is via CLI)
- Mail Read (7) -- list inbox (with Focused Inbox filter), read message, bulk read by ID via
$batch, search (KQL), list folders, delta-sync inbox changes, composed "since last call" digest across mail/events/contacts - Mail Write (3) -- send, reply/reply-all, forward
- Mail Triage (9) -- move, delete (soft by default), flag, categorize, mark read/unread, reclassify (Focused Inbox), list/set/delete per-sender Focused Inbox overrides
- Calendar Read (3) -- list events (with recurring expansion), get event details, delta-sync event changes
- Calendar Write (4) -- create, update, delete, RSVP (accept/decline/tentative)
- Contacts (7) -- list, search, get, create, update, delete, delta-sync changes
- To Do (6) -- list task lists, list/create/update/complete/delete tasks
- Drafts (5) -- list, create, update, send, delete
- Attachments (5) -- list, download, send-with-attachments, attach-to-draft, remove-draft-attachment
- Folder Management (3) -- create, rename, delete mail folders
- Threading and Batch (3) -- list thread, copy message, batch triage
- User and Admin (6) -- whoami, list calendars, list categories, mail tips, accounts
Design principles:
- BYOID -- Bring Your Own ID. You register your own Azure AD app. No shared client ID.
- Zero telemetry -- no analytics, no local caching, no third-party calls.
- Token storage -- OS keyring via
azure-identity(macOS Keychain, Windows Credential Store, Linux Secret Service). - Input validation -- all inputs validated (email, Graph IDs, OData, KQL, datetimes) before any API call.
- Read-only mode -- set
read_only: truein config to block all write operations. - Soft delete -- delete moves to Deleted Items by default. Hard delete requires explicit
permanent: true. - Timezone-aware -- calendar operations respect your configured IANA timezone.
Agent-friendly shape (1.8.0)
Two pure-code upgrades that make the same 57 tools cheaper and more recoverable for AI agents:
-
Concise mode — pass
concise=Trueto the five high-volume read tools (outlook_list_inbox,outlook_read_message,outlook_search_mail,outlook_list_events,outlook_list_thread) to drop bulky fields: full message bodies, per-event attendee lists, quoted prior-message text in threads, body previews/categories on inbox listings. Typical payload reduction ~10×. Defaultconcise=Falsepreserves the existing response shape — strict backward compat. -
Structured Graph errors — every tool wraps msgraph SDK exceptions into
{code, message, action}responses with operator-friendly recovery hints: re-auth on 401, ROADMAP pointer on 403/ErrorAccessDenied(known unsupported-endpoint dead-ends), re-list on 404/ErrorItemNotFound, back-off on 429, retry on 503.OutlookMCPErrorsubclasses and validation errors pass through unchanged.
Azure AD App Registration
You need to register a free Azure AD app to get a client ID.
Prerequisites (Personal Microsoft Accounts)
Microsoft has deprecated app registration for personal accounts without an Azure AD tenant. You need to create a free Azure account first:
- Go to azure.microsoft.com/free and sign up with your personal
@outlook.comaccount. Requires a credit card for identity verification but won't charge you. This creates a proper Azure AD tenant.
Register the App
-
Go to App Registrations and sign in with your
@outlook.comaccount. -
Click "+ New registration" and fill in:
- Name: anything except Microsoft-branded terms (e.g.
mp-outlook-mcp— names like "Outlook MCP" will be rejected) - Supported account types: select "Personal Microsoft accounts only"
- Redirect URI: leave blank
- Name: anything except Microsoft-branded terms (e.g.
-
Click Register. Copy the Application (client) ID from the overview page.
-
Go to Authentication (Preview) → Settings tab → toggle "Allow public client flows" to Yes → Save.
-
Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions → add:
Mail.ReadWrite,Mail.SendCalendars.ReadWriteContacts.ReadWrite,Tasks.ReadWriteUser.Read,offline_access
No client secret is needed. The device code flow uses public client auth.
Quick Start
Install
Option A — from PyPI (recommended):
uv tool install outlook-graph-mcp
# or: pipx install outlook-graph-mcp
# or: pip install outlook-graph-mcp
Option B — from source:
git clone https://github.com/mpalermiti/outlook-mcp.git
cd outlook-mcp
uv sync
Configure
Create ~/.outlook-mcp/config.json:
{
"client_id": "YOUR_APPLICATION_CLIENT_ID",
"tenant_id": "consumers",
"timezone": "America/Los_Angeles",
"read_only": true
}
The only required field is client_id. Everything else has sensible defaults. Start with read_only: true — flip to false when you're comfortable.
Register with your MCP client
If installed from PyPI:
{
"mcpServers": {
"outlook": {
"command": "outlook-mcp"
}
}
}
If installed from source:
{
"mcpServers": {
"outlook": {
"command": "uv",
"args": ["--directory", "/path/to/outlook-mcp", "run", "outlook-mcp"]
}
}
}
For OpenClaw, use the openclaw mcp CLI — it writes to mcp.servers in ~/.openclaw/openclaw.json for you:
# If installed from PyPI:
openclaw mcp set outlook '{"command":"outlook-mcp"}'
# If installed from source:
openclaw mcp set outlook '{"command":"uv","args":["--directory","/path/to/outlook-mcp","run","outlook-mcp"]}'
# Verify:
openclaw mcp list
openclaw mcp show outlook --json
Restart the OpenClaw gateway after registering. See the OpenClaw MCP docs for SSE/HTTP transport variants.
Authenticate
Run this once on the machine where the MCP server will run:
uv run outlook-mcp auth
You'll get a URL and a code. Open the URL in any browser, enter the code, and sign in with your Microsoft account. Tokens are cached in the OS keyring — the MCP server picks them up automatically.
Other CLI commands:
uv run outlook-mcp status # Check auth status
uv run outlook-mcp logout # Clear credentials
uv run outlook-mcp serve # Start MCP server (default, used by OpenClaw/Claude)
Tool Reference
Auth
| Tool | Description |
|---|---|
outlook_auth_status | Check if authenticated and whether read-only mode is active. |
Note: Authentication is handled via the CLI (
outlook-mcp auth), not through MCP tools. See Authenticate above.
Mail Read
| Tool | Description |
|---|---|
outlook_list_inbox | List messages in a folder. folder accepts display names, well-known names, or Graph IDs. Filter by read status, sender, date range, Focused Inbox classification. Pagination via skip. |
outlook_read_message | Get full message by ID. Format: text, html, or full (both). Pass include_deferred_send=True to also surface the draft's scheduled delivery time. |
outlook_read_messages | Bulk read up to 20 messages by ID via Graph $batch in one round-trip. Per-message shape matches outlook_read_message byte-for-byte for the same (format, concise, include_deferred_send). Partial-failure tolerant: 404s on some IDs surface in failures[] without failing the whole call. Use NOT N outlook_read_message calls. |
outlook_search_mail | Search mail using KQL query. Optionally scope to a folder by name or ID. |
outlook_list_folders | List mail folders with counts, parent_id, and child_count. Pass recursive=true to walk the full folder tree (subfolders included). |
outlook_list_inbox_delta | List only inbox changes since the last call. First call returns a full snapshot plus a delta_token; subsequent calls (token passed back) return only added/updated/deleted items. Deletes come back as {id, is_deleted: True}. Cursor is stateless — agent persists and replays. |
outlook_changes_since | One structured "since last call" digest composing mail/events/contacts deltas. Returns counts + urgent_flagged mail + top-5 by_sender + new/cancelled events. Each resource has an independent delta_token; stale-token recovery (HTTP 410) auto-resyncs that resource and surfaces _meta.resync. First-call snapshot is filtered to fallback_window_hours (default 24). Designed for recurring agent loops. |
Mail Write
| Tool | Description |
|---|---|
outlook_send_message | Send email. Supports TO/CC/BCC, HTML body, importance level. |
outlook_reply | Reply or reply-all to a message. |
outlook_forward | Forward a message to one or more recipients with optional comment. |
Mail Triage
| Tool | Description |
|---|---|
outlook_move_message | Move a message to a folder by name or ID. |
outlook_delete_message | Delete a message. Soft delete (Deleted Items) by default. permanent: true for hard delete. |
outlook_flag_message | Set follow-up flag: flagged, complete, or notFlagged. |
outlook_categorize_message | Set categories on a message. |
outlook_mark_read | Mark a message as read or unread. |
outlook_reclassify_message | Move a message between Focused Inbox and Other (focused / other). |
outlook_list_inbox_overrides | List Focused Inbox per-sender override rules. |
outlook_set_inbox_override | Upsert a per-sender Focused Inbox override (focused / other). Case-insensitive sender matching; PATCH-if-exists, else POST. |
outlook_delete_inbox_override | Delete a Focused Inbox override by ID. |
Calendar Read
| Tool | Description |
|---|---|
outlook_list_events | List events in a date range. Expands recurring events. Configurable via days, after, before. |
outlook_get_event | Get full event details: attendees, body, online meeting URL, recurrence. |
outlook_list_events_delta | List only event changes inside a window since the last call. start and end (ISO 8601) required on the first call (Graph constraint — no whole-calendar sync). Deletes come back as {id, is_deleted: True}. Cursor is stateless. |
Calendar Write
| Tool | Description |
|---|---|
outlook_create_event | Create event with location, attendees, recurrence, online meeting support. |
outlook_update_event | Update event fields (subject, time, location, body). Only patches changed fields. |
outlook_delete_event | Delete a calendar event. |
outlook_rsvp | RSVP to an event: accept, decline, or tentative. Optionally include a message. |
Contacts
| Tool | Description |
|---|---|
outlook_list_contacts | List contacts with cursor pagination. |
outlook_search_contacts | Search contacts by name or email. |
outlook_get_contact | Get full contact details by ID. |
outlook_create_contact | Create a new contact. |
outlook_update_contact | Update contact fields. |
outlook_delete_contact | Delete a contact. |
outlook_list_contacts_delta | List only contact changes since the last call. Deletes come back as {id, is_deleted: True}. Cursor is stateless. |
To Do
| Tool | Description |
|---|---|
outlook_list_task_lists | List To Do lists. |
outlook_list_tasks | List tasks with status filter and pagination. |
outlook_create_task | Create task with due date, importance, recurrence. |
outlook_update_task | Update task fields. |
outlook_complete_task | Mark task as completed. |
outlook_delete_task | Delete a task. |
Drafts
| Tool | Description |
|---|---|
outlook_list_drafts | List draft messages with pagination. |
outlook_create_draft | Create a draft. Supports scheduled delivery via deferred_send_datetime (server-side, Outlook-desktop-compatible "Delay Delivery"). |
outlook_update_draft | Update draft fields. Accepts is_html=True for HTML bodies and deferred_send_datetime to set or clear the scheduled delivery time. |
outlook_send_draft | Send an existing draft. |
outlook_delete_draft | Delete a draft. |
Attachments
| Tool | Description |
|---|---|
outlook_list_attachments | List attachments on a message. |
outlook_download_attachment | Download attachment and save decoded bytes to a file. |
outlook_send_with_attachments | Send message with file attachments (auto upload session for >3MB). |
outlook_attach_to_draft | Add attachments to an existing draft (auto upload session for >3MB). |
outlook_remove_draft_attachment | Remove a single attachment from a draft. |
Folder Management
| Tool | Description |
|---|---|
outlook_create_folder | Create mail folder (top-level or nested). |
outlook_rename_folder | Rename a mail folder. |
outlook_delete_folder | Delete a mail folder (refuses well-known folders). |
Threading and Batch
| Tool | Description |
|---|---|
outlook_list_thread | Get all messages in a conversation thread. |
outlook_copy_message | Copy a message to another folder. |
outlook_batch_triage | Batch move/flag/categorize/mark_read (max 20 per call). Single Graph /$batch round-trip — 10-20× faster than per-message calls for large triage. |
User and Admin
| Tool | Description |
|---|---|
outlook_whoami | Get current user profile. |
outlook_list_calendars | List available calendars. |
outlook_list_categories | List category definitions with colors. |
outlook_get_mail_tips | Pre-send check (OOF, delivery restrictions). |
outlook_list_accounts | List configured accounts. |
outlook_switch_account | Switch active account. |
Configuration
Config lives at ~/.outlook-mcp/config.json (created with 0600 permissions).
| Field | Type | Default | Description |
|---|---|---|---|
client_id | string | null | Azure AD application (client) ID. Required for auth. |
tenant_id | string | "consumers" | Azure AD tenant. Use "consumers" for personal Microsoft accounts. |
timezone | string | "UTC" | IANA timezone (e.g. "America/New_York"). Used for relative date computations in calendar tools. |
read_only | bool | false | When true, all write tools (send, reply, move, delete, create, update, RSVP) return an error. |
allow_categories | list[string] | [] | Optional. Restrict write tools to specific categories (see below). Empty list = all writes allowed when read_only: false. |
Granular Write Permissions (optional)
By default, read_only: false unlocks all write tools. For finer control, set allow_categories to restrict write access to specific categories. Read tools (list, search, get) are always allowed — allow_categories only narrows the write surface.
Available categories:
| Category | Tools | Risk |
|---|---|---|
mail_drafts | create/update/delete draft | Safe — drafts only, no send |
mail_triage | move, delete (soft), flag, categorize, mark read, copy, batch | Moderate — reversible except hard delete |
mail_folders | create/rename/delete folder | Moderate |
mail_send | send, reply, forward, send_draft, send_with_attachments | Dangerous — sends email on your behalf |
calendar_write | create/update/delete event, RSVP | Moderate — creates calendar entries |
contacts_write | create/update/delete contact | Moderate |
todo_write | create/update/complete/delete task | Safe — your own task list |
Example policies:
Draft-only assistant (agent can compose drafts, you review and send):
{ "read_only": false, "allow_categories": ["mail_drafts", "mail_triage", "todo_write"] }
Calendar-only (agent can manage your schedule, nothing else):
{ "read_only": false, "allow_categories": ["calendar_write"] }
Full write access (agent can do everything):
{ "read_only": false }
Read-only (safest default, no writes):
{ "read_only": true }
When allow_categories is set, any tool in a non-allowed category returns a permission-denied error (PermissionDeniedError) naming the blocked category. When allow_categories is empty (or unset) and read_only is false, all write tools are permitted. read_only: true always takes precedence — if set, all writes are blocked regardless of allow_categories. Unknown category names are rejected at config load time with a validation error; only the seven names above are accepted.
Privacy and Security
- Zero telemetry. No analytics, no tracking, no usage data collected.
- Zero local caching. Every call goes directly to Microsoft Graph. No local email/calendar storage.
- Zero third-party calls. The server only talks to
graph.microsoft.comandlogin.microsoftonline.com. - Token storage. OAuth tokens are persisted via
azure-identity'sTokenCachePersistenceOptions. On macOS the OS Keychain is used; on Windows, DPAPI; on Linux with PyGObject/libsecret available, gnome-keyring. On Linux without libsecret (e.g. the isolated venv created byuv tool install), tokens fall back to a0600plaintext file at~/.IdentityService/and the MCP logs a one-time warning at startup. For encrypted storage on Linux, installpython3-gi gnome-keyring libsecret-1-0and re-create the venv with--system-site-packages. - No logging of sensitive data. Message bodies, recipient addresses, and tokens are never logged.
- Config permissions. Config directory is
0700, config file is0600. Symlinked configs are rejected. - Input validation. All user inputs (email addresses, Graph IDs, OData filters, KQL queries, datetimes) are validated and sanitized before reaching the Graph API.
Development
# Install dev dependencies
uv sync --extra dev
# Run tests
uv run pytest
# Lint
uv run ruff check src/ tests/
# Format
uv run ruff format src/ tests/
# Run server locally (stdio)
uv run outlook-mcp
Requirements: Python 3.10+
Roadmap
- Inbox Rules -- list, create, delete rules
- Advanced mail -- raw MIME export, internet message headers
- Calendar -- cancel event (with attendee notification)
- Checklists -- checklist items on To Do tasks
- Enterprise (Entra ID) -- work/school account support
License
MIT. See LICENSE.
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Registryactive
Packageoutlook-graph-mcp
TransportSTDIO
UpdatedMay 23, 2026
