{"id":50803376,"url":"https://github.com/guinacio/mcp-microsoft","last_synced_at":"2026-06-12T22:33:32.740Z","repository":{"id":360582606,"uuid":"1197894342","full_name":"guinacio/mcp-microsoft","owner":"guinacio","description":"MCP server for Microsoft 365 — Mail, Calendar, OneDrive, Teams, Contacts, SharePoint, and more","archived":false,"fork":false,"pushed_at":"2026-05-27T02:00:36.000Z","size":1278,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-27T04:03:42.873Z","etag":null,"topics":["claude","fastmcp","mcp","mcp-server","microsoft","microsoft365","onedrive","outlook","python","sharepoint","teams"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guinacio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T01:13:09.000Z","updated_at":"2026-05-27T02:00:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/guinacio/mcp-microsoft","commit_stats":null,"previous_names":["guinacio/mcp-microsoft"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/guinacio/mcp-microsoft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guinacio%2Fmcp-microsoft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guinacio%2Fmcp-microsoft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guinacio%2Fmcp-microsoft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guinacio%2Fmcp-microsoft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guinacio","download_url":"https://codeload.github.com/guinacio/mcp-microsoft/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guinacio%2Fmcp-microsoft/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34265491,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","fastmcp","mcp","mcp-server","microsoft","microsoft365","onedrive","outlook","python","sharepoint","teams"],"created_at":"2026-06-12T22:33:30.628Z","updated_at":"2026-06-12T22:33:32.728Z","avatar_url":"https://github.com/guinacio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-microsoft\n\n![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)\n![License MIT](https://img.shields.io/badge/license-MIT-green)\n![MCP](https://img.shields.io/badge/MCP-compatible-purple)\n[![Tests](https://github.com/guilhermeinacio/mcp-microsoft/actions/workflows/ci.yml/badge.svg)](https://github.com/guilhermeinacio/mcp-microsoft/actions/workflows/ci.yml)\n\nMicrosoft 365 MCP server — Mail, Calendar, OneDrive, SharePoint, Contacts, and Teams via the Microsoft Graph API, with multi-account support.\n\n## Overview\n\n`mcp-microsoft` is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude (and any other MCP client) full access to your Microsoft 365 account. It covers six surface areas of the Microsoft Graph API: email, calendar, OneDrive file storage, SharePoint, contacts, and Teams — **93 tools** in total.\n\nThe server works with both personal Microsoft accounts (Outlook.com, Live) and enterprise accounts (Azure AD / Entra ID) using a single App Registration. Teams and SharePoint require a work or school account and are gated behind feature flags (`MCP_ENABLE_TEAMS` / `MCP_ENABLE_SHAREPOINT`). On manual installs, they auto-enable for corporate-oriented tenant values (`common`, `organizations`, or a specific tenant ID). In Claude Desktop / MCPB, the installer toggles remain authoritative. You can always override the default with the environment flags to force either service on or off. Teams meeting transcripts/recordings and Copilot AI insights are separate explicit opt-ins so the server does not request those additional scopes unless you enable them.\n\nMulti-account support is a first-class feature. Named profiles let you configure separate client IDs for each account and switch between them on any tool call by passing `profile=\"work\"`. Profiles and MSAL token caches are stored in `~/.microsoft-mcp/` and survive server restarts without re-authentication.\n\nThe server ships as an MCPB bundle (`mcp-microsoft.mcpb`) for zero-friction installation through the Claude Desktop Extension installer. It can also be run from source or wired directly into `claude_desktop_config.json`. Built with [FastMCP](https://github.com/jlowin/fastmcp), MSAL, and async httpx.\n\n## Features\n\n### Tools (93 total)\n\n#### Mail (25 tools)\n\n- `list_emails` — list messages from any folder with pagination and unread filter\n- `read_email` — fetch the full body of a message by ID (supports summary mode)\n- `search_emails` — search using Microsoft Graph KQL `$search` syntax (max 25 results)\n- `filter_emails` — find emails by sender, recipient, subject, date range, or attachments with full pagination\n- `send_email` — compose and send a new message (to/cc/bcc, HTML or plain text)\n- `reply_email` — reply or reply-all to an existing message\n- `forward_email` — forward a message to one or more recipients\n- `mark_as_read` / `mark_as_unread` — toggle read state\n- `move_email` — move to any folder by well-known name or folder ID\n- `trash_email` — soft-delete to Deleted Items (recoverable)\n- `delete_email` — permanently delete a message (irreversible)\n- `bulk_move_emails` — move multiple messages to a folder in one operation\n- `bulk_trash_emails` — move multiple messages to Deleted Items\n- `bulk_delete_emails` — permanently delete multiple messages (irreversible)\n- `create_draft` / `get_draft` / `list_drafts` / `update_draft` / `send_draft` — full draft lifecycle\n- `list_folders` / `create_folder` / `delete_folder` — manage mailbox folders\n- `list_attachments` / `download_attachment` — inspect and save attachments\n\n#### Calendar (10 tools)\n\n- `list_calendars` — enumerate all calendars in the mailbox\n- `list_events` — list events from a calendar with optional date filtering\n- `list_upcoming_events` — list events using calendarView with recurring-instance expansion\n- `get_event` — fetch full event details including attendees, body, and recurrence\n- `create_event` — create an event (subject, datetime, timezone, attendees, location, online meeting flag)\n- `update_event` / `delete_event` — modify or remove an event\n- `rsvp_event` — accept, tentatively accept, or decline an invitation\n- `get_free_busy` — check availability for one or more people in a time window\n- `find_meeting_times` — get meeting time suggestions for a set of attendees\n\n#### OneDrive (8 tools)\n\n- `list_drive_items` — browse files and folders by path or item ID\n- `get_drive_item` — get metadata for a specific file or folder\n- `search_drive` — full-text search across OneDrive\n- `upload_file` — upload a local file (auto-switches to resumable upload for files over 4 MB)\n- `download_file` — download a file to a local path\n- `create_drive_folder` — create a new folder at any path\n- `move_or_copy_item` — move or copy items within OneDrive\n- `delete_drive_item` — delete a file or folder (moves to recycle bin)\n\n#### SharePoint (12 tools)\n\n\u003e SharePoint tools require a work or school account (Azure AD / Entra ID). They are not available for personal Outlook.com / Live accounts, which do not support the `Sites.ReadWrite.All` Graph permission. `Sites.ReadWrite.All` requires one-time admin consent in enterprise tenants.\n\n- `search_sharepoint_sites` — search or list SharePoint sites the user can access\n- `get_sharepoint_site` — get details of a specific site\n- `list_site_libraries` — list document libraries in a site\n- `list_site_files` / `get_site_file` — browse files in a document library\n- `upload_to_site` / `download_from_site` — transfer files to/from SharePoint\n- `list_site_lists` — list all SharePoint lists in a site\n- `get_list_items` / `create_list_item` / `update_list_item` / `delete_list_item` — manage list records\n\n#### Contacts (8 tools)\n\n- `list_contacts` — list contacts with optional folder scope and field selection\n- `get_contact` — retrieve a single contact by ID\n- `create_contact` — create a new contact with name, email, phone, org, and notes\n- `update_contact` — update any subset of contact fields\n- `delete_contact` — delete a contact by ID (irreversible)\n- `list_contact_folders` — enumerate contact folders in the mailbox\n- `search_contacts` — search contacts by display name or email\n- `get_contact_photo` — fetch a contact's profile photo as base64 or save to disk\n\n#### Teams (25 tools)\n\n\u003e Teams tools require a work or school account (Azure AD / Entra ID) with a specific tenant ID. They are not available for personal Outlook.com / Live accounts.\n\n- `teams_list_joined` / `teams_get` — list and inspect teams\n- `teams_list_channels` / `teams_get_channel` / `teams_create_channel` — manage channels\n- `teams_list_channel_messages` / `teams_get_channel_message` / `teams_send_channel_message` — read and post channel messages\n- `teams_reply_to_channel_message` / `teams_list_message_replies` — manage channel threads\n- `teams_list_chats` / `teams_get_chat` / `teams_list_chat_messages` / `teams_send_chat_message` / `teams_create_chat` — 1:1 and group chats\n- `teams_create_meeting` / `teams_get_meeting` / `teams_find_meeting_by_url` / `teams_list_meetings` — online meetings with join URLs\n- `teams_list_meeting_transcripts` / `teams_get_meeting_transcript` — Teams meeting transcript metadata and VTT content\n- `teams_list_meeting_recordings` / `teams_download_meeting_recording` — Teams meeting recording metadata and downloads\n- `teams_list_meeting_ai_insights` / `teams_get_meeting_ai_insight` — Copilot meeting recap/insight metadata and full detail\n\n\u003e Teams meeting transcripts and recordings require explicit opt-in via `MCP_ENABLE_TEAMS_MEETING_ARTIFACTS` plus the delegated permissions `OnlineMeetingTranscript.Read.All` and `OnlineMeetingRecording.Read.All`. Teams AI insights require explicit opt-in via `MCP_ENABLE_TEAMS_AI_INSIGHTS`, the delegated permission `OnlineMeetingAiInsight.Read.All`, and Microsoft 365 Copilot licensing.\n\n#### Profile Management (5 tools)\n\n- `list_ms_profiles` — list all configured profiles and which is the default\n- `add_ms_profile` — add a new account (name, client_id, tenant_id)\n- `remove_ms_profile` — remove a profile and delete its cached tokens\n- `authenticate_ms_profile` — trigger interactive OAuth for a profile\n- `set_default_ms_profile` — change which profile is used when none is specified\n\n## Installation\n\n### Option A: Claude Desktop Extension (MCPB) — Recommended\n\n```bash\nnpx @anthropic-ai/mcpb install mcp-microsoft-0.6.0.mcpb\n```\n\nThe installer prompts for your Azure App Registration details (see [Azure Setup](#azure-setup)):\n\n| Prompt | Description |\n|---|---|\n| **Azure Client ID** | Application (client) ID from your App Registration |\n| **Tenant ID** | `common` for personal + work, `consumers` for personal only, or your org's tenant ID/domain |\n| **Credentials Directory** | Optional. Defaults to `~/.microsoft-mcp/` |\n| **Enable Teams Tools** | Toggle Teams tools on/off (requires work/school account) |\n| **Enable Teams Meeting Artifacts** | Toggle Teams transcript/recording tools on/off (requires work/school account and extra Graph permissions) |\n| **Enable Teams AI Insights** | Toggle Teams Copilot AI insight tools on/off (requires work/school account, extra Graph permissions, and Copilot licensing) |\n| **Enable SharePoint Tools** | Toggle SharePoint tools on/off (requires work/school account) |\n\nA `default` profile is created automatically from these values.\n\n### Option B: From Source\n\n```bash\ngit clone https://github.com/guilhermeinacio/mcp-microsoft.git\ncd mcp-microsoft\nuv sync\nexport MS365_CLIENT_ID=your-client-id\nexport MS365_TENANT_ID=common\n# Optional overrides:\n# export MCP_ENABLE_SHAREPOINT=false\n# export MCP_ENABLE_TEAMS=false\n# export MCP_ENABLE_TEAMS_MEETING_ARTIFACTS=true\n# export MCP_ENABLE_TEAMS_AI_INSIGHTS=true\nuv run mcp-microsoft\n```\n\n### Option C: Add to claude_desktop_config.json\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-microsoft\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/mcp-microsoft\", \"mcp-microsoft\"],\n      \"env\": {\n        \"MS365_CLIENT_ID\": \"your-client-id\",\n        \"MS365_TENANT_ID\": \"common\"\n      }\n    }\n  }\n}\n```\n\n## Azure Setup\n\nYou need an Azure App Registration to get a `client_id`. This is a one-time step.\n\n1. Go to [portal.azure.com](https://portal.azure.com) → **Azure Active Directory** → **App registrations** → **New registration**.\n2. Name it anything (e.g., `mcp-microsoft`).\n3. Under **Supported account types**, choose based on your use case:\n   - *Personal Microsoft accounts only* — Outlook.com / Live users\n   - *Accounts in any organizational directory and personal Microsoft accounts* — personal and work\n4. Under **Redirect URI**, select **Mobile and desktop applications** and enter `http://localhost`.\n5. Under **Authentication**, enable **Allow public client flows** (required for the interactive loopback OAuth flow — no client secret needed).\n6. Go to **API permissions** → **Add a permission** → **Microsoft Graph** → **Delegated permissions** and add:\n   - `Mail.ReadWrite`\n   - `Mail.Send`\n   - `Calendars.ReadWrite`\n   - `Contacts.ReadWrite`\n   - `Files.ReadWrite`\n   - `offline_access` *(usually pre-added)*\n7. If you want to enable **SharePoint** tools, also add `Sites.ReadWrite.All`.\n8. If you want to enable **Teams** tools, also add:\n   - `Team.ReadBasic.All`\n   - `Channel.ReadBasic.All`\n   - `Channel.Create`\n   - `ChannelMessage.Read.All`\n   - `ChannelMessage.Send`\n   - `Chat.ReadWrite`\n   - `Chat.Create`\n   - `OnlineMeetings.ReadWrite`\n9. If you want to enable **Teams meeting transcripts and recordings**, also add:\n   - `OnlineMeetingTranscript.Read.All`\n   - `OnlineMeetingRecording.Read.All`\n10. If you want to enable **Teams Copilot AI insights**, also add:\n   - `OnlineMeetingAiInsight.Read.All`\n   All users of applications that call this API need a Microsoft 365 Copilot license.\n11. For admin-restricted permissions such as `Sites.ReadWrite.All`, click **Grant admin consent**. Your IT administrator must approve this once per tenant.\n12. From the **Overview** page, copy the **Application (client) ID** and, if targeting a specific tenant, the **Directory (tenant) ID**.\n\nFor a detailed walkthrough with screenshots, see [`docs/azure-setup.md`](docs/azure-setup.md).\n\n## Account Type Compatibility\n\n| Module | Personal (Outlook.com/Live) | Work/School (Azure AD/Entra) |\n|---|---|---|\n| Mail | Yes | Yes |\n| Calendar | Yes | Yes |\n| OneDrive | Yes | Yes |\n| Contacts | Yes | Yes |\n| SharePoint | No | Yes (admin consent required) |\n| Teams | No | Yes |\n\nPersonal accounts use `tenant_id=consumers`. For access to both personal and work accounts via a single profile, use `tenant_id=common`. Teams transcript/recording and AI-insight APIs remain work-account-only and are additional explicit opt-ins on top of the base Teams tools.\n\n## Profile Management\n\nThe server supports multiple Microsoft 365 accounts as named profiles. Each profile has its own `client_id`, `tenant_id`, and MSAL token cache.\n\n**Bootstrap:** On first start, if `MS365_CLIENT_ID` is set (via the MCPB installer or environment variable), a `default` profile is created and persisted to `profiles.json` automatically. If the variable is not set, the server starts with zero profiles and you must call `add_ms_profile`.\n\n**Add accounts:**\n\n```\nadd_ms_profile(name=\"personal\", client_id=\"...\", tenant_id=\"consumers\")\nadd_ms_profile(name=\"work\", client_id=\"...\", tenant_id=\"mycompany.onmicrosoft.com\")\n```\n\n**Use a specific profile** on any tool call:\n\n```\nlist_emails(folder=\"Inbox\", profile=\"work\")\nsearch_drive(query=\"Q1 report\", profile=\"personal\")\n```\n\n**Authenticate** (opens a browser window for OAuth the first time):\n\n```\nauthenticate_ms_profile(profile=\"work\")\n```\n\n**List profiles:**\n\n```\nlist_ms_profiles()\n```\n\n**Change the default:**\n\n```\nset_default_ms_profile(profile=\"work\")\n```\n\nProfiles are stored in `~/.microsoft-mcp/profiles.json`. Token caches are stored as `~/.microsoft-mcp/msal_cache_{name}.bin` and encrypted at rest via OS-native APIs (DPAPI on Windows, Keychain on macOS, libsecret on Linux) using [msal-extensions](https://github.com/AzureAD/microsoft-authentication-extensions-for-python). Legacy plaintext caches from older versions are migrated automatically on first run. After the first interactive login, MSAL handles token refresh silently.\n\n\u003e **Security note:** `profiles.json` contains the client/tenant IDs only — it has no secrets but is restricted to mode `0600` on POSIX. The `msal_cache_*.bin` files hold encrypted refresh tokens; do not commit either to version control. `MS365_CLIENT_ID` is not a secret and can be committed.\n\u003e\n\u003e **Disabling destructive tools:** set `MCP_DISABLE_DELETION_TOOLS=1` to suppress registration of all permanent-delete tools (`delete_email`, `bulk_delete_emails`, `delete_event`, `delete_contact`, `delete_folder`, `delete_drive_item`, `delete_list_item`, `remove_ms_profile`). Recoverable variants such as `trash_email` remain available.\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `MS365_CLIENT_ID` | Yes (for bootstrap) | — | Azure App Registration client ID for the default profile |\n| `MS365_TENANT_ID` | No | `common` | Tenant ID for the default profile |\n| `MS365_CREDENTIALS_DIR` | No | `~/.microsoft-mcp/` | Directory for `profiles.json` and token caches |\n| `MCP_ENABLE_SHAREPOINT` | No | auto-detect | Set to `true` to force-enable SharePoint tools or `false` to force-disable them |\n| `MCP_ENABLE_TEAMS` | No | auto-detect | Set to `true` to force-enable Teams tools or `false` to force-disable them |\n| `MCP_ENABLE_TEAMS_MEETING_ARTIFACTS` | No | `false` | Set to `true` to register Teams transcript and recording tools and request the related delegated scopes |\n| `MCP_ENABLE_TEAMS_AI_INSIGHTS` | No | `false` | Set to `true` to register Teams Copilot AI insight tools and request `OnlineMeetingAiInsight.Read.All` |\n| `MCP_DISABLE_DELETION_TOOLS` | No | `false` | Set to `true` to suppress registration of all permanent-delete tools (recoverable trash variants remain) |\n\n`MS365_CLIENT_ID`, `MS365_TENANT_ID`, and `MS365_CREDENTIALS_DIR` are only used to bootstrap the `default` profile on first run. `MCP_ENABLE_TEAMS` and `MCP_ENABLE_SHAREPOINT` participate in the existing auto-detection behavior; `MCP_ENABLE_TEAMS_MEETING_ARTIFACTS` and `MCP_ENABLE_TEAMS_AI_INSIGHTS` are explicit opt-ins only.\n\n## Development\n\n```bash\n# Install dependencies\nuv sync\n\n# Start the MCP server (stdio mode)\nuv run mcp-microsoft\n\n# Run the test suite\nuv run pytest -q\n\n# Rebuild the MCPB bundle\nnpx @anthropic-ai/mcpb pack\n```\n\nTool implementations are organized by surface area under `src/mcp_microsoft/tools/`: `mail.py`, `drafts.py`, `folders.py`, `attachments.py`, `calendar.py`, `onedrive.py`, `sharepoint.py`, `contacts.py`, `teams.py`, `profiles.py`. Authentication is handled by [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-python) with a per-profile serializable token cache. HTTP calls go through a shared async `httpx` client initialized at server startup.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguinacio%2Fmcp-microsoft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguinacio%2Fmcp-microsoft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguinacio%2Fmcp-microsoft/lists"}