{"id":"2f4941b5-d1a8-492b-b2a0-e4a03858cb06","slug":"onedrive-cli","kind":"mcp","name":"onedrive-cli","summary":"Command line interface and MCP for OneDrive","owner":"lionello","repoUrl":"https://github.com/lionello/onedrive-cli","license":"MIT","licenseTier":"permissive","trust":"community","stars":174,"match":null,"fewStars":false,"format":"mcp","createdAt":null,"addedAt":"2026-10-14T03:44:01.806Z","logoUrl":"https://avatars.githubusercontent.com/u/591860?u=07c14174d1683dfcaf1ce4c6099eeb5fa5189426&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":["onedrive","onedrive-storage","nodejs","onedrive-api","onedrive-client","command-line","command-line-tool"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T03:55:07.241Z","sample":false,"url":"https://conduits.dev/tools/onedrive-cli","language":"JavaScript","transports":["stdio"],"install":{"npm":"@lionello/onedrive-cli"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# onedrive-cli\n\nCross-platform command line interface for OneDrive (Personal)\n\n## Installation\n\nWith `npm`:\n\n```sh\nnpm install -g @lionello/onedrive-cli\n```\n\nThat installs the command as `onedrive`, with `onedrive-cli` as an alias for it.\n\nOr with `nix-env`:\n\n```sh\nnix-env -if https://github.com/lionello/onedrive-cli/archive/master.tar.gz -A package\n```\n\nOr from source:\n\n```sh\ngit clone https://github.com/lionello/onedrive-cli.git\ncd onedrive-cli\nnpm install\nbin/onedrive login\n```\n\n## Getting started\n\nSign in once, then use the drive like a filesystem:\n\n```sh\nonedrive login          # opens the Microsoft login page\nonedrive df             # check the connection and storage usage\nonedrive ls             # list your drive root\n```\n\n`login` opens your browser, then stores the access token it gets back in\n`~/.onedrive-cli-token` (or `$XDG_STATE_HOME` if that is set). Tokens are valid\nfor one hour, so run `login` again when a command reports that the token\nexpired. Add `-r` for a read-only token.\n\n## Usage\n\n`usage: onedrive COMMAND [arguments]`\n\nRun `onedrive help` (or `-h`/`--help`) for this list at any time, and\n`onedrive --version` for the installed version. The commands are:\n\n-   `album` - list, create, or edit photo albums (`ls`/`create`/`add`/`rm`)\n-   `cat` - dumps the contents of a file to stdout\n-   `chmod` - change sharing permissions\n-   `cp` - copies local file(s) to OneDrive or vice-versa\n-   `df` - shows OneDrive storage usage stats\n-   `find` - find file(s) or folder(s) by name, optionally separated by `NUL`\n-   `grep` - full-text search across the drive, listing matching paths\n-   `help` - shows list of supported commands\n-   `ln` - create a link to the remote item\n-   `login` - request/store an OAuth access token\n-   `ls` - list the contents of a folder\n-   `mcp` - run a read-only [MCP](https://modelcontextprotocol.io) server over stdio\n-   `mkdir` - create a remote folder\n-   `mv` - move a local file to OneDrive or vice-versa\n-   `rm` - delete a file or folder from OneDrive\n-   `sendmail` - send an invitation email for editing to recipients\n-   `stat` - dump all information for particular file(s)\n-   `wget` - copy a remote URL to OneDrive (server side)\n\n## Examples\n\n##### List the contents of the Public folder\n\n`onedrive ls Public`\n\n##### Grep one file\n\n`onedrive cat Documents/passwords | grep boa`\n\n##### Let OneDrive upload a file server side\n\n`onedrive wget http://mega.com/somehugepublicfile Documents/somehugepublicfile`\n\n##### Upload files recursively\n\n`find * -type f -print0 | xargs -0 -n1 -I{} onedrive cp \"./{}\" \"Shared Favorites/{}\"`\n\n##### Move remote files to a new folder\n\n`onedrive find 'Pictures/Camera Roll' -regex 2015 -type f -print0 | xargs -0 onedrive mv -t :/Pictures/2015/`\n\n##### Create an album and add photos to it\n\n```sh\nonedrive album create 'Summer 2026'\nonedrive album add 'Summer 2026' 'Pictures/Camera Roll/IMG_1234.jpg'\nonedrive albums                # list all albums\nonedrive albums 'Summer 2026'  # list the photos in one album\n```\n\nAlbums are OneDrive [bundles](https://learn.microsoft.com/onedrive/developer/rest-api/api/drive_list_bundles):\nthey live outside the folder hierarchy and only reference the files, so\n`album rm` removes a photo from the album without deleting the file.\nDeleting an album itself is not supported by the API — use the OneDrive\nweb UI for that.\n\n## MCP server\n\n`onedrive mcp` starts a read-only [Model Context Protocol](https://modelcontextprotocol.io)\nserver over stdio, so an MCP client (Claude, etc.) can browse and read your\nOneDrive. It reuses the stored access token, so `login` first — ideally with\n`login -r` for a read-only token. The server only issues `GET` requests and\ncannot modify the drive. It exposes these tools:\n\n-   `list_onedrive_folder` - list the direct children of a folder\n-   `search_onedrive_content` - full-text search across the whole drive\n-   `find_onedrive_files` - recursively find items by name glob\n-   `list_onedrive_albums` - list the photo albums, or the items in one album\n-   `read_onedrive_file` - read a file's contents as text\n-   `stat_onedrive_item` - return full metadata for an item\n-   `onedrive_storage` - report storage quota for the available drives\n\nRegister it with your MCP client, e.g. in `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"onedrive\": {\n      \"command\": \"onedrive\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n## FAQ\n\n##### Access token was not found; 'login' first.\n\nThe `onedrive` utility needs an access token in order to read/write to your OneDrive storage.\nRun `onedrive login`: it opens the Microsoft login page, and after you sign in the\n[callback page](https://github.com/lionello/onedrive-cli/blob/master/docs/oauthcallbackhandler.html)\nhands the token straight back to the waiting command, which saves it to\n`~/.onedrive-cli-token`. If the browser runs on another machine (or the handover\nfails), the page shows the token so you can paste it at the prompt instead.\nTokens are valid for 1 hour.\n\n##### \"An item with the same name already exists under the parent\"\n\nCurrently, a copy will fail if a file with the same it already exists.\nChange the name of the target, or use other means to delete/rename the existing file in your OneDrive.\n\n##### Invalid source name\n\nYou cannot copy folders. Specify a source file instead, or use wildcards.\n\n##### Invalid target name\n\nThe target file name cannot be determined from the source path. Specify a target file name.\n\n##### Use ./ or :/ path prefix for local or remote paths.\n\nThe `cp` command supports both local->remote as well as remote->local copy.\nTo make it clear which path is remote and which is local, either use `./` as a prefix for\nthe local path, or use `:/` as a prefix for the remote path. Either one will suffice.\n\n##### chmod: Invalid file mode\n\nThe `chmod` command currently only supports `-w` or `-rw`. The former tried to downgrade _write_\nshares 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`.\n\n<!-- readme-only:start -->\n\n## TODO\n\nTracked on the [issue tracker](https://github.com/lionello/onedrive-cli/issues),\nso this stays a pointer rather than a second source of truth:\n\n-   [#33](https://github.com/lionello/onedrive-cli/issues/33) — uploads larger than 100 MiB (`createUploadSession`)\n-   [#36](https://github.com/lionello/onedrive-cli/issues/36) — skip the transfer when the SHA1 already matches\n-   [#34](https://github.com/lionello/onedrive-cli/issues/34) — `chmod`: granting write access (`+w`)\n-   [#37](https://github.com/lionello/onedrive-cli/issues/37) — confirm the API honours gzip/deflate on downloads\n-   [#4](https://github.com/lionello/onedrive-cli/issues/4), [#8](https://github.com/lionello/onedrive-cli/issues/8) — OneDrive for Business, via Microsoft Graph\n\n## DONE\n\n-   Read-only [MCP](https://modelcontextprotocol.io) server (`onedrive mcp`)\n-   Photo albums via bundles (`onedrive album`)\n-   Full-text search across the drive (`onedrive grep`)\n-   Capture the OAuth token over a loopback listener instead of copy-paste\n-   Delete files and folders (`onedrive rm`)\n-   Get the sharing link for a file (`onedrive ln`)\n-   Register with NPM ([@lionello/onedrive-cli](https://www.npmjs.com/package/@lionello/onedrive-cli))\n-   Fixed OAuth redirect on Safari (https://bugs.webkit.org/show_bug.cgi?id=24175)\n-   Use XDG path spec for token file (https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)\n-   Using `async`/`await`\n\n<!-- readme-only:end -->\n\n## Development\n\nA [Nix](https://nixos.org) flake provides the package and a dev shell with all\ndependencies. Run `nix develop` (or use [Direnv](https://direnv.net)'s `use flake`)\nfor the shell, and `nix build` / `nix run` to build or run the CLI. The legacy\n`shell.nix` still works with `nix-shell`.\n\n### Update the dependency hash\n\nAfter changing `package-lock.json`, refresh `npmDepsHash` in `flake.nix`:\n\n```sh\nnix run nixpkgs#prefetch-npm-deps -- package-lock.json\n```\n\n### Regenerate the website\n\n`docs/index.html` is generated from this README:\n\n```sh\nnpm run readme\n```\n"}