onedrive-blade-mcp

A token-efficient MCP server for OneDrive and SharePoint file operations via Microsoft Graph API.

18 tools covering browse, read, search, upload, share, versioning, delta sync, and SharePoint — with pipe-delimited output, write-gating, and dual auth.

Why this over generic file MCPs?

	onedrive-blade-mcp	Generic file / Graph MCPs
Output	Pipe-delimited, null omission	Raw JSON blobs (10-50x more tokens)
Delta sync	drive_delta tracks file changes incrementally	Full re-listing every time
SharePoint	Browse sites, libraries, and files natively	OneDrive-only or not supported
Safety	Write-gated by default, delete requires confirm=true	Varies
Auth	Dual: device code (interactive) + client credentials (headless/CI)	Single flow
Versioning	drive_versions for full file history	Not exposed
Thumbnails	drive_thumbnail for image previews	Not available

Delta sync is the killer feature for AI workflows — track what changed in a folder without re-listing thousands of files.

Features

• 18 tools — browse, read, search, upload, share, version history, delta sync, SharePoint
• Token-efficient output — pipe-delimited, field-selected, null fields omitted
• Write-gated by default — reads are free, writes require ONEDRIVE_WRITE_ENABLED=true
• Delta sync — incremental file change tracking with delta tokens
• SharePoint integration — sites, document libraries, and files
• Dual authentication — device code for interactive, client credentials for headless
• Sharing management — create links, check permissions, control scope
• FastMCP 2.0 — stdio and HTTP transports

Quick Start

# Install
git clone https://github.com/groupthink-dev/onedrive-blade-mcp.git
cd onedrive-blade-mcp
uv sync

# Configure
export ONEDRIVE_TENANT_ID="your-tenant-id"
export ONEDRIVE_CLIENT_ID="your-client-id"
export ONEDRIVE_AUTH_MODE="device_code"

# Run (stdio)
uv run onedrive-blade-mcp

Tools (18)

Meta

Tool	Description
drive_info	Storage info — drive type, quota usage, owner

Read (8)

Tool	Description
drive_list	Browse folder contents (path or ID)
drive_read	Read file content — text for text files, base64 summary for binary
drive_metadata	Detailed metadata — name, size, dates, creator, MIME, sharing
drive_search	Search files by name or content (Microsoft Search)
drive_download	Pre-authenticated short-lived download URL
drive_versions	Version history with dates, authors, sizes
drive_delta	Incremental change tracking with delta tokens
drive_thumbnail	Thumbnail URLs (small/medium/large) for images and documents

SharePoint (3)

Tool	Description
drive_sites	List or search SharePoint sites
drive_site_libraries	Document libraries for a SharePoint site
drive_site_list	Files in a SharePoint document library

Write (4, gated)

Tool	Description
drive_upload	Upload a file (up to 4MB, base64 content)
drive_create_folder	Create a new folder
drive_move	Move and/or rename a file or folder
drive_delete	Delete to recycle bin (requires confirm=true)

Sharing (2)

Tool	Description
drive_share	Create sharing links (view/edit/embed, org/anonymous scope)
drive_permissions	View who has access and existing sharing links

Delta Sync

Track file changes without re-listing entire directories:

# First call — returns current state + delta_link
drive_delta(folder_path="/Documents")

# Subsequent calls — returns only changes since last call
drive_delta(delta_link="aHR0cHM6Ly9ncmFwaC5taW...")

Returns created, modified, and deleted items with a fresh delta_link for the next call.

Authentication

Device Code (interactive)

export ONEDRIVE_AUTH_MODE="device_code"
export ONEDRIVE_TENANT_ID="your-tenant-id"
export ONEDRIVE_CLIENT_ID="your-client-id"

Client Credentials (headless)

export ONEDRIVE_AUTH_MODE="client_credentials"
export ONEDRIVE_TENANT_ID="your-tenant-id"
export ONEDRIVE_CLIENT_ID="your-client-id"
export ONEDRIVE_CLIENT_SECRET="your-client-secret"

Security Model

Layer	Behaviour
Write gate	All mutations disabled by default (ONEDRIVE_WRITE_ENABLED=true)
Delete safety	drive_delete requires confirm=true (moves to recycle bin)
Credential scrubbing	Tokens never appear in tool output or error messages
Bearer auth	Optional ONEDRIVE_MCP_API_TOKEN for HTTP transport

Claude Desktop Config

{
  "mcpServers": {
    "onedrive": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/onedrive-blade-mcp", "onedrive-blade-mcp"],
      "env": {
        "ONEDRIVE_TENANT_ID": "your-tenant-id",
        "ONEDRIVE_CLIENT_ID": "your-client-id",
        "ONEDRIVE_AUTH_MODE": "device_code"
      }
    }
  }
}

Claude Code

claude mcp add onedrive -- uv run --directory /path/to/onedrive-blade-mcp onedrive-blade-mcp

Environment Variables

Variable	Required	Default	Description
ONEDRIVE_TENANT_ID	Yes	—	Azure AD tenant ID
ONEDRIVE_CLIENT_ID	Yes	—	App registration client ID
ONEDRIVE_CLIENT_SECRET	For client_credentials	—	App registration client secret
ONEDRIVE_AUTH_MODE	No	device_code	device_code or client_credentials
ONEDRIVE_WRITE_ENABLED	No	false	Enable write/delete tools
ONEDRIVE_MCP_TRANSPORT	No	stdio	stdio or http
ONEDRIVE_MCP_HOST	No	127.0.0.1	HTTP bind address
ONEDRIVE_MCP_PORT	No	8002	HTTP port
ONEDRIVE_MCP_API_TOKEN	No	—	Bearer token for HTTP auth

Architecture

src/onedrive_blade_mcp/
├── server.py       — FastMCP 2.0 server, 18 @mcp.tool decorators
├── client.py       — Graph API client with dual auth, write gate, delta sync
├── formatters.py   — Token-efficient output (pipe-delimited, null omission)
├── models.py       — Config, constants
└── auth.py         — Device code + client credentials, bearer middleware

Built with FastMCP 2.0 and httpx.

Development

uv sync               # Install dependencies
uv run onedrive-blade-mcp   # Run locally (stdio)
uv run ruff check .    # Lint
uv run pytest tests/   # Tests (mocked, no OneDrive needed)

License

MIT