OneDrive Read-Only MCP Server

A local Model Context Protocol (MCP) server for searching, inspecting, and downloading files from a personal Microsoft OneDrive account. Install the published package with npx; no repository checkout or separate Python installation is needed. The launcher uses Astral uv to install and run the matching Python package in an isolated environment.

This project targets personal Microsoft accounts and consumer OneDrive. OneDrive for Business and SharePoint are outside its default scope. Linux is the supported production platform; Windows and other non-POSIX systems are for development only because POSIX file modes do not establish Windows ACLs.

Install and connect

Requirements

• Node.js 18 or newer, which provides npx.
• Astral uv, which provides uvx. It creates an isolated Python environment and can provision a compatible Python interpreter; you do not need to install the server's Python dependencies yourself.
• A personal Microsoft account and a Microsoft Entra app registration that you own or are authorized to use.

1. Register your Microsoft application

Follow the app registration guide. You will use its public Application (client) ID below. Each user supplies their own ID; this project does not ship a shared client ID or client secret.

2. Save your client ID and sign in

The following commands are for Linux/macOS shells. They create a private per-user configuration directory and .env file; replace the placeholder with your app registration's client ID:

CONFIG_DIR="${ONEDRIVE_MCP_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/onedrive-mcp}"
install -d -m 700 "$CONFIG_DIR"
if [ ! -e "$CONFIG_DIR/.env" ]; then
  (umask 077; printf 'AZURE_CLIENT_ID=%s\nAZURE_TENANT_ID=consumers\n' 'YOUR-APPLICATION-CLIENT-ID' > "$CONFIG_DIR/.env")
else
  echo "Keep the existing $CONFIG_DIR/.env; verify AZURE_CLIENT_ID is set there."
fi
npx --yes --package @joescars/onedrive-mcp@0.1.1 onedrive-mcp-setup

These commands target 0.1.1; wait until the matching npm and PyPI releases are published before installing that version.

The setup command displays Microsoft's device-code sign-in instructions and stores the token cache in the stable per-user data directory. You normally sign in once; repeat only if your credentials expire or are revoked. See Setup for app registration, path overrides, and migration from a source install.

3. Add the server to your MCP client

Use the following stdio configuration in clients that support an mcpServers object:

{
  "mcpServers": {
    "onedrive": {
      "command": "npx",
      "args": ["--yes", "@joescars/onedrive-mcp@0.1.1"]
    }
  }
}

Pinning the package version makes upgrades intentional. The MCP client starts the server when needed; do not run a separate server process. If the client cannot find npx on its PATH, use the absolute path to npx. Keep client IDs, .env contents, and tokens out of client configuration. For client- specific examples, see Client configuration; the npm launcher has its own installation guide.

What it can do

The server provides these five MCP tools:

Paths such as /Documents/report.pdf and Graph item IDs are accepted where documented. Pagination continuations are opaque; pass them back to the same tool with the original arguments. The server returns a local path and metadata for downloads, not the downloaded file's contents. See the Tool reference for exact arguments and results.

Storage and security

• Microsoft Graph requests use read-only delegated scopes and a GET-only network helper. This is not a guarantee against future code changes.
• .env configuration, the token cache, and downloads live outside the npm cache and source checkout in stable per-user directories.
• The token cache contains sensitive credentials. On Linux, files are restricted with owner-only POSIX permissions; the cache is not encrypted.
• Signed download URLs are not returned in tool results or errors. Downloads have configurable per-file and total-directory limits, and existing files are never overwritten.
• Search results, file names, paths, and metadata become available to the MCP client and may enter the model's context. Only connect accounts and files you intend to make available.

Read the full Security guide, and never share token_cache.bin or the contents of your .env file.

Other installation and deployment options

• Python/source installation: follow Setup. Useful for development or when you prefer managing the checkout yourself.
• Open WebUI: this server uses stdio; expose it through the authenticated mcpo bridge rather than pointing Open WebUI directly at the stdio process.

Documentation

License

MIT licensed; see LICENSE. This is an independent community project and is not affiliated with or endorsed by Microsoft.