OneDrive Read-Only MCP Server

A local Model Context Protocol (MCP) server that lets AI agents search, inspect, and download files from a personal Microsoft OneDrive account.

Features

• Search OneDrive by file name or indexed content.
• Browse folders with secure, bounded pagination.
• Inspect file and folder metadata.
• Download files to a controlled local directory without overwriting existing files.
• Refresh cached Microsoft credentials without interactive sign-in.
• Connect directly to VS Code, Hermes, or pi over stdio, or to Open WebUI through an authenticated mcpo bridge.

This server targets personal Microsoft accounts and consumer OneDrive. OneDrive for Business and SharePoint are outside the project's default scope.

Requirements

• Linux is the supported production platform. Windows is suitable for development only because POSIX file modes do not establish Windows ACLs.
• Source installs require Python 3.11 or newer. The optional npm launcher requires Node.js 18+ and Astral uv (which can provision Python).
• A personal Microsoft account and a Microsoft Entra app registration configured for device-code authentication; see the registration prerequisites.

Quick start

For complete Azure and authentication instructions, see Setup.

git clone https://github.com/joescars/onedrive-mcp.git
cd onedrive-mcp
python3 -m venv venv
./venv/bin/pip install --require-hashes -r requirements.lock
export ONEDRIVE_MCP_CONFIG_DIR="${ONEDRIVE_MCP_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/onedrive-mcp}"
CONFIG_DIR="$ONEDRIVE_MCP_CONFIG_DIR"
install -d -m 700 "$CONFIG_DIR"
cp .env.example "$CONFIG_DIR/.env"

Set AZURE_CLIENT_ID in "$CONFIG_DIR/.env", restrict the file, and sign in:

chmod 600 "$CONFIG_DIR/.env"
./venv/bin/python scripts/setup_auth.py
./venv/bin/python scripts/smoke_test.py

The token cache and downloads default to the stable per-user data directory ($XDG_DATA_HOME/onedrive-mcp or ~/.local/share/onedrive-mcp), not the checkout or package install directory. The smoke test reads drive information and lists the root folder. It does not download or modify files.

Connect a client

Complete the quick start before configuring a client. The MCP host starts this server when needed; do not leave a separate standalone process running.

Example VS Code workspace configuration:

{
  "servers": {
    "onedrive": {
      "type": "stdio",
      "command": "${workspaceFolder}/venv/bin/python",
      "args": ["${workspaceFolder}/server.py"]
    }
  }
}

Use absolute paths for user-level or remote-user configuration. No tokens or .env values belong in client configuration.

Tools

Paths such as /Documents/report.pdf and raw Graph item IDs are accepted where path_or_id is documented. Pagination continuations are opaque and must be passed back to the same tool with the original arguments.

See the Tool reference for complete inputs, outputs, and pagination behavior.

Example prompts:

• Use OneDrive to list /Documents without downloading anything.
• Search OneDrive for "invoice" and tell me if more pages are available.
• Get metadata for /Documents/report.pdf without downloading it.
• Download /Documents/report.pdf as report-copy.pdf.

Downloads remain on the machine running the server. The tool returns a local path and metadata, not the file's contents.

Security and privacy

• Microsoft Graph operations use the GET-only helper in graph_client.py and read-only delegated scopes; this is not a guarantee against future code changes.
• The token cache and downloads are stored with owner-only POSIX permissions.
• Signed Graph download URLs are never returned in tool results or errors.
• Downloads have configurable per-file and directory-wide limits.
• Existing files are never overwritten.
• The optional HTTP bridge requires an API key and defaults to loopback.

Read-only access is still sensitive: names, paths, metadata, and quota details returned by tools enter the MCP client's context. Use only accounts and files you intend to make available, and never share token_cache.bin.

See Security for the trust model, safeguards, and operational limitations.

Documentation

Development

Run the credential-free test suite:

./venv/bin/python -m pytest -v

Tests mock Microsoft Graph and MSAL traffic; they do not access a real OneDrive account. See Development for maintenance and contribution details.

License

This project is licensed under the MIT License. It is an independent community project and is not affiliated with or endorsed by Microsoft.