m365-mcp

Production-grade Microsoft 365 MCP server — Email, Calendar, Contacts, OneDrive, Teams, Tasks, and Users via delegated OAuth.

Built from the best of both office365-connector (delegated OAuth, multi-account) and mcp-microsoft365 (MCP protocol, full scope), with all the gaps fixed: pagination, rate limiting, retry logic, proper timezone handling, and TypeScript throughout.

Why this exists

This comparison reflects the code shipped in mcp-microsoft365 v1.0.0 and office365-connector v2.0.0 as reviewed on July 18, 2026.

| Feature | mcp-microsoft365 | office365-connector | m365-mcp | |---|---|---|---| | Auth flow | Client credentials (app-only) | Device code + client secret | Public-client device code | | Access model | Application permissions (tenant-wide) | Delegated (signed-in user) | Delegated (signed-in user) | | Client secret | Required | Required and stored locally | None ✅ | | MCP server | ✅ | ❌ (CLI scripts) | ✅ | | Multi-account | ❌ | ✅ | ✅ | | Pagination | ❌ | ❌ | ✅ | | Graph 429 retries | ❌ | ❌ (not implemented in shipped code) | ✅ | | Read-only mode | ❌ | ❌ | ✅ | | Email | ✅ | ✅ | ✅ | | Calendar | ✅ | ✅ | ✅ | | Contacts | ❌ | ❌ (documented, not shipped) | ✅ | | OneDrive | ✅ | ❌ | ✅ | | Teams | ✅ | ❌ | ✅ | | Tasks | ✅ | ❌ | ✅ | | Users | ✅ | ❌ | ✅ | | Implementation | TypeScript | JavaScript CLI | TypeScript | | Interface coverage | 19 MCP tools | CLI scripts | 43 MCP tools |

m365-mcp does not store a client secret or password. Tenant and client IDs are non-secret identifiers; sensitive OAuth access and refresh tokens are stored locally as permission-restricted plaintext files. See Security for the storage and revocation details.

Scope

Delegated permissions — the app acts AS YOU, not as the tenant. It can only access YOUR data:

• Mail.Read / Mail.ReadWrite / Mail.Send
• Calendars.Read / Calendars.ReadWrite
• Contacts.Read / Contacts.ReadWrite
• Files.Read.All (your OneDrive)
• Tasks.ReadWrite (To Do)
• Chat.Read / Chat.ReadWrite (Teams)
• User.Read + offline_access

These are delegated scopes, not tenant-wide application permissions. Set M365_MCP_READ_ONLY=true before authentication and when running the server to request only the read variants and disable mutating MCP tools.

Organization-wide mail application permissions such as Mail.Read.All are not used.

Setup

1. Create Azure Entra ID App Registration

1. Go to Azure Portal → App registrations
2. New registration
   • Name: m365-mcp
   • Supported account types: Single tenant (or multi-tenant if you manage your own tenant)
   • Redirect URI: leave this blank; device-code flow does not use one
3. Click Register
4. Go to Authentication → Advanced settings
5. Set "Allow public client flows" to Yes, then click Save

This is required for device-code OAuth. Do not create or configure a client secret; m365-mcp is a public client.

2. Add API Permissions

Under API Permissions → Add a permission → Microsoft Graph → Delegated permissions:

offline_access
User.Read
Mail.Read
Mail.ReadWrite
Mail.Send
Calendars.Read
Calendars.ReadWrite
Contacts.Read
Contacts.ReadWrite
Files.Read.All
Tasks.ReadWrite
Chat.Read
Chat.ReadWrite

Click Grant admin consent (or each user will consent individually during login).

Organization-wide user listing and lookup additionally requires delegated User.Read.All with admin consent. This broader scope is not requested by default.

3. Install

Install the published command-line tools:

npm install --global @sam2kb/m365-mcp

Or build from source:

# Clone
git clone https://github.com/sam2kb/m365-mcp.git
cd m365-mcp

# Install dependencies
npm install

# Build
npm run build

4. Add Your Account & Authenticate

m365-mcp-auth add work <tenant-id> <client-id> [email protected] "Work account"
m365-mcp-auth login --account=work

AADSTS7000218 or a missing client_secret / client_assertion error: Microsoft is treating the registration as a confidential client. Confirm that the configured Application (client) ID belongs to the registration you edited, then return to Authentication and verify Allow public client flows is saved as Yes. Do not work around this error by adding a client secret.

When running from a source checkout, use node dist/auth-cli.js instead of m365-mcp-auth.

Follow the on-screen URL + code to sign in. Access and refresh tokens are stored as plaintext JSON in ~/.m365-mcp/auth/ by default, protected with directory mode 0700 and file mode 0600 where supported. Set M365_MCP_AUTH_DIR to use another protected location.

5. Configure an MCP Client

The server uses standard MCP over stdio and works with any MCP client (Claude Desktop, Cursor, Continue, etc.).

OpenClaw

For the global npm installation, add this to your mcporter config at ~/.openclaw/mcporter.json:

{
  "mcpServers": {
    "m365": {
      "command": "m365-mcp",
      "args": [],
      "env": {
        "M365_ACCOUNT": "work",
        "M365_TIMEZONE": "America/Chicago"
      }
    }
  }
}

Or via mcporter CLI:

mcporter config add m365 --stdio "m365-mcp" \
  --env M365_ACCOUNT=work \
  --env M365_TIMEZONE=America/Chicago

For a source checkout, use "command": "node" with "args": ["/absolute/path/to/m365-mcp/dist/index.js"].

Then restart OpenClaw for the server to load.

Other MCP Clients

Use the same JSON config in your client's MCP server configuration — m365-mcp is a standard stdio MCP server with no client-specific requirements.

Multi-Account

# Add more accounts
node dist/auth-cli.js add personal <tenant2> <client2> [email protected] "Personal"
node dist/auth-cli.js add client <tenant3> <client3> [email protected] "Consulting"

# Authenticate each
node dist/auth-cli.js login --account=personal
node dist/auth-cli.js login --account=client

# Set default
node dist/auth-cli.js default work

# List
node dist/auth-cli.js list

Each account needs its own App Registration in its respective tenant. Tokens are isolated per account.

Available Tools (43)

📧 Mail (9 tools)

| Tool | Description | |---|---| | m365_mail_list | List emails (folder, filter, search, paginated) | | m365_mail_read | Read full email by ID | | m365_mail_send | Send email (to/cc/bcc, HTML or plain) | | m365_mail_reply | Reply / reply-all to an email | | m365_mail_search | Search emails across folders | | m365_mail_move | Move email to another folder | | m365_mail_delete | Delete email | | m365_mail_mark_read | Mark as read/unread | | m365_mail_folders | List all mail folders with counts |

📅 Calendar (7 tools)

| Tool | Description | |---|---| | m365_calendar_list | Events in a date range (paginated) | | m365_calendar_today | Today's events, nicely formatted | | m365_calendar_week | Week view grouped by day | | m365_calendar_create | Create event (optional Teams meeting) | | m365_calendar_update | Update event | | m365_calendar_delete | Cancel event with message | | m365_calendar_availability | Free/busy lookup |

👤 Contacts (11 tools)

| Tool | Description | |---|---| | m365_contacts_list | List by folder and filter by one or more exact categories (any/all) | | m365_contacts_search | Search by name, email, or company | | m365_contacts_read | Full contact details | | m365_contacts_create | Create with multiple emails, phones, categories, addresses, and work or personal details | | m365_contacts_update | Update or clear contact fields and category assignments | | m365_contacts_delete | Move a contact to Deleted Items | | m365_contacts_categories_list | List unique categories in the default or selected folder with usage counts | | m365_contacts_folders_list | List top-level or child contact folders | | m365_contacts_folder_create | Create a child contact folder | | m365_contacts_folder_update | Rename or move a contact folder | | m365_contacts_folder_delete | Delete a non-default contact folder |

Outlook categories are tags stored on each contact; contact folders are containers. Category filtering is exact and case-insensitive, supports any/all matching, and can be combined with folder selection. Folder tools manage top-level folders and one direct child level, keeping the interface predictable.

📁 OneDrive (5 tools)

| Tool | Description | |---|---| | m365_files_list | List files/folders (paginated) | | m365_files_search | Search files | | m365_files_read | Read text file content | | m365_files_info | File/folder metadata | | m365_files_create_folder | Create folder |

💬 Teams (3 tools)

| Tool | Description | |---|---| | m365_teams_chats | List your chats | | m365_teams_messages | Get chat messages | | m365_teams_send | Send chat message |

✅ Tasks (5 tools)

| Tool | Description | |---|---| | m365_tasks_lists | List To Do lists | | m365_tasks_list | List tasks in a list | | m365_tasks_create | Create task | | m365_tasks_update | Update task | | m365_tasks_delete | Delete task |

👥 Users (3 tools)

| Tool | Description | |---|---| | m365_users_list | List org users | | m365_users_profile | Get user profile | | m365_users_manager | Get user's manager |

Development

npm install
npm run dev    # tsx watch mode
npm run build  # compile TypeScript

Security

• Delegated OAuth — the app acts as the authenticated user; it does not use application credentials or tenant-wide mail permissions.
• Device code flow — you never type your password into anything but Microsoft's login page.
• Sensitive reads — mail, files, calendar entries, contacts, Teams messages, tasks, and user profiles can enter the MCP client's model context.
• Real side effects — send, reply, move, create, update, and delete tools change Microsoft 365 data. Configure your MCP client to require explicit user approval before it invokes them.
• MCP safety annotations — every tool declares read-only, destructive, idempotent, and open-world hints for clients that enforce tool policies.
• Enforced read-only mode — set M365_MCP_READ_ONLY=true both when authenticating and running the server. The auth flow requests read-only Graph scopes, mutating tools are omitted from discovery, and direct calls are blocked.
• Local token storage — access and refresh tokens are plaintext JSON protected by 0700 directories and 0600 files where supported. Protect ~/.m365-mcp/auth/ or your configured M365_MCP_AUTH_DIR.
• Auto-refresh — tokens refreshed before expiry, expired refresh tokens trigger re-auth.
• No telemetry, no analytics, no third-party calls besides login.microsoftonline.com and graph.microsoft.com.

To delete a local token, remove its account:

m365-mcp-auth remove work

If a token or device may be compromised, also revoke the application's consent from the Microsoft account or Entra ID portal. Re-authenticate after changing M365_MCP_READ_ONLY so the stored token reflects the intended scope set.

License

MIT