@jbctechsolutions/mcp-office365

MCP server for Microsoft 365 -- mail, calendar, contacts, tasks, teams, people, and planner.

A Model Context Protocol (MCP) server that provides 249 tools for full read/write access to Microsoft 365 via the Microsoft Graph API. Manage your emails, calendar events, contacts, tasks, OneNote notes, Teams channels and chats, people directory, and Planner boards directly through MCP.

Features Overview

| Category | Tools | Description | |----------|------:|-------------| | Mail -- Reading | 9 | Folders, search, delta sync, conversations, unread counts | | Mail -- Sending & Drafts | 16 | Send, draft, reply, forward with two-phase approval | | Mail -- Signatures | 2 | Email signature management | | Mail -- Organization | 24 | Read/unread, flags, categories, importance, move, delete, batch ops | | Mail -- Rules | 4 | Inbox rule management | | Mail -- Categories | 4 | Master category management | | Mail -- Focused Inbox | 4 | Focused inbox override management | | Mail -- Settings & Auto-Replies | 4 | Automatic replies, mailbox settings | | Mail -- Tips & Headers | 3 | Mail tips, message headers, MIME export | | Attachments | 2 | List and download email attachments | | Calendar -- Events | 11 | List, search, create, update, delete, RSVP, recurring instances | | Calendar -- Groups | 2 | Calendar group management | | Calendar -- Permissions | 4 | Calendar sharing permissions | | Calendar -- Rooms | 2 | Room lists and meeting rooms | | Contacts & Folders | 13 | CRUD contacts, contact folders, photos | | Tasks & Task Lists | 13 | To Do tasks with recurrence, task lists | | Checklist Items | 5 | Subtasks on To Do tasks | | Linked Resources | 4 | Linked resources on To Do tasks | | Task Attachments | 4 | File attachments on To Do tasks | | OneNote | 6 | Browse notebooks/sections/pages, search, and create pages | | Scheduling | 2 | Free/busy availability, meeting time suggestions | | Teams -- Channels | 8 | Channel CRUD, team members | | Teams -- Channel Messages | 6 | Read and send channel messages with replies | | Teams -- Chats | 6 | 1:1 and group chats, send messages | | People & Presence | 8 | People search, org chart, presence status | | Planner | 18 | Plans, buckets, tasks, task details with ETag | | Shared Mailbox | 8 | Read another user's mailbox, calendar, and OneDrive via delegate/shared access | | Total | 229 | |

Quick Start

Install and run

npx -y @jbctechsolutions/mcp-office365

The server connects to Microsoft 365 via the Microsoft Graph API (cross-platform, full read/write access).

Pre-authenticate (optional)

npx @jbctechsolutions/mcp-office365 auth
npx @jbctechsolutions/mcp-office365 auth --status
npx @jbctechsolutions/mcp-office365 auth --logout

Server flags

Pass these when launching the server (after any subcommand) to scope the exposed tool surface:

| Flag | Effect | | --- | --- | | --preset <names> | Expose only the listed domains (comma-separated). Repeatable. Default (or all) exposes the full surface. | | --read-only | Expose only read tools (readOnlyHint: true). All writes, prepare_*/confirm_*, and destructive tools are hidden; calling one returns a READ_ONLY_MODE error. Note: download_* and get_*_photo tools are excluded too — they write fetched bytes to local disk and so are not read-only. | | --confirm <mode> | How a destructive prepare_* seeks confirmation. token (default) returns an approval token to pass to the matching confirm_* tool. elicit asks the user inline (MCP elicitation, ~60s) and, on approval, executes immediately; if the client can't elicit, the user cancels, or it times out, it falls back to the token flow. An explicit decline cancels and invalidates the token. |

Valid presets: mail, calendar, contacts, tasks, notes, teams, planner, files, sharepoint, excel, people, meetings, shared (plus all). An unknown preset name fails startup with the valid list.

# Mail + calendar only, read-only
npx @jbctechsolutions/mcp-office365 --preset mail,calendar --read-only

In a client config, add them to args:

{
  "mcpServers": {
    "office365": {
      "command": "npx",
      "args": ["-y", "@jbctechsolutions/mcp-office365", "--preset", "mail,calendar", "--read-only"]
    }
  }
}

Claude Desktop configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "office365": {
      "command": "npx",
      "args": ["-y", "@jbctechsolutions/mcp-office365"]
    }
  }
}

Claude Code configuration

Option 1: Plugin (recommended) -- add to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "jbctechsolutions": {
      "source": {
        "source": "github",
        "repo": "jbctechsolutions/mcp-office365"
      }
    }
  },
  "enabledPlugins": {
    "office365@jbctechsolutions": true
  }
}

Option 2: Manual -- add .mcp.json to your project or ~/.claude/.mcp.json globally:

{
  "mcpServers": {
    "office365": {
      "command": "npx",
      "args": ["-y", "@jbctechsolutions/mcp-office365"]
    }
  }
}

Authentication

Device Code Flow (Graph API)

1. The server displays a device code and URL
2. Visit https://microsoft.com/devicelogin
3. Enter the code and sign in with your Microsoft account
4. Grant the requested permissions

Tokens are stored in ~/.outlook-mcp/tokens.json and refreshed automatically.

Azure AD App Registration (required)

No app registration is embedded — device-code sign-in needs an app that belongs to the tenant you sign in against, so you must register your own and set OUTLOOK_MCP_CLIENT_ID (and OUTLOOK_MCP_TENANT_ID for a single-tenant app). The server fails fast with setup guidance if OUTLOOK_MCP_CLIENT_ID is unset.

1. Register in Azure Portal > Azure Active Directory > App registrations > New registration
   • Name: Outlook MCP Server
   • Supported account types: single-tenant for one org, or multitenant to allow other tenants (multitenant + personal accounts may require Microsoft publisher verification)
   • Redirect URI: leave blank
2. Add API permissions (Microsoft Graph > Delegated): see Required Graph API Permissions below
3. Enable public client flows: Authentication > Advanced settings > Allow public client flows > Yes
4. Configure with environment variables:

{
  "mcpServers": {
    "office365": {
      "command": "npx",
      "args": ["-y", "@jbctechsolutions/mcp-office365"],
      "env": {
        "OUTLOOK_MCP_CLIENT_ID": "your-client-id-here",
        "OUTLOOK_MCP_TENANT_ID": "common"
      }
    }
  }
}

Tenant options: common (all accounts), organizations (work/school only), consumers (personal only), or a specific tenant ID.

Tool Reference

All 249 tools listed below.

| Tool | Description | |------|-------------| | list_folders | List all mail folders with message and unread counts | | list_emails | List emails in a folder with pagination | | search_emails | Search emails by subject, sender, or content | | search_emails_advanced | Advanced email search using KQL (Keyword Query Language) (Graph API) | | check_new_emails | Check for new/changed emails since last check via delta sync (Graph API) | | get_email | Get full email details including body | | get_emails | Get multiple emails by ID in a single call (max 25) | | list_conversation | List all messages in an email conversation/thread (Graph API) | | get_unread_count | Get unread email count |

| Tool | Description | |------|-------------| | send_email | Send an email with optional CC, BCC, attachments, and HTML | | create_draft | Create a draft email for later editing and sending | | update_draft | Update an existing draft email | | add_draft_attachment | Add a file attachment to a draft (Graph API) | | add_draft_inline_image | Add an inline image to a draft for HTML body (Graph API) | | list_drafts | List all draft emails | | prepare_send_draft | Prepare to send a draft (two-phase approval) | | confirm_send_draft | Confirm and send a draft | | prepare_send_email | Prepare to send an email immediately (two-phase) | | confirm_send_email | Confirm and send the email | | prepare_reply_email | Prepare to reply to an email (two-phase) | | confirm_reply_email | Confirm and send the reply | | prepare_forward_email | Prepare to forward an email (two-phase) | | confirm_forward_email | Confirm and forward the email | | reply_as_draft | Create a reply (or reply-all) as an editable draft | | forward_as_draft | Create a forward as an editable draft |

| Tool | Description | |------|-------------| | mark_email_read | Mark an email as read | | mark_email_unread | Mark an email as unread | | set_email_flag | Set a follow-up flag on an email | | clear_email_flag | Clear the follow-up flag from an email | | set_email_categories | Set categories on an email | | set_email_importance | Set email importance level (low, normal, high) (Graph API) | | create_folder | Create a new mail folder | | rename_folder | Rename a mail folder | | move_folder | Move a mail folder under a different parent | | prepare_delete_email | Prepare to delete an email (two-phase) | | confirm_delete_email | Confirm email deletion | | prepare_move_email | Prepare to move an email to another folder (two-phase) | | confirm_move_email | Confirm email move | | prepare_archive_email | Prepare to archive an email (two-phase) | | confirm_archive_email | Confirm email archive | | prepare_junk_email | Prepare to mark an email as junk (two-phase) | | confirm_junk_email | Confirm marking as junk | | prepare_delete_folder | Prepare to delete a mail folder (two-phase) | | confirm_delete_folder | Confirm folder deletion | | prepare_empty_folder | Prepare to empty a folder (two-phase) | | confirm_empty_folder | Confirm emptying folder | | prepare_batch_delete_emails | Prepare to batch delete multiple emails (two-phase) | | prepare_batch_move_emails | Prepare to batch move multiple emails (two-phase) | | confirm_batch_operation | Confirm a batch delete or move operation |

| Tool | Description | |------|-------------| | list_mail_rules | List all inbox mail rules | | create_mail_rule | Create an inbox rule with conditions and actions | | prepare_delete_mail_rule | Prepare to delete a mail rule (two-phase) | | confirm_delete_mail_rule | Confirm mail rule deletion |

| Tool | Description | |------|-------------| | list_categories | List all master categories | | create_category | Create a new master category with a color preset | | prepare_delete_category | Prepare to delete a master category (two-phase) | | confirm_delete_category | Confirm category deletion |

| Tool | Description | |------|-------------| | list_focused_overrides | List all focused inbox overrides | | create_focused_override | Create a focused inbox override for a sender | | prepare_delete_focused_override | Prepare to delete a focused inbox override (two-phase) | | confirm_delete_focused_override | Confirm focused inbox override deletion |

| Tool | Description | |------|-------------| | get_automatic_replies | Get automatic replies (out-of-office) settings | | set_automatic_replies | Set automatic replies (out-of-office) settings | | get_mailbox_settings | Get mailbox settings (language, time zone, formats, working hours) | | update_mailbox_settings | Update mailbox settings (language, time zone, formats) |

| Tool | Description | |------|-------------| | get_mail_tips | Get mail tips (auto-replies, mailbox full, restrictions) for addresses | | get_message_headers | Get internet message headers (SPF, DKIM, routing) | | get_message_mime | Download the full MIME content (.eml) of an email |

| Tool | Description | |------|-------------| | list_attachments | List attachment metadata (name, size, type) for an email | | download_attachment | Download an email attachment to disk |

| Tool | Description | |------|-------------| | list_calendars | List all calendar folders | | list_events | List calendar events with date range filtering | | get_event | Get event details | | search_events | Search events by title and/or date range | | create_event | Create a calendar event (supports Teams online meetings) | | update_event | Update event details (single instance or series) | | respond_to_event | Accept, decline, or tentatively accept an invitation | | delete_event | Delete a calendar event or recurring series | | prepare_delete_event | Prepare to delete a calendar event (two-phase) (Graph API) | | confirm_delete_event | Confirm calendar event deletion | | list_event_instances | List instances of a recurring event in a date range (Graph API) |

| Tool | Description | |------|-------------| | list_calendar_groups | List all calendar groups | | create_calendar_group | Create a new calendar group |

| Tool | Description | |------|-------------| | list_calendar_permissions | List sharing permissions for a calendar | | create_calendar_permission | Share a calendar by creating a permission | | prepare_delete_calendar_permission | Prepare to delete a calendar permission (two-phase) | | confirm_delete_calendar_permission | Confirm calendar permission deletion |

| Tool | Description | |------|-------------| | list_room_lists | List all room lists (building/floor groupings) | | list_rooms | List meeting rooms, optionally filtered by room list |

| Tool | Description | |------|-------------| | list_contacts | List contacts with pagination | | search_contacts | Search contacts by name | | get_contact | Get contact details | | create_contact | Create a new contact (Graph API) | | update_contact | Update contact details (Graph API) | | prepare_delete_contact | Prepare to delete a contact (two-phase) (Graph API) | | confirm_delete_contact | Confirm contact deletion | | get_contact_photo | Download a contact's photo (Graph API) | | set_contact_photo | Set or update a contact's photo (Graph API) | | list_contact_folders | List all contact folders (Graph API) | | create_contact_folder | Create a contact folder (Graph API) | | prepare_delete_contact_folder | Prepare to delete a contact folder (two-phase) (Graph API) | | confirm_delete_contact_folder | Confirm contact folder deletion |

| Tool | Description | |------|-------------| | list_task_lists | List all task lists (Microsoft To Do) (Graph API) | | list_tasks | List tasks with pagination and filtering | | search_tasks | Search tasks by name | | get_task | Get task details | | create_task | Create a task with optional recurrence (Graph API) | | update_task | Update task details with optional recurrence (Graph API) | | complete_task | Mark a task as completed (Graph API) | | create_task_list | Create a new task list (Graph API) | | rename_task_list | Rename a task list (Graph API) | | prepare_delete_task | Prepare to delete a task (two-phase) (Graph API) | | confirm_delete_task | Confirm task deletion | | prepare_delete_task_list | Prepare to delete a task list (two-phase) (Graph API) | | confirm_delete_task_list | Confirm task list deletion |

| Tool | Description | |------|-------------| | list_checklist_items | List checklist items (subtasks) on a To Do task | | create_checklist_item | Create a checklist item on a To Do task | | update_checklist_item | Update a checklist item (toggle check, rename) | | prepare_delete_checklist_item | Prepare to delete a checklist item (two-phase) | | confirm_delete_checklist_item | Confirm checklist item deletion |

| Tool | Description | |------|-------------| | list_linked_resources | List linked resources on a To Do task | | create_linked_resource | Create a linked resource on a To Do task | | prepare_delete_linked_resource | Prepare to delete a linked resource (two-phase) | | confirm_delete_linked_resource | Confirm linked resource deletion |

| Tool | Description | |------|-------------| | list_task_attachments | List attachments on a To Do task | | create_task_attachment | Attach a file to a To Do task (base64 encoded) | | prepare_delete_task_attachment | Prepare to delete a task attachment (two-phase) | | confirm_delete_task_attachment | Confirm task attachment deletion |

| Tool | Description | |------|-------------| | list_notebooks | List OneNote notebooks for the current user | | list_note_sections | List OneNote sections, optionally scoped to a notebook | | list_note_pages | List OneNote pages, optionally scoped to a section | | get_note_page | Get a OneNote page's metadata and HTML content | | search_note_pages | Search OneNote pages by keyword | | create_note_page | Create a new OneNote page in a section |

| Tool | Description | |------|-------------| | check_availability | Check free/busy availability for people in a time window | | find_meeting_times | Find available meeting time slots for a group of attendees |

| Tool | Description | |------|-------------| | set_signature | Save an email signature auto-appended to outgoing emails | | get_signature | Get the currently stored email signature |

| Tool | Description | |------|-------------| | list_teams | List all Microsoft Teams the user has joined | | list_channels | List all channels in a team | | get_channel | Get details for a specific channel | | create_channel | Create a new channel in a team | | update_channel | Update a channel name or description | | prepare_delete_channel | Prepare to delete a channel (two-phase) | | confirm_delete_channel | Confirm channel deletion | | list_team_members | List all members of a team |

| Tool | Description | |------|-------------| | list_channel_messages | List recent messages in a channel | | get_channel_message | Get a specific channel message with its replies | | prepare_send_channel_message | Prepare to send a message to a channel (two-phase) | | confirm_send_channel_message | Confirm sending a channel message | | prepare_reply_channel_message | Prepare to reply to a channel message (two-phase) | | confirm_reply_channel_message | Confirm replying to a channel message |

| Tool | Description | |------|-------------| | list_chats | List recent 1:1 and group chats | | get_chat | Get details of a specific chat | | list_chat_messages | List recent messages in a chat | | prepare_send_chat_message | Prepare to send a message in a chat (two-phase) | | confirm_send_chat_message | Confirm sending a chat message | | list_chat_members | List members of a chat |

| Tool | Description | |------|-------------| | list_relevant_people | List AI-ranked relevant people for the current user | | search_people | Search people by name or email | | get_manager | Get the current user's manager | | get_direct_reports | Get the current user's direct reports | | get_user_profile | Get a user's profile information | | get_user_photo | Get a user's profile photo | | get_user_presence | Get a user's presence/availability status | | get_users_presence | Batch get presence status for multiple users |

| Tool | Description | |------|-------------| | list_plans | List all Planner plans the user has access to | | get_plan | Get details for a specific Planner plan | | create_plan | Create a new Planner plan in a Microsoft 365 group | | update_plan | Update a Planner plan title | | list_buckets | List all buckets in a Planner plan | | create_bucket | Create a new bucket in a Planner plan | | update_bucket | Update a Planner bucket name | | prepare_delete_bucket | Prepare to delete a Planner bucket (two-phase) | | confirm_delete_bucket | Confirm Planner bucket deletion | | list_planner_tasks | List all tasks in a Planner plan | | list_my_planner_tasks | List all Planner tasks assigned to the signed-in user across every plan | | get_planner_task | Get details for a specific Planner task | | create_planner_task | Create a new task in a Planner plan | | update_planner_task | Update a Planner task | | prepare_delete_planner_task | Prepare to delete a Planner task (two-phase) | | confirm_delete_planner_task | Confirm Planner task deletion | | get_planner_task_details | Get task details (description, checklist, references) | | update_planner_task_details | Update task details (requires ETag from get_planner_task_details) | | list_planner_task_messages | List chat comments on a task (Comments tab) (Graph API beta) | | create_planner_task_message | Post a task comment with optional @mentions (Graph API beta; Tasks.ReadWrite) | | update_planner_task_message | Update a task comment (Graph API beta; Tasks.ReadWrite) | | prepare_delete_planner_task_message | Prepare to delete a task comment (two-phase) (Graph API beta) | | confirm_delete_planner_task_message | Confirm task comment deletion (Graph API beta) |

Read another user's mailbox, calendar, or OneDrive via /users/{upn}/..., relying on the signed-in user having delegate/shared access (Mail.Read.Shared / Calendars.Read.Shared / Files.Read.All). Read-only. These return raw Graph ids (not durable tokens, which are scoped to your own /me mailbox); pass the mailbox plus the raw id back to the matching get_* tool.

| Tool | Description | | --- | --- | | list_shared_mailbox_folders | List mail folders in a shared/delegated mailbox | | list_shared_mailbox_emails | List emails in a shared/delegated mailbox (optionally by folder) | | get_shared_mailbox_email | Get a single email from a shared/delegated mailbox by raw Graph id | | search_shared_mailbox_emails | Full-text search a shared/delegated mailbox | | list_shared_calendar_events | List events from another user's calendar (optionally within a window) | | get_shared_calendar_event | Get a single event from another user's calendar by raw Graph id | | list_shared_user_drive_items | List items in another user's OneDrive (root or a folder) | | search_shared_user_drive_items | Search another user's OneDrive |

Architecture

The server connects to Microsoft 365 cloud services via the Microsoft Graph API. Full read/write access across all 249 tools. No Outlook installation required. Works on macOS, Windows, and Linux.

Two-Phase Approval

Destructive operations (delete, send, move, forward, etc.) use a prepare/confirm pattern. The prepare_* call returns a preview and a short-lived approval token. The confirm_* call executes the action only with a valid token. This prevents accidental data loss.

ID Caching

The server maintains an internal ID mapping layer that assigns stable, durable identifier tokens for Graph API resources so tool callers do not need to track raw Graph object IDs.

ETag Caching

Planner resources use ETag-based concurrency control. The server caches ETags from read operations and automatically includes them in update/delete requests to prevent conflicts.

Source Layout

src/
  graph/             Microsoft Graph API integration
    auth/            MSAL authentication, device code flow, token cache
    client/          Graph client wrapper with response caching
    mappers/         Graph-to-internal type mappers
  tools/             MCP tool implementations (mail-send, mailbox-organization, etc.)
  types/             TypeScript type definitions
  utils/             Date parsing, error handling, utilities

Required Graph API Permissions

These delegated permissions are requested via Microsoft Graph:

| Permission | Purpose | |------------|---------| | Mail.ReadWrite | Read, create, and manage mail and drafts | | Mail.Send | Send mail as the signed-in user | | Calendars.ReadWrite | Read and manage calendar events | | Contacts.ReadWrite | Read and manage contacts | | Tasks.ReadWrite | Read and manage To Do tasks | | User.Read | Read user profile | | offline_access | Token refresh (maintain access) | | ChannelMessage.Read.All | Read Teams channel messages | | ChannelMessage.Send | Send Teams channel messages | | Channel.ReadBasic.All | Read Teams channel metadata | | Team.ReadBasic.All | Read Teams metadata | | Chat.ReadWrite | Read and send Teams chat messages | | ChatMessage.Send | Send Teams chat messages | | People.Read | Read relevant people | | User.ReadBasic.All | Read basic user profiles and photos | | Presence.Read.All | Read user presence/availability | | Group.Read.All | Read Microsoft 365 groups (for Planner) | | Mail.Read.Shared | Read mail in shared/delegated mailboxes | | Calendars.Read.Shared | Read shared/delegated calendars | | Files.Read.All | Read another user's OneDrive files (shared/delegate access) | | Sites.ReadWrite.All | Read and write SharePoint sites and document libraries |

Upgrading? These are delegated scopes, so any change to the list requires you to re-consent — re-run npx @jbctechsolutions/mcp-office365 auth --force so the refreshed token carries the new permissions. If a send or SharePoint write fails with GRAPH_PERMISSION_DENIED, your token predates the Mail.Send / Sites.ReadWrite.All scopes; re-authenticate to pick them up. (Custom app registrations via OUTLOOK_MCP_CLIENT_ID must also add these delegated permissions in Azure AD — Sites.ReadWrite.All may require admin consent.)

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | OUTLOOK_MCP_CLIENT_ID | Azure AD app (client) ID | (required) | | OUTLOOK_MCP_TENANT_ID | Azure AD tenant ID (required for single-tenant apps) | common |

Contributing

We welcome contributions. Please see our Contributing Guide for details.

Support policy: This is a part-time, hobby project. Response times are best-effort (typically 1-2 weeks for bug reports). See SUPPORT.md for details.

This project adheres to our Code of Conduct.

Support This Project

• Star this repository
• GitHub Sponsors
• Buy Me a Coffee
• PayPal

License

MIT License -- Copyright (c) 2026 JBC Tech Solutions, LLC. See LICENSE for details.