msgraph-mcp

MCP server for Microsoft 365 — Mail, Calendar, Teams, OneDrive via Microsoft Graph API.

No Copilot license required. Uses device code login with your own Azure app. Only accesses your own data.

---

Quick Start

npx msgraph-mcp --client-id YOUR_CLIENT_ID --tenant-id YOUR_TENANT_ID

On first run it shows a device code. Sign in at https://microsoft.com/devicelogin. Tokens are cached at ~/.ms-graph-mcp/token-cache.json.

---

Azure App Setup

1. Create App Registration

1. Go to Azure Portal → App registrations
2. Click New registration
3. Name: anything (e.g. my-graph-mcp)
4. Supported account types: Single tenant (or Multitenant if needed)
5. Click Register
6. Copy the Application (client) ID and Directory (tenant) ID

2. Enable Device Code Flow

1. In your app → Authentication
2. Click Add a platform → Mobile and desktop applications
3. Check https://login.microsoftonline.com/common/oauth2/nativeclient
4. Under Advanced settings → enable Allow public client flows → Yes
5. Click Save

3. Add API Permissions

Go to API permissions → Add a permission → Microsoft Graph → Delegated:

Permission	Purpose
Mail.Read	Read emails
Mail.Send	Send emails
Calendars.Read	Read calendar
Calendars.ReadWrite	Create/update events
Chat.Read	Read Teams chats
Channel.ReadBasic.All	List channels in Teams
ChannelMessage.Read.All	Read Teams channel messages ⚠️ requires admin consent
ChannelMessage.Send	Send messages to channels
Team.ReadBasic.All	List Teams
Files.Read.All	Read OneDrive files
User.Read	Read user profile
offline_access	Keep tokens refreshed

Note: ChannelMessage.Read.All requires an admin to Grant admin consent. All other permissions work with user consent only.

---

Configuration

CLI flags

msgraph-mcp --client-id <id> --tenant-id <id>

Environment variables

export MS_GRAPH_CLIENT_ID=your-client-id
export MS_GRAPH_TENANT_ID=your-tenant-id
msgraph-mcp

MCP client config (Claude, Cursor, etc.)

{
  "mcpServers": {
    "msgraph": {
      "command": "npx",
      "args": ["-y", "msgraph-mcp", "--client-id", "YOUR_ID", "--tenant-id", "YOUR_TENANT"]
    }
  }
}

Or with env vars:

{
  "mcpServers": {
    "msgraph": {
      "command": "npx",
      "args": ["-y", "msgraph-mcp"],
      "env": {
        "MS_GRAPH_CLIENT_ID": "YOUR_ID",
        "MS_GRAPH_TENANT_ID": "YOUR_TENANT"
      }
    }
  }
}

Clear cached tokens

msgraph-mcp --logout

---

Tools

Mail

Tool	Description	Parameters
list_emails	List emails from a folder	folder (inbox/sentitems/drafts), limit, unread_only
get_email	Get full email with body	id
send_email	Send an email	to[], subject, body, body_type (text/html), cc[]
reply_email	Reply to an email	id, body

Calendar

Tool	Description	Parameters
list_events	List events in date range	start_datetime, end_datetime, limit
get_event	Get event details	id
create_event	Create a calendar event	subject, start_datetime, end_datetime, timezone, body, attendees[], is_online_meeting, location

Teams

Tool	Description	Parameters
list_teams	List joined Teams	—
list_channels	List channels in a Team	team_id
list_channel_messages	Get recent channel messages	team_id, channel_id, limit
send_channel_message	Post to a channel	team_id, channel_id, body, content_type
list_chats	List DMs and group chats	limit
send_chat_message	Send a DM or group message	chat_id, body, content_type

OneDrive

Tool	Description	Parameters
list_files	List files in a folder	folder_path, limit
search_files	Search files across OneDrive	query, limit
get_file_info	Get file metadata	item_id

User

Tool	Description	Parameters
get_me	Get your profile	—
get_user	Get another user's profile	user_id (email or object ID)

---

Integrations

All tools use the same base config. Replace YOUR_CLIENT_ID and YOUR_TENANT_ID throughout.

Sign-in note: First run opens a device code prompt. Sign in once at https://microsoft.com/devicelogin — tokens auto-refresh after that.

---

Claude Desktop

Config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "msgraph": {
      "command": "npx",
      "args": ["-y", "msgraph-mcp", "--client-id", "YOUR_CLIENT_ID", "--tenant-id", "YOUR_TENANT_ID"]
    }
  }
}

Restart Claude Desktop after saving.

---

Claude Code (CLI)

claude mcp add msgraph npx -- -y msgraph-mcp --client-id YOUR_CLIENT_ID --tenant-id YOUR_TENANT_ID

Or add to .claude/settings.json in your project:

{
  "mcpServers": {
    "msgraph": {
      "command": "npx",
      "args": ["-y", "msgraph-mcp", "--client-id", "YOUR_CLIENT_ID", "--tenant-id", "YOUR_TENANT_ID"]
    }
  }
}

---

Cursor

Global config: ~/.cursor/mcp.json Project config: .cursor/mcp.json (checked into repo — use env vars to avoid committing IDs)

{
  "mcpServers": {
    "msgraph": {
      "command": "npx",
      "args": ["-y", "msgraph-mcp"],
      "env": {
        "MS_GRAPH_CLIENT_ID": "YOUR_CLIENT_ID",
        "MS_GRAPH_TENANT_ID": "YOUR_TENANT_ID"
      }
    }
  }
}

---

Windsurf

Config file: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "msgraph": {
      "command": "npx",
      "args": ["-y", "msgraph-mcp"],
      "env": {
        "MS_GRAPH_CLIENT_ID": "YOUR_CLIENT_ID",
        "MS_GRAPH_TENANT_ID": "YOUR_TENANT_ID"
      }
    }
  }
}

---

Cline (VS Code extension)

Open VS Code settings (Cmd+,) → search cline.mcpServers → Edit in settings.json:

{
  "cline.mcpServers": {
    "msgraph": {
      "command": "npx",
      "args": ["-y", "msgraph-mcp", "--client-id", "YOUR_CLIENT_ID", "--tenant-id", "YOUR_TENANT_ID"]
    }
  }
}

Or use Cline's MCP panel → Add Server → paste the config.

---

Continue (VS Code / JetBrains extension)

Config file: ~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "msgraph",
      "command": "npx",
      "args": ["-y", "msgraph-mcp", "--client-id", "YOUR_CLIENT_ID", "--tenant-id", "YOUR_TENANT_ID"]
    }
  ]
}

---

Zed

Open Zed settings (Cmd+,) and add under context_servers:

{
  "context_servers": {
    "msgraph": {
      "command": {
        "path": "npx",
        "args": ["-y", "msgraph-mcp", "--client-id", "YOUR_CLIENT_ID", "--tenant-id", "YOUR_TENANT_ID"]
      }
    }
  }
}

---

Hermes Agent (Nous Research)

Config file: ~/.hermes/config.yaml

mcp_servers:
  msgraph:
    command: "npx"
    args:
      - "-y"
      - "msgraph-mcp"
      - "--client-id"
      - "YOUR_CLIENT_ID"
      - "--tenant-id"
      - "YOUR_TENANT_ID"

---

OpenClaw

Add to your OpenClaw gateway MCP config:

{
  "mcpServers": {
    "msgraph": {
      "command": "npx",
      "args": ["-y", "msgraph-mcp"],
      "env": {
        "MS_GRAPH_CLIENT_ID": "YOUR_CLIENT_ID",
        "MS_GRAPH_TENANT_ID": "YOUR_TENANT_ID"
      }
    }
  }
}

Then restart the gateway: openclaw gateway restart

---

Publishing to npm

cd msgraph-mcp
npm install
# update package.json with your name and repo URL
npm login
npm publish

---

License

MIT