Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OneDrive Read-Only MCP Server search my OneDrive for the Q3 budget spreadsheet"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 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.
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.
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.
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-setupThe setup command follows npm's latest tag. The MCP client example below
pins the running server to 0.1.1 so upgrades are intentional; use that pin
after the matching npm and PyPI releases are available.
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.
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.
Related MCP server: mcp-onedrive
The server provides these five MCP tools:
Tool | Purpose |
| Search by file name or indexed content, one page at a time. |
| List a folder's children with bounded pagination. |
| Inspect metadata for a file or folder. |
| Download a file into the local download directory without overwriting an existing file. |
| 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.
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.
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.
Guide | What it covers |
Microsoft app registration, source installation, configuration, and sign-in. | |
VS Code, Hermes, pi, stdio, and Open WebUI setup. | |
Published launcher requirements, sign-in, and client configuration. | |
Tool inputs, response shapes, pagination, and downloads. | |
Read-only design, local storage, and privacy considerations. | |
Tests, dependency maintenance, and publishing releases. | |
Authentication, Graph, client, and dependency issues. |
MIT licensed; see LICENSE. This is an independent community project and is not affiliated with or endorsed by Microsoft.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path_or_id | Yes | ||
| dest_filename | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well. It discloses that the source is never modified, the file is always saved to disk with owner-only permissions, base64 is not returned, large files are handled safely, and existing destinations raise an error instead of being overwritten.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and safety property, then organized into Args and Returns sections. Despite its length, every sentence adds necessary constraints or behavioral context, especially given the bare input schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, but the description supplies return fields, local-save behavior, safety constraints, and parameter meaning. For a two-parameter download tool, this gives an agent enough information to call it correctly and anticipate errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does. It explains path_or_id as a human path or Graph item id for the file, and dest_filename as an optional bare local filename with defaulting, location, separator restrictions, and no-overwrite behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: downloading a OneDrive file's content to local disk. It clearly distinguishes the operation from sibling tools like search_onedrive, list_folder, get_item_metadata, and get_drive_info by emphasizing file-content retrieval and local saving.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is clear: retrieve a file's actual content rather than metadata or folder listings. However, it does not explicitly name alternative tools or state when not to use this tool, such as for folders or metadata-only requests.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the load: 'Get' plus a pure read-shaped return list make the read-only, side-effect-free nature unambiguous. Because there is no output schema, the explicit field list (drive_id, drive_type, owner_name, quota_used, quota_total, quota_remaining, web_url) adds real behavioral value. It doesn't mention auth-failure behavior or latency, keeping it at 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the purpose and the smoke-test cue. The return-field list is compact and earns its place because no output schema exists to convey it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only metadata tool with no output schema, the description covers purpose, use case, and return shape — everything an agent needs to call it correctly. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4 by rule and there is nothing further to document. The description correctly implies a no-argument call rather than leaving the agent guessing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get basic OneDrive info') and enumerates exactly what is returned (quota, owner, drive id). It also distinguishes itself from the file/folder siblings (search_onedrive, list_folder, get_item_metadata, download_file) by being the account-level metadata call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete use case — 'useful as a smoke test that authentication is working' — which tells the agent when to reach for it (first call / auth validation) rather than the content-oriented siblings. It does not explicitly state when *not* to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path_or_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the burden: it discloses the exact return shape, declares the operation's read nature implicitly, and surfaces a non-obvious security decision (downloadUrl withheld per SECURITY_REVIEW N-M2). It omits error behavior for invalid paths/ids and any permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose sentence, then Args and Returns blocks with zero filler; the return-field enumeration earns its place because no output schema exists. Slightly list-heavy, but nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the explicit return-field list is essential and present, as is the parameter dual-form explanation. The remaining gap is failure modes — what happens on an unresolvable path or missing item — which an agent would need before calling confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by defining the single parameter's two accepted forms with a concrete path example ('/Documents/foo.pdf') and the raw Graph drive item id alternative — information available nowhere else.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get full metadata for a single OneDrive file or folder'), and the word 'single' plus the plural siblings (search_onedrive, list_folder) makes the scope distinction clear without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes content retrieval to download_file() and explains why the downloadUrl is omitted, so the agent knows when to reach for another tool. It does not address when to prefer get_drive_info or how to handle a not-found path, so it stops short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| path | No | / | |
| next_link | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses the return shape ({items, next_link, has_more}), pagination behavior, continuation binding to folder and page size, and one-hour/server-restart expiry. It stops short of mentioning permissions, error behavior, or read-only safety, but it is unusually transparent for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then succinctly details parameters, return value, and pagination rules. Every sentence earns its place, and the paging instruction is clear without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and an output schema, the description provides enough context to invoke the tool correctly, including return structure and continuation semantics. It could be slightly more complete with a note on permissions or error handling, but the essential operational context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: path accepts a folder path, 'root'/'/', or a Graph item id; top is a page size between 1 and 200 with default 50; next_link is a continuation that requires keeping path and top unchanged. These details add substantial meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List the contents of a OneDrive folder.' This clearly identifies the operation, but it does not explicitly distinguish the tool from siblings like search_onedrive or get_item_metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by explaining pagination with next_link, but it never explicitly states when to use this tool versus search_onedrive or get_item_metadata. There are no exclusions or alternative-routing instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| query | Yes | ||
| next_link | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral load, and it does disclose the return envelope and the paging contract, including that count is page-local. It omits scope questions an agent would care about, such as permission/auth requirements and whether shared or other-drive content is included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose sentence, then compact per-argument notes, then a returns/paging paragraph. Every line carries information the schema does not, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with no output schema, the description fully covers parameters, return shape, and the pagination loop. The remaining gap is operational context — auth scope and what corpus is searched — which no other structured field supplies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does: query is defined as Graph full-text over names and content, top is bounded at 1-200 with a default of 20, and next_link is explained as a continuation that requires holding query and top constant — a constraint absent from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource plus the match surface ('by name or content match'), which distinguishes it from list_folder's enumeration role. It stops short of explicitly naming a sibling or when enumeration beats searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use it when you have search text. The only explicit procedural guidance concerns pagination ('Repeat with next_link until has_more is false'), not tool selection against list_folder or get_item_metadata. No exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1download_fileget_drive_infoget_item_metadatalist_foldersearch_onedriveScored across 5 tools
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.
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.
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.
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.
Permissioned access to Outlook, OneDrive and Teams via the user's own Microsoft account
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Find, read and reorganize files across Google Drive, OneDrive, SharePoint and Dropbox, with undo.
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants