Content
# @jbctechsolutions/mcp-office365
[](https://www.npmjs.com/package/@jbctechsolutions/mcp-office365)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
MCP server for Microsoft 365 -- mail, calendar, contacts, tasks, teams, people, and planner.
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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
```bash
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)
```bash
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.
```bash
# Mail + calendar only, read-only
npx @jbctechsolutions/mcp-office365 --preset mail,calendar --read-only
```
In a client config, add them to `args`:
```json
{
"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`:
```json
{
"mcpServers": {
"office365": {
"command": "npx",
"args": ["-y", "@jbctechsolutions/mcp-office365"]
}
}
}
```
### Claude Code configuration
**Option 1: Plugin (recommended)** -- add to `~/.claude/settings.json`:
```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:
```json
{
"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](https://portal.azure.com) > 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](#required-graph-api-permissions) below
3. **Enable public client flows**: Authentication > Advanced settings > Allow public client flows > Yes
4. **Configure** with environment variables:
```json
{
"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.
## Remote connector mode (claude.ai)
Besides the local stdio mode above, the server can run as a **remote HTTP
connector** so it can be added to claude.ai (web/desktop) as a custom connector —
multi-user, each caller authenticated with their own Entra ID and acting on their
own Microsoft 365 data via On-Behalf-Of.
```bash
# Local dev (loopback only, unauthenticated):
npx @jbctechsolutions/mcp-office365 serve --port 3000
# Deployed (auth required): set OUTLOOK_MCP_CONNECTOR_URL and the Entra env vars.
node dist/index.js serve --host 0.0.0.0 --port 8080
```
It serves stateless Streamable HTTP at `POST /mcp`, a health check at
`GET /healthz`, and the RFC 9728 discovery document at
`/.well-known/oauth-protected-resource`. Auth turns on automatically when
`OUTLOOK_MCP_CONNECTOR_URL` is set; without it, the server refuses any
non-loopback bind so it can never be exposed unauthenticated.
Operational subcommands (run on the deployment host):
| Command | Purpose |
| --- | --- |
| `serve` | Run the remote connector (flags: `--host`, `--port`, plus the `--preset`/`--read-only`/`--confirm` surface flags above as a process-wide bound). |
| `revoke <oid>` | Offboard a user: deny-list their Entra oid + purge their durable state. `--readmit <oid>`, `--list`. |
| `audit` | Read the write/destructive audit trail. `--user <oid>`, `--since <iso\|ms>`, `--limit <n>`. |
Remote mode adds **per-user entitlements** (a pinned tool surface, widenable per
user), **revocation**, and a durable **audit log** of every write. Full setup,
the environment contract, deployment requirements, cost estimate, and the
end-user guide live in [`docs/remote/`](./docs/remote/):
[deployment](./docs/remote/deployment.md) ·
[provisioning](./docs/remote/provisioning.md) ·
[user guide](./docs/remote/user-guide.md) ·
[pilot runbook](./docs/remote/pilot-runbook.md).
## Tool Reference
All 249 tools listed below.
<details>
<summary><strong>Mail -- Reading (9)</strong></summary>
| 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 |
</details>
<details>
<summary><strong>Mail -- Sending & Drafts (16)</strong></summary>
| 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 |
</details>
<details>
<summary><strong>Mail -- Organization (24)</strong></summary>
| 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 |
</details>
<details>
<summary><strong>Mail -- Rules (4)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Mail -- Categories (4)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Mail -- Focused Inbox (4)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Mail -- Settings & Auto-Replies (4)</strong> <em>(Graph API)</em></summary>
| 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) |
</details>
<details>
<summary><strong>Mail -- Tips & Headers (3)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Attachments (2)</strong></summary>
| Tool | Description |
|------|-------------|
| `list_attachments` | List attachment metadata (name, size, type) for an email |
| `download_attachment` | Download an email attachment to disk |
</details>
<details>
<summary><strong>Calendar -- Events (11)</strong></summary>
| 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)* |
</details>
<details>
<summary><strong>Calendar -- Groups (2)</strong> <em>(Graph API)</em></summary>
| Tool | Description |
|------|-------------|
| `list_calendar_groups` | List all calendar groups |
| `create_calendar_group` | Create a new calendar group |
</details>
<details>
<summary><strong>Calendar -- Permissions (4)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Calendar -- Rooms (2)</strong> <em>(Graph API)</em></summary>
| Tool | Description |
|------|-------------|
| `list_room_lists` | List all room lists (building/floor groupings) |
| `list_rooms` | List meeting rooms, optionally filtered by room list |
</details>
<details>
<summary><strong>Contacts & Folders (13)</strong></summary>
| 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 |
</details>
<details>
<summary><strong>Tasks & Task Lists (13)</strong></summary>
| 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 |
</details>
<details>
<summary><strong>Checklist Items (5)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Linked Resources (4)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Task Attachments (4)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>OneNote (6)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Scheduling (2)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Mail -- Signatures (2)</strong> <em>(Graph API)</em></summary>
| Tool | Description |
|------|-------------|
| `set_signature` | Save an email signature auto-appended to outgoing emails |
| `get_signature` | Get the currently stored email signature |
</details>
<details>
<summary><strong>Teams -- Channels (8)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Teams -- Channel Messages (6)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Teams -- Chats (6)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>People & Presence (8)</strong> <em>(Graph API)</em></summary>
| 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 |
</details>
<details>
<summary><strong>Planner (23)</strong> <em>(Graph API; task comments use Graph beta, delegated only)</em></summary>
| 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)* |
</details>
<details>
<summary><strong>Shared Mailbox (8)</strong> <em>(Graph API)</em></summary>
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 |
</details>
## 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](CONTRIBUTING.md) 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](SUPPORT.md) for details.
This project adheres to our [Code of Conduct](CODE_OF_CONDUCT.md).
## Support This Project
- Star this repository
- [GitHub Sponsors](https://github.com/sponsors/jbctechsolutions)
- [Buy Me a Coffee](https://buymeacoffee.com/jbctechsolutions)
- [PayPal](https://paypal.me/jbctechsolutions)
## License
MIT License -- Copyright (c) 2026 JBC Tech Solutions, LLC. See [LICENSE](LICENSE) for details.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available