Skip to main content
Glama
OneDrive Read-Only MCP Server

OneDrive Read-Only MCP Server

by joescars

OneDrive Read-Only MCP Server

Tests and dependency audit PyPI npm

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.

IMPORTANT

This server is read-only. It exposes five read-style tools and only makes HTTP GET requests to Microsoft Graph. It can download files from OneDrive to the local machine, but cannot upload, edit, rename, move, or delete OneDrive content.

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@latest onedrive-mcp-setup

The setup command follows npm's latest tag. The MCP client example below pins the running server to 0.1.2 so upgrades are intentional.

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.2"]
    }
  }
}

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.

Related MCP server: mcp-onedrive

What it can do

The server provides these five MCP tools:

Tool

Purpose

search_onedrive(query, top=20, next_link=None)

Search by file name or indexed content, one page at a time.

list_folder(path='/', top=50, next_link=None)

List a folder's children with bounded pagination.

get_item_metadata(path_or_id)

Inspect metadata for a file or folder.

download_file(path_or_id, dest_filename=None)

Download a file into the local download directory without overwriting an existing file.

get_drive_info()

Read drive, owner, and quota information.

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.

Configuration preflight and troubleshooting

Before starting the MCP transport, the Python server validates local settings for malformed Azure IDs, unsupported tenant names, path conflicts, filesystem inspection failures, and non-positive byte limits. Config/data directory overrides must be absolute; relative cache/download paths remain supported as described in Setup. The server still permits a credential-free startup so MCP clients can discover its tools, but it refuses to proceed with a broken runtime configuration before any Graph request or token-cache write occurs.

If startup fails, the error is sent to stderr and the process exits without leaking config values or tokens to MCP stdout. For more detail, see Setup and Troubleshooting.

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

Guide

What it covers

Setup

Microsoft app registration, source installation, configuration, and sign-in.

Client configuration

VS Code, Hermes, pi, stdio, and Open WebUI setup.

npm installation

Published launcher requirements, sign-in, and client configuration.

Tool reference

Tool inputs, response shapes, pagination, and downloads.

Security

Read-only design, local storage, and privacy considerations.

Development

Tests, dependency maintenance, and publishing releases.

Troubleshooting

Authentication, Graph, client, and dependency issues.

License

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

Available Tools

5 tools
download_fileA

Download a OneDrive file's content to local disk (read-only — the source file in OneDrive is never modified).

Args: path_or_id: Human path (e.g. '/Documents/foo.pdf') or Graph item id of the FILE to download. dest_filename: Optional bare local filename to save as (defaults to the OneDrive file's own name). Saved under DOWNLOAD_DIR. Must be a plain file name (no path separators) and must not already exist — an existing destination raises an error instead of being silently overwritten.

Returns {local_path, size_bytes, mime_type, source_name}. The file is always saved to disk (owner-only permissions); base64 content is not returned to keep responses small and to safely handle large files.

Inputs: path_or_id (required), dest_filename.

get_drive_infoA

Get basic OneDrive info (quota, owner, drive id) — useful as a smoke test that authentication is working.

Returns {drive_id, drive_type, owner_name, quota_used, quota_total, quota_remaining, web_url}.

Inputs: no named parameters.

get_item_metadataA

Get full metadata for a single OneDrive file or folder.

Args: path_or_id: Either a human path (e.g. '/Documents/foo.pdf') or a raw Graph drive item id.

Returns {name, id, path, size, last_modified, is_folder, web_url, created, mime_type, child_count}. The pre-authenticated Graph downloadUrl is intentionally NOT returned (see SECURITY_REVIEW N-M2) — use download_file() to fetch content.

Inputs: path_or_id (required).

list_folderA

List the contents of a OneDrive folder.

Args: path: Folder path (e.g. '/Documents') or 'root'/'/' for the drive root. A Graph item id is also accepted. top: Page size, between 1 and 200 (default 50). next_link: Continuation returned by this tool; keep path and top unchanged.

Returns {items: [...], next_link, has_more}. Repeat with next_link until has_more is false. Opaque continuations are bound to this folder and page size, and expire after one hour or a server restart.

Inputs: top, path, next_link.

search_onedriveA

Search OneDrive for files/folders by name or content match.

Args: query: Search text (Graph full-text search over file/folder names and content). top: Page size, between 1 and 200 (default 20). next_link: Continuation returned by this tool; keep query and top unchanged.

Returns {query, count, items, next_link, has_more}. Repeat with next_link until has_more is false; count is the number of items in this page only.

Inputs: query (required), top, next_link.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool maps to a distinct resource+action pair: search by text, enumerate a folder, fetch metadata for one item, download file content, and retrieve drive-level info. The only near-overlap (search_onedrive vs list_folder) is clearly separated by text-query versus path-scoped semantics, and descriptions reinforce the boundary.

    Naming Consistency5/5

    All five tools follow a strict snake_case verb_noun pattern (search_, list_, get_, download_, get_). The verb choice matches the operation type, and there are no camelCase or vague-verb outliers.

    Tool Count5/5

    Five tools is well-scoped for a read-only OneDrive surface: discovery, enumeration, inspection, retrieval, and a health check. Every tool earns its place and nothing feels redundant or missing at this granularity.

    Completeness4/5

    Read-only coverage is solid: search, folder listing, metadata, content download, and auth smoke test cover the core lifecycle without dead ends. Minor gaps remain — no tool for shared/remote drives, recent or shared-with-me items, or permission/version metadata that Graph exposes.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets AI agents browse, search, and inspect a user's OneDrive files and folders through the Microsoft Graph API, including reading text file contents, viewing items shared with the user, and checking drive storage quota and owner details. It is also reachable over HTTP or as a local stdio server for direct tool calls.
      99 npm
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients to browse and read OneDrive contents through read-only tools for listing folders, searching content, finding files, listing albums, reading files, and reporting storage quota.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients to browse and read a user's Microsoft cloud drive through read-only tools for folder listing, full-text search, file lookup, album inspection, file reading, metadata, and storage quota.
      MIT