@teamnetwork/m365-mcp-server

A Model Context Protocol (MCP) server for Microsoft 365 Email and Calendar access, using app-only (client credentials) authentication — no user login flows required.

Supports multiple accounts, shared mailboxes, per-mailbox read-only access control, folder navigation, and date/content filtering. Designed to be extended with Teams support later.

Prerequisites

• Node.js 18+
• A Microsoft 365 tenant with an Azure AD app registration configured for app-only access (see Admin Setup below)

Installation

npm install -g @teamnetwork/m365-mcp-server

Or run directly without installing:

npx @teamnetwork/m365-mcp-server

Configuration

Create a JSON config file (e.g. m365-config.json) based on the example below. Keep this file secure — it contains your client secret.

{
  "connection": {
    "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "clientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "clientSecret": "your-client-secret"
  },
  "accounts": [
    {
      "id": "main",
      "displayName": "Main Organisation",
      "mailboxes": [
        { "email": "[email protected]", "readonly": false },
        { "email": "[email protected]", "readonly": true, "displayName": "Shared (read-only)" }
      ]
    },
    {
      "id": "partner",
      "displayName": "Partner Tenant",
      "tenantId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "clientId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "clientSecret": "partner-secret",
      "mailboxes": [
        { "email": "[email protected]", "readonly": false }
      ]
    }
  ]
}

Config notes

• The top-level connection block provides default credentials for all accounts.
• Each account can override tenantId, clientId, and/or clientSecret individually — useful for multi-tenant setups.
• readonly: true mailboxes block all write operations (send, reply, move, create/update events) at the server level.

Set the path to your config via the M365_CONFIG_PATH environment variable:

export M365_CONFIG_PATH=/path/to/m365-config.json

Claude Desktop / Claude Code Setup

Add the following to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "m365": {
      "command": "npx",
      "args": ["@teamnetwork/m365-mcp-server"],
      "env": {
        "M365_CONFIG_PATH": "/path/to/m365-config.json"
      }
    }
  }
}

If installed globally, you can use the m365-mcp command instead:

{
  "mcpServers": {
    "m365": {
      "command": "m365-mcp",
      "env": {
        "M365_CONFIG_PATH": "/path/to/m365-config.json"
      }
    }
  }
}

Default Mailbox Behaviour

All email and calendar tools accept optional accountId and mailbox parameters. When either is omitted:

• accountId defaults to the first account in the config file.
• mailbox defaults to the first mailbox listed under the resolved account.

Config file ordering is the source of truth — put your primary account and mailbox first. Use list_mailboxes to see which account and mailbox are marked isDefault: true.

Operations always target exactly one mailbox per request, either the default or a specific one provided by name.

Available Tools

Email

| Tool | Description | |---|---| | list_mailboxes | List configured accounts and mailboxes with read/write status | | list_folders | List mail folders (top-level or child folders) | | list_messages | List messages with optional filters: date range, subject, body keyword, sender | | get_message | Get full message details. Set includeBody, includeAttachments, or includeInternetMessageHeaders as needed | | send_message | Send an email (non-readonly mailboxes only) | | reply_message | Reply or reply-all to a message (non-readonly mailboxes only) | | move_message | Move a message to another folder (non-readonly mailboxes only) | | list_message_attachments | List all attachments on a message (file, item, and reference types) | | download_attachment | Download a file attachment as base64. Images returned as MCP image content; reference attachments return their preview URL |

Calendar

| Tool | Description | |---|---| | list_calendars | List calendars for a mailbox | | list_events | List events in a date range (recurring events expanded into instances) | | get_event | Get full event details | | create_event | Create a new event (non-readonly mailboxes only) | | update_event | Update an existing event (non-readonly mailboxes only) |

Admin Setup

Before the server can access mailboxes, a tenant admin must complete the following steps.

1. Register an Azure AD Application

In the Azure Portal → App registrations → New registration:

• Set a name (e.g. M365 MCP Server)
• Note the Application (client) ID and Directory (tenant) ID
• Under Certificates & secrets, create a client secret and note the value

Grant the following Application permissions (not Delegated) and click Grant admin consent:

| Permission | Required for | |---|---| | Mail.Read | Reading email | | Mail.ReadWrite | Moving messages | | Mail.Send | Sending and replying | | Calendars.Read | Reading calendar events | | Calendars.ReadWrite | Creating and updating events |

2. Restrict Mailbox Access (Recommended)

By default, the above permissions grant access to all mailboxes in the tenant. Use an ApplicationAccessPolicy in Exchange Online to restrict access to only the mailboxes in your config.

Run the following in Exchange Online PowerShell:

# Create a mail-enabled security group and add the allowed mailboxes
New-DistributionGroup -Name "MCP-Allowed-Mailboxes" -Type Security
Add-DistributionGroupMember -Identity "MCP-Allowed-Mailboxes" -Member "[email protected]"
Add-DistributionGroupMember -Identity "MCP-Allowed-Mailboxes" -Member "[email protected]"

# Restrict the app to only those mailboxes
New-ApplicationAccessPolicy `
  -AppId "<your-client-id>" `
  -PolicyScopeGroupId "MCP-Allowed-Mailboxes" `
  -AccessRight RestrictAccess `
  -Description "Restrict MCP server to configured mailboxes"

# Verify (should return Granted for allowed mailboxes)
Test-ApplicationAccessPolicy -AppId "<your-client-id>" -Identity "[email protected]"

Note: Policy changes can take up to 1 hour to propagate. Shared mailboxes must be added to the group directly.

Security

• Credentials are never logged. The server scrubs secrets, tokens, and email body content from all log output.
• All Graph API calls use the /users/{email}/... path (application permissions), never /me/.
• Write operations are blocked at the server level for any mailbox marked readonly: true in the config — this check happens before any network call is made.
• The config file should be kept outside your project directory and never committed to source control. Use restrictive file permissions (chmod 600 on Linux/macOS).

License

MIT