Onedrive

Data & APIs

Read, manage, share, upload, and download OneDrive files via Microsoft Graph API. Use when the user asks about OneDrive, OneDrive for Business, SharePoint document libraries, file sharing, or cloud storage on Microsoft.

Install

openclaw skills install trendex-onedrive

OneDrive Skill

Access OneDrive (personal + business) and SharePoint document libraries via Microsoft Graph using OAuth2.

Quick Setup (Automated)

# Requires: Azure CLI, jq
./scripts/onedrive-setup.sh

The setup script will:

Log you into Azure (device code flow)
Create an App Registration automatically
Configure API permissions (Files.ReadWrite.All, Sites.ReadWrite.All, User.Read)
Guide you through authorization
Save credentials to ~/.onedrive-mcp/

Manual Setup

See references/setup.md for step-by-step manual configuration via Azure Portal.

Bootstrap (Headless / Pre-Provisioned Tokens)

If the deployment system already has client_id, client_secret, access_token, and refresh_token, run the templated bootstrap script (substituting the __PLACEHOLDERS__):

bash scripts/onedrive-bootstrap.sh

It installs jq + curl if missing, writes ~/.onedrive-mcp/{config,credentials}.json, refreshes the token, and probes /me/drive to confirm. No browser, no Azure CLI.

Usage

Token Management

./scripts/onedrive-token.sh refresh  # Refresh expired token
./scripts/onedrive-token.sh test     # Test connection
./scripts/onedrive-token.sh get      # Print access token
./scripts/onedrive-token.sh info     # Show token info / expiry
./scripts/onedrive-token.sh me       # Show signed-in user

Browsing Files

./scripts/onedrive-files.sh list                    # List root folder
./scripts/onedrive-files.sh list "Documents"        # List a folder by path
./scripts/onedrive-files.sh list-id <item-id>       # List by item ID
./scripts/onedrive-files.sh list-special documents  # documents|photos|cameraroll|approot|music
./scripts/onedrive-files.sh tree [path] [depth=3]   # Recursive tree
./scripts/onedrive-files.sh recent [count]          # Recently used files
./scripts/onedrive-files.sh shared [count]          # Items shared with me
./scripts/onedrive-files.sh search "<query>" [top]  # Full-text search

Inspecting Items

./scripts/onedrive-files.sh info <path-or-id>       # Full metadata
./scripts/onedrive-files.sh stat <path-or-id>       # Size, mime, modified
./scripts/onedrive-files.sh url <path-or-id>        # Pre-auth download URL
./scripts/onedrive-files.sh thumbnail <id> [size]   # small | medium | large
./scripts/onedrive-files.sh preview <id>            # Embeddable preview URL
./scripts/onedrive-files.sh versions <id>           # Version history
./scripts/onedrive-files.sh owner <path-or-id>      # Creator / last modifier

Uploading / Downloading

./scripts/onedrive-files.sh mkdir <path>            # Create folder (parents auto-created)
./scripts/onedrive-files.sh upload <local> <remote> # Auto: simple (≤4MB) or resumable
./scripts/onedrive-files.sh upload-stream <remote>  # Pipe stdin to remote
./scripts/onedrive-files.sh download <remote> [local]
./scripts/onedrive-files.sh cat <path>              # Print text file to stdout

Modifying / Deleting

./scripts/onedrive-files.sh rename <id-or-path> <new-name>
./scripts/onedrive-files.sh move   <src> <dest-folder>
./scripts/onedrive-files.sh copy   <src> <dest-folder> [new-name]
./scripts/onedrive-files.sh delete <id-or-path>     # → recycle bin

Sharing

# Anonymous / org-scoped links
./scripts/onedrive-share.sh link <path-or-id> view  anonymous
./scripts/onedrive-share.sh link <path-or-id> edit  anonymous
./scripts/onedrive-share.sh link <path-or-id> view  organization
./scripts/onedrive-share.sh link <path-or-id> embed anonymous
./scripts/onedrive-share.sh link <path-or-id> view  anonymous --password "secret" --expiry 2026-12-31

# Invite specific users
./scripts/onedrive-share.sh invite <path-or-id> alice@example.com read "Have a look!"
./scripts/onedrive-share.sh invite <path-or-id> alice@x.com,bob@y.com write "Please review"

# Permissions
./scripts/onedrive-share.sh permissions <path-or-id>           # List
./scripts/onedrive-share.sh revoke      <path-or-id> <perm-id>
./scripts/onedrive-share.sh update-role <path-or-id> <perm-id> <new-role>

# Resolve a 1drv.ms / SharePoint share URL
./scripts/onedrive-share.sh open "https://1drv.ms/u/s!..."

Drives & Quota

./scripts/onedrive-files.sh drives           # List drives the user can access
./scripts/onedrive-files.sh drive [drive-id] # Drive metadata (default: yours)
./scripts/onedrive-files.sh quota            # total / used / remaining
./scripts/onedrive-files.sh delta [token]    # Change feed (initial or incremental)

Example Output

$ ./scripts/onedrive-files.sh list

{
  "kind": "dir",
  "name": "Documents",
  "size": 5242880,
  "modified": "2026-05-15T10:24:31Z",
  "id": "01ABCDEF1234ZZZ",
  "mime": null,
  "children": 12
}
{
  "kind": "file",
  "name": "Budget-Q2.xlsx",
  "size": 184320,
  "modified": "2026-05-18T16:02:11Z",
  "id": "01ABCDEF5678YYY",
  "mime": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
}

$ ./scripts/onedrive-files.sh quota

{
  "state": "normal",
  "total": 1099511627776,
  "used": 482918400,
  "remaining": 1099028709376,
  "deleted": 0
}

$ ./scripts/onedrive-share.sh link "Reports/q1.xlsx" view organization

{
  "id": "aTo...",
  "type": "view",
  "scope": "organization",
  "webUrl": "https://contoso-my.sharepoint.com/:x:/p/...",
  "expirationDateTime": null,
  "hasPassword": false
}

$ ./scripts/onedrive-token.sh me

{
  "id": "9b8...-...-...",
  "displayName": "Jane Doe",
  "userPrincipalName": "jane@contoso.onmicrosoft.com",
  "mail": "jane@contoso.com",
  "givenName": "Jane",
  "surname": "Doe",
  "jobTitle": "Engineer"
}

Token Refresh

Access tokens expire after ~1 hour. Refresh with:

./scripts/onedrive-token.sh refresh

This requires a valid refresh_token in the credentials file (kept ~90 days for personal accounts).

Files

~/.onedrive-mcp/config.json — Client ID, secret, tenant, scopes
~/.onedrive-mcp/credentials.json — OAuth tokens (access + refresh)

Both files are chmod 600, directory 700. Never commit them.

Permissions

Delegated scopes used by default:

Files.ReadWrite.All — Read/write all files the user can access
Sites.ReadWrite.All — SharePoint / OneDrive for Business document libraries
User.Read — Basic profile (needed for sign-in)
offline_access — Refresh tokens (stay logged in)

See references/permissions.md for the full scope catalog (delegated + application/daemon flows).

Targeting Other Drives

By default, all commands target /me/drive (the signed-in user's drive). To target a different drive, set:

export ONEDRIVE_DRIVE_PREFIX="/drives/<drive-id>"          # Specific drive by ID
export ONEDRIVE_DRIVE_PREFIX="/sites/<site-id>/drive"      # SharePoint site default doc library
export ONEDRIVE_DRIVE_PREFIX="/users/<user-id>/drive"      # Another user (requires Files.Read.All)

Discover drive IDs with ./scripts/onedrive-files.sh drives.

Bring Your Own Access Token

If you already have a Microsoft Graph access token (from another app / Postman / MSAL / etc.), three options:

# A) Env var (one-shot)
export ONEDRIVE_ACCESS_TOKEN="eyJ0..."
./scripts/onedrive-files.sh list

# B) Helper (persists to ~/.onedrive-mcp/credentials.json)
./scripts/onedrive-token.sh set "eyJ0..." "refresh-token"

# C) Drop the JSON file directly
mkdir -p ~/.onedrive-mcp && chmod 700 ~/.onedrive-mcp
cat > ~/.onedrive-mcp/credentials.json <<EOF
{"token_type":"Bearer","access_token":"eyJ0...","refresh_token":"..."}
EOF
chmod 600 ~/.onedrive-mcp/credentials.json

Notes

Item IDs: stable per drive. The id field is the full Graph ID — pass it as-is.
Path addressing: use / separators (Documents/Reports/q4.xlsx). Scripts handle URL-encoding.
Conflict behavior: uploads default to replace. Use the API directly for rename / fail.
Large uploads: files > 4 MiB automatically use a resumable upload session (10 MiB chunks).
Download URLs: @microsoft.graph.downloadUrl returned by the API is pre-authenticated and short-lived (minutes).
Deletes move to the recycle bin (recoverable via the web UI for 30 days personal / 93 days business).
Throttling: respect the Retry-After header on 429.

Troubleshooting

"Token expired" → ./scripts/onedrive-token.sh refresh

"Invalid grant" → Refresh token revoked or expired; re-run onedrive-setup.sh (or have the deployment system re-bootstrap).

"accessDenied" → Token's scopes don't cover the operation. Check onedrive-token.sh info and reconsent with the right scopes.

"itemNotFound" on a visible path → URL-encode special chars. Try info <id> to confirm the ID-based path works.

SharePoint drive returns 404 for /me/drive → Use /sites/{site-id}/drive or list /me/drives first.

Resumable upload stalls → The uploadUrl expired (~1h). Restart the session via upload (the script re-creates it automatically).

Supported Accounts

Personal Microsoft accounts (outlook.com, hotmail.com, live.com)
Work / school accounts (Microsoft 365) — may require admin consent for *.All scopes
SharePoint document libraries via Sites.ReadWrite.All

Resources

Microsoft Graph OneDrive overview
DriveItem resource
Large file upload (resumable)
Sharing concepts
references/api-reference.md — full endpoint catalog
references/permissions.md — OAuth scopes (delegated + application)
references/setup.md — manual Azure Portal walkthrough

Changelog

v1.0.0

Initial release
Direct Microsoft Graph integration (no third-party proxy)
Three install paths: automated (Azure CLI), manual (portal), or headless bootstrap (pre-provisioned tokens)
File/folder CRUD, sharing, permissions, search, recent, shared-with-me, versions, thumbnails, preview, delta
BYO-token support via ONEDRIVE_ACCESS_TOKEN or onedrive-token.sh set
Multi-drive targeting via ONEDRIVE_DRIVE_PREFIX