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:

1. Log you into Azure (device code flow)
2. Create an App Registration automatically
3. Configure API permissions (Files.ReadWrite.All, Sites.ReadWrite.All, User.Read)
4. Guide you through authorization
5. 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 \x3Citem-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 "\x3Cquery>" [top]  # Full-text search

Inspecting Items

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

Uploading / Downloading

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

Modifying / Deleting

./scripts/onedrive-files.sh rename \x3Cid-or-path> \x3Cnew-name>
./scripts/onedrive-files.sh move   \x3Csrc> \x3Cdest-folder>
./scripts/onedrive-files.sh copy   \x3Csrc> \x3Cdest-folder> [new-name]
./scripts/onedrive-files.sh delete \x3Cid-or-path>     # → recycle bin

Sharing

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

# Invite specific users
./scripts/onedrive-share.sh invite \x3Cpath-or-id> [email protected] read "Have a look!"
./scripts/onedrive-share.sh invite \x3Cpath-or-id> [email protected],[email protected] write "Please review"

# Permissions
./scripts/onedrive-share.sh permissions \x3Cpath-or-id>           # List
./scripts/onedrive-share.sh revoke      \x3Cpath-or-id> \x3Cperm-id>
./scripts/onedrive-share.sh update-role \x3Cpath-or-id> \x3Cperm-id> \x3Cnew-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": "[email protected]",
  "mail": "[email protected]",
  "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/\x3Cdrive-id>"          # Specific drive by ID
export ONEDRIVE_DRIVE_PREFIX="/sites/\x3Csite-id>/drive"      # SharePoint site default doc library
export ONEDRIVE_DRIVE_PREFIX="/users/\x3Cuser-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 \x3C\x3CEOF
{"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 \x3Cid> 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