npm package: @insightsentry/ms-mcp
Description: MCP server for Microsoft Outlook, To Do, and Calendar via Graph API - provides AI-accessible tools for email, task management, and calendar events
Latest version: 2.0.5

# @insightsentry/ms-mcp

MCP (Model Context Protocol) server for Microsoft Outlook, To Do, Calendar, and OneDrive via the Microsoft Graph API.

Gives AI assistants direct access to your Microsoft account — read, search, send, and draft emails, manage To Do tasks, manage calendar events, and browse/manage OneDrive files. Uses OAuth2 delegated auth with interactive browser login (or device-code flow for headless environments).

## Setup

### Prerequisites

You need a Microsoft Entra (Azure AD) app registration with **delegated permissions** (not application permissions):

- `Mail.ReadWrite`
- `Mail.Send`
- `Tasks.ReadWrite`
- `Calendars.ReadWrite`
- `Files.ReadWrite`
- `Notes.ReadWrite`
- `User.Read`

The app registration must be configured as a **public client** (allow public client flows) since this uses `PublicClientApplication` — no client secret is needed.

Gather these values from your app registration:

| Variable | Description |
|----------|-------------|
| `MS_MCP_CLIENT_ID` | Application (client) ID |
| `MS_MCP_TENANT_ID` | Directory (tenant) ID |

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "microsoft": {
      "command": "npx",
      "args": ["@insightsentry/ms-mcp"],
      "env": {
        "MS_MCP_CLIENT_ID": "your-client-id",
        "MS_MCP_TENANT_ID": "your-tenant-id"
      }
    }
  }
}
```

### Claude Code

Add to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "microsoft": {
      "command": "npx",
      "args": ["@insightsentry/ms-mcp"],
      "env": {
        "MS_MCP_CLIENT_ID": "your-client-id",
        "MS_MCP_TENANT_ID": "your-tenant-id"
      }
    }
  }
}
```

## Authentication

On first use, call the `microsoft_login` tool (or run `npx @insightsentry/ms-mcp-login` from the terminal). This opens your browser for interactive OAuth sign-in. On headless/SSH environments, it falls back to device-code flow automatically.

For device-code flow explicitly:

```bash
npx @insightsentry/ms-mcp-login --device-code
```

Tokens are cached to `~/.ms-mcp/msal-cache.json` and silently refreshed via the refresh token on subsequent runs.

## Available Tools (29)

### Auth
| Tool | Description |
|------|-------------|
| `microsoft_login` | Sign in to Microsoft account via browser OAuth |
| `microsoft_login_status` | Check if currently signed in |

### Raw API
| Tool | Description |
|------|-------------|
| `graph_api` | Call any Microsoft Graph API endpoint directly |

### Email
| Tool | Description |
|------|-------------|
| `search_emails` | Search emails across all folders using KQL syntax |
| `list_emails` | List emails with pagination, filtering, and search |
| `read_email` | Read full email content by ID |
| `create_draft` | Create a draft email |
| `send_email` | Send a new email directly |
| `reply_email` | Reply or reply-all to an email |

### To Do
| Tool | Description |
|------|-------------|
| `search_tasks` | Search tasks across all lists by keyword |
| `list_task_lists` | List all To Do task lists |
| `list_tasks` | List tasks in a task list with filtering |
| `create_task` | Create a task with title, body, due date, importance |
| `update_task` | Update task title, body, due date, importance, or status |
| `delete_task` | Delete a task |

### Calendar
| Tool | Description |
|------|-------------|
| `search_events` | Search calendar events using KQL syntax |
| `list_events` | List upcoming calendar events in a time range |
| `get_event` | Get full details of a calendar event |
| `create_event` | Create an event with attendees, location, Teams meeting |
| `update_event` | Update event details |
| `delete_event` | Delete a calendar event |

### OneDrive
| Tool | Description |
|------|-------------|
| `list_drive_items` | List files and folders (root or by path/ID) |
| `search_drive` | Search files and folders by name or content |
| `get_drive_item` | Get file/folder metadata by ID or path |
| `create_drive_folder` | Create a new folder |
| `move_drive_item` | Move or rename a file/folder |
| `copy_drive_item` | Copy a file/folder to a new location |
| `delete_drive_item` | Delete a file/folder (moves to recycle bin) |
| `share_drive_item` | Create a sharing link for a file/folder |

## JSONata Transforms

Most read tools accept an optional `transform` parameter — a JSONata expression applied to the response before returning. This lets AI assistants extract exactly the fields they need without processing the full response.

## Development

```bash
npm install
npm run build     # Compile TypeScript
npm run dev       # Run with tsx (no build needed)
npm run login     # Interactive login
```

## License

MIT