onedrive-cli MCP server
Commit Nov 13, 2026Allows an AI client to browse, search, and read files from a OneDrive account via a read-only MCP server.
Also known as lionello/onedrive-cli
- Stars
- 179
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is onedrive-cli MCP?
onedrive-cli allows an AI client to browse, search, and read files from a OneDrive account via a read-only MCP server.
Summary generated from the project's README
About onedrive-cli MCP server
Browsing and searching your personal OneDrive files from within an AI client is what this MCP server enables. By running the onedrive mcp command, you provide an interface for tools like Claude to interact with your cloud storage through a read-only connection. This setup ensures that the AI can access your data without the ability to modify or delete any files.
To use this server, you must first authenticate using the onedrive login command, which opens a browser to secure an OAuth access token. For maximum security, you can use the -r flag during login to generate a read-only token. Once configured, the server provides specific tools such as list_onedrive_folder, search_onedrive_content, and read_onedrive_file to help the AI navigate your directories, perform full-text searches, and extract text from documents.
This tool is ideal for developers or researchers who want to give their AI assistants context from their existing cloud-based document collections. It handles metadata via stat_onedrive_item and can even report your storage quota using the onedrive_storage tool.
What you can do with it
- 1Search through cloud documentsAsk your AI client to find specific information buried within your OneDrive files using full-text search.
- 2Read file contents directlyHave an AI assistant read the text inside a specific document stored in your OneDrive account.
- 3Explore photo albumsRequest that the AI list your organized photo bundles to find specific collections.
- 4Check storage availabilityAsk the AI how much space you have left in your OneDrive account.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelionello/onedrive-cli is public and reachablegithub.com/lionello/onedrive-cli ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/lionello/onedrive-cli ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 5.2 / 10; weakest: Token-Permissions 0, CII-Best-Practices 0, Fuzzing 0scorecard.dev/viewer/?uri=github.com/lionello/onedrive-cli ↗Partial 8/15
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubonedrive-cli
Cross-platform command line interface for OneDrive (Personal)
Installation
With npm:
npm install -g @lionello/onedrive-cli
That installs the command as onedrive, with onedrive-cli as an alias for it.
Or with nix-env:
nix-env -if https://github.com/lionello/onedrive-cli/archive/master.tar.gz -A package
Or from source:
git clone https://github.com/lionello/onedrive-cli.git
cd onedrive-cli
npm install
bin/onedrive login
Getting started
Sign in once, then use the drive like a filesystem:
onedrive login # opens the Microsoft login page
onedrive df # check the connection and storage usage
onedrive ls # list your drive root
login opens your browser, then stores the access token it gets back in
~/.onedrive-cli-token (or $XDG_STATE_HOME if that is set). Tokens are valid
for one hour, so run login again when a command reports that the token
expired. Add -r for a read-only token.
Usage
usage: onedrive COMMAND [arguments]
Run onedrive help (or -h/--help) for this list at any time, and
onedrive --version for the installed version. The commands are:
album- list, create, or edit photo albums (ls/create/add/rm)cat- dumps the contents of a file to stdoutchmod- change sharing permissionscp- copies local file(s) to OneDrive or vice-versadf- shows OneDrive storage usage statsfind- find file(s) or folder(s) by name, optionally separated byNULgrep- full-text search across the drive, listing matching pathshelp- shows list of supported commandsln- create a link to the remote itemlogin- request/store an OAuth access tokenls- list the contents of a foldermcp- run a read-only MCP server over stdiomkdir- create a remote foldermv- move a local file to OneDrive or vice-versarm- delete a file or folder from OneDrivesendmail- send an invitation email for editing to recipientsstat- dump all information for particular file(s)wget- copy a remote URL to OneDrive (server side)
Examples
List the contents of the Public folder
onedrive ls Public
Grep one file
onedrive cat Documents/passwords | grep boa
Let OneDrive upload a file server side
onedrive wget http://mega.com/somehugepublicfile Documents/somehugepublicfile
Upload files recursively
find * -type f -print0 | xargs -0 -n1 -I{} onedrive cp "./{}" "Shared Favorites/{}"
Move remote files to a new folder
onedrive find 'Pictures/Camera Roll' -regex 2015 -type f -print0 | xargs -0 onedrive mv -t :/Pictures/2015/
Create an album and add photos to it
onedrive album create 'Summer 2026'
onedrive album add 'Summer 2026' 'Pictures/Camera Roll/IMG_1234.jpg'
onedrive albums # list all albums
onedrive albums 'Summer 2026' # list the photos in one album
Albums are OneDrive bundles:
they live outside the folder hierarchy and only reference the files, so
album rm removes a photo from the album without deleting the file.
Deleting an album itself is not supported by the API — use the OneDrive
web UI for that.
MCP server
onedrive mcp starts a read-only Model Context Protocol
server over stdio, so an MCP client (Claude, etc.) can browse and read your
OneDrive. It reuses the stored access token, so login first — ideally with
login -r for a read-only token. The server only issues GET requests and
cannot modify the drive. It exposes these tools:
list_onedrive_folder- list the direct children of a foldersearch_onedrive_content- full-text search across the whole drivefind_onedrive_files- recursively find items by name globlist_onedrive_albums- list the photo albums, or the items in one albumread_onedrive_file- read a file's contents as textstat_onedrive_item- return full metadata for an itemonedrive_storage- report storage quota for the available drives
Register it with your MCP client, e.g. in claude_desktop_config.json:
{
"mcpServers": {
"onedrive": {
"command": "onedrive",
"args": ["mcp"]
}
}
}
FAQ
Access token was not found; 'login' first.
The onedrive utility needs an access token in order to read/write to your OneDrive storage.
Run onedrive login: it opens the Microsoft login page, and after you sign in the
callback page
hands the token straight back to the waiting command, which saves it to
~/.onedrive-cli-token. If the browser runs on another machine (or the handover
fails), the page shows the token so you can paste it at the prompt instead.
Tokens are valid for 1 hour.
"An item with the same name already exists under the parent"
Currently, a copy will fail if a file with the same it already exists. Change the name of the target, or use other means to delete/rename the existing file in your OneDrive.
Invalid source name
You cannot copy folders. Specify a source file instead, or use wildcards.
Invalid target name
The target file name cannot be determined from the source path. Specify a target file name.
Use ./ or :/ path prefix for local or remote paths.
The cp command supports both local->remote as well as remote->local copy.
To make it clear which path is remote and which is local, either use ./ as a prefix for
the local path, or use :/ as a prefix for the remote path. Either one will suffice.
chmod: Invalid file mode
The chmod command currently only supports -w or -rw. The former tried to downgrade write
shares to read-only, whereas the latter removes all shares for the given item(s). Octal modes are accepted (for example 644, 0700) as well as og-rw or g-w.
TODO
Tracked on the issue tracker, so this stays a pointer rather than a second source of truth:
- #33 — uploads larger than 100 MiB (
createUploadSession) - #36 — skip the transfer when the SHA1 already matches
- #34 —
chmod: granting write access (+w) - #37 — confirm the API honours gzip/deflate on downloads
- #4, #8 — OneDrive for Business, via Microsoft Graph
DONE
- Read-only MCP server (
onedrive mcp) - Photo albums via bundles (
onedrive album) - Full-text search across the drive (
onedrive grep) - Capture the OAuth token over a loopback listener instead of copy-paste
- Delete files and folders (
onedrive rm) - Get the sharing link for a file (
onedrive ln) - Register with NPM (@lionello/onedrive-cli)
- Fixed OAuth redirect on Safari (https://bugs.webkit.org/show_bug.cgi?id=24175)
- Use XDG path spec for token file (https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
- Using
async/await
Development
A Nix flake provides the package and a dev shell with all
dependencies. Run nix develop (or use Direnv's use flake)
for the shell, and nix build / nix run to build or run the CLI. The legacy
shell.nix still works with nix-shell.
Update the dependency hash
After changing package-lock.json, refresh npmDepsHash in flake.nix:
nix run nixpkgs#prefetch-npm-deps -- package-lock.json
Regenerate the website
docs/index.html is generated from this README:
npm run readme
onedrive-cli MCP questions
How do I authenticate with OneDrive?
Run the 'onedrive login' command, which opens a Microsoft login page in your browser to obtain an access token.
Is the MCP server capable of modifying my files?
No, the MCP server is read-only and only issues GET requests, meaning it cannot modify your drive.
How long are the access tokens valid?
Tokens are valid for one hour, so you may need to run the login command again if they expire.
Can I use the MCP server in a read-only mode?
Yes, you can use the 'login -r' command to obtain a read-only token for the server.