# MSGraph MCP server

> Allows AI agents to manage Outlook mail and calendar events and read Microsoft Teams message history using Microsoft Graph.

- Repository: https://github.com/timfurlong/msgraph-mcp
- Page: https://hostedmcp.org/servers/timfurlong/msgraph-mcp
- Transport: stdio
- Stars: 1
- License: MIT
- Latest version: 0.5.2

## Install

### Claude Code

```sh
claude mcp add --env 'MSGRAPH_MCP_CLIENT_ID=<MSGRAPH_MCP_CLIENT_ID>' --env 'MSGRAPH_MCP_TENANT_ID=<MSGRAPH_MCP_TENANT_ID>' msgraph-mcp -- uvx msgraph-mcp-server
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "msgraph-mcp": {
      "command": "uvx",
      "args": [
        "msgraph-mcp-server"
      ],
      "env": {
        "MSGRAPH_MCP_CLIENT_ID": "<MSGRAPH_MCP_CLIENT_ID>",
        "MSGRAPH_MCP_TENANT_ID": "<MSGRAPH_MCP_TENANT_ID>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "msgraph-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "msgraph-mcp-server"
      ],
      "env": {
        "MSGRAPH_MCP_CLIENT_ID": "<MSGRAPH_MCP_CLIENT_ID>",
        "MSGRAPH_MCP_TENANT_ID": "<MSGRAPH_MCP_TENANT_ID>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"msgraph-mcp","type":"stdio","command":"uvx","args":["msgraph-mcp-server"],"env":{"MSGRAPH_MCP_CLIENT_ID":"<MSGRAPH_MCP_CLIENT_ID>","MSGRAPH_MCP_TENANT_ID":"<MSGRAPH_MCP_TENANT_ID>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "msgraph-mcp": {
      "command": "uvx",
      "args": [
        "msgraph-mcp-server"
      ],
      "env": {
        "MSGRAPH_MCP_CLIENT_ID": "<MSGRAPH_MCP_CLIENT_ID>",
        "MSGRAPH_MCP_TENANT_ID": "<MSGRAPH_MCP_TENANT_ID>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add msgraph-mcp --env 'MSGRAPH_MCP_CLIENT_ID=<MSGRAPH_MCP_CLIENT_ID>' --env 'MSGRAPH_MCP_TENANT_ID=<MSGRAPH_MCP_TENANT_ID>' -- uvx msgraph-mcp-server
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.msgraph-mcp]
command = "uvx"
args = ["msgraph-mcp-server"]

[mcp_servers.msgraph-mcp.env]
MSGRAPH_MCP_CLIENT_ID = "<MSGRAPH_MCP_CLIENT_ID>"
MSGRAPH_MCP_TENANT_ID = "<MSGRAPH_MCP_TENANT_ID>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'MSGRAPH_MCP_CLIENT_ID=<MSGRAPH_MCP_CLIENT_ID>' -e 'MSGRAPH_MCP_TENANT_ID=<MSGRAPH_MCP_TENANT_ID>' msgraph-mcp uvx -- msgraph-mcp-server
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "msgraph-mcp": {
      "command": "uvx",
      "args": [
        "msgraph-mcp-server"
      ],
      "env": {
        "MSGRAPH_MCP_CLIENT_ID": "<MSGRAPH_MCP_CLIENT_ID>",
        "MSGRAPH_MCP_TENANT_ID": "<MSGRAPH_MCP_TENANT_ID>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `MSGRAPH_MCP_CLIENT_ID` | yes | no | Client ID of your Entra (Azure AD) app registration |
| `MSGRAPH_MCP_TENANT_ID` | yes | no | Entra tenant ID (or 'common' / 'organizations' / 'consumers') |
| `MSGRAPH_MCP_TOKEN_CACHE_PATH` | no | no | Override the token cache location (default ~/.msgraph-mcp/token_cache.bin) |

## FAQ

### What can the server access in Microsoft Teams?

The server provides read-only access to Microsoft Teams message history, including chats, channels, and message replies.

### How do I sign in to the MSGraph MCP server?

You sign in once using the `msgraph-mcp-login` command, which uses the MSAL device code flow to print a URL and a code for you to visit.

### Can the server manage shared mailboxes?

Yes, mail and calendar tools accept an optional mailbox parameter to target shared or delegated mailboxes.

### What happens if I add new permissions to my Entra app later?

You must re-run the login command because sign-in requests all scopes at once; otherwise, tools requiring the new scope will fail.