Microsoft 365

SKILL.md

---
name: microsoft-365
description: Comprehensive Microsoft 365 (Office 365) integration for email, calendar, files, tasks, and contacts.
metadata:
  openclaw:
    requires:
      bins: ["npm", "node", "python3"]
      packages: ["@softeria/ms-365-mcp-server"]
---

# Microsoft 365

This skill provides a complete interface to Microsoft 365 services using the `ms-365-mcp-server` and a built-in Python CLI helper.

## Setup & Initialization

This skill requires the following tools to be available in the environment:
- **NPM Package:** `@softeria/ms-365-mcp-server` (install with `npm install -g @softeria/ms-365-mcp-server --prefix ~/lib/node`)
- **Python CLI:** `ms365_cli.py` (located in the `scripts/` directory of this skill)

Always ensure the npm bin path is on PATH before running:
```bash
export PATH="$HOME/lib/node/bin:$PATH"
```

---

## Authentication (Agent-Friendly — Two-Step Flow)

Microsoft 365 uses **Device Code Flow** for authentication. Because the login process blocks waiting for browser sign-in, agents **must use the two-step flow** below to avoid timeout issues.

### Step 1 — Get the device code (non-blocking)

```bash
export PATH="$HOME/lib/node/bin:$PATH"
cd ~/skills/user/microsoft-365
python3 scripts/ms365_cli.py get-code
```

This prints the device code and URL, then exits immediately. A background login process is left running (PID saved to `/tmp/ms365_login.pid`).

**Show the user output like:**
```
To sign in, use a web browser to open the page https://login.microsoft.com/device
and enter the code XXXXXXXXX to authenticate.
```

### Step 2 — Poll until auth completes

Ask the user to sign in, then poll for completion:

```bash
export PATH="$HOME/lib/node/bin:$PATH"
cd ~/skills/user/microsoft-365
python3 scripts/ms365_cli.py poll-auth --timeout 120
```

Returns `{"success": true, ...}` once the user has signed in. Exits with error if it times out.

### Verify auth status

```bash
python3 scripts/ms365_cli.py status
```

Returns the logged-in user's name and email, or a clear "not authenticated" message.

---

## Token Expiry

Device code tokens typically last **60–90 days**. If you receive auth errors, re-run the two-step flow above. There is no automatic refresh — re-authentication is required when the token expires.

---

## Available Workflows

### Email Management (Outlook)

```bash
# List recent emails (default: 10)
python3 scripts/ms365_cli.py mail list --top 10

# Read a specific email
python3 scripts/ms365_cli.py mail read <MESSAGE_ID>

# Send an email
python3 scripts/ms365_cli.py mail send --to "to@example.com" --subject "Hello" --body "Message content"
```

### Calendar & Meetings

```bash
# View upcoming events
python3 scripts/ms365_cli.py calendar list --top 5

# Schedule a new meeting
python3 scripts/ms365_cli.py calendar create \
  --subject "Project Sync" \
  --start "2026-04-01T10:00:00" \
  --end "2026-04-01T11:00:00"
```

### OneDrive & Files

```bash
# List files in root (with optional limit)
python3 scripts/ms365_cli.py files list --top 5

# List files in a specific folder
python3 scripts/ms365_cli.py files list --path "FolderName"
```

### Microsoft To Do Tasks

```bash
# List all task lists
python3 scripts/ms365_cli.py tasks lists

# View tasks in a list
python3 scripts/ms365_cli.py tasks get <LIST_ID>

# Create a task
python3 scripts/ms365_cli.py tasks create <LIST_ID> --title "My task" --due "2026-04-15T09:00:00"
```

### Contacts

```bash
# Search contacts
python3 scripts/ms365_cli.py contacts search "SearchName"
```

---

## Advanced Usage

Run as a continuous MCP server for background synchronization:

```bash
npx -y @softeria/ms-365-mcp-server --http 3001 --org-mode
```