Onedrive

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.

OneDrive Skill

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

Quick Setup (Automated)

bash

# 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

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

bash

./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

bash

./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

bash

./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

bash

./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

bash

./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

bash

# 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> [e-mail] read "Have a look!"
./scripts/onedrive-share.sh invite <path-or-id> [e-mail],[e-mail] 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

bash

./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

bash

$ ./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": "[e-mail]",
  "mail": "[e-mail]",
  "givenName": "Jane",
  "surname": "Doe",
  "jobTitle": "Engineer"
}

Token Refresh

Access tokens expire after ~1 hour. Refresh with:

bash

./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:

bash

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:

bash

# 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