Metadata-Version: 2.4
Name: joescars-onedrive-mcp
Version: 0.1.0
Summary: Read-only MCP server for personal Microsoft OneDrive accounts
Author: Joe Raio
License-Expression: MIT
Project-URL: Homepage, https://github.com/joescars/onedrive-mcp
Project-URL: Repository, https://github.com/joescars/onedrive-mcp
Project-URL: Issues, https://github.com/joescars/onedrive-mcp/issues
Keywords: mcp,onedrive,microsoft-graph,read-only
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet
Classifier: Topic :: Office/Business
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2.0.0,>=1.2.0
Requires-Dist: msal>=1.28.0
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: filelock>=4.2.1
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: responses>=0.25.0; extra == "test"
Dynamic: license-file

# OneDrive Read-Only MCP Server

[![Tests and dependency audit](https://github.com/joescars/onedrive-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/joescars/onedrive-mcp/actions/workflows/ci.yml)

A local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
server that lets AI agents search, inspect, and download files from a personal
Microsoft OneDrive account.

> [!IMPORTANT]
> This project is **read-only**. It exposes five read-style tools and only
> performs HTTP GET requests against Microsoft Graph. It cannot upload, edit,
> rename, move, or delete OneDrive content.

## Features

- Search OneDrive by file name or indexed content.
- Browse folders with secure, bounded pagination.
- Inspect file and folder metadata.
- Download files to a controlled local directory without overwriting existing
  files.
- Refresh cached Microsoft credentials without interactive sign-in.
- Connect directly to VS Code, Hermes, or pi over stdio, or to Open WebUI
  through an authenticated `mcpo` bridge.

This server targets **personal Microsoft accounts and consumer OneDrive**.
OneDrive for Business and SharePoint are outside the project's default scope.

## Requirements

- Linux is the supported production platform. Windows is suitable for
  development only because POSIX file modes do not establish Windows ACLs.
- Source installs require Python 3.11 or newer. The optional npm launcher
  requires Node.js 18+ and Astral `uv` (which can provision Python).
- A personal Microsoft account and a Microsoft Entra app registration
  configured for device-code authentication; see the
  [registration prerequisites](docs/setup.md#1-register-an-azure-application).

## Quick start

For complete Azure and authentication instructions, see
[Setup](docs/setup.md).

```bash
git clone https://github.com/joescars/onedrive-mcp.git
cd onedrive-mcp
python3 -m venv venv
./venv/bin/pip install --require-hashes -r requirements.lock
export ONEDRIVE_MCP_CONFIG_DIR="${ONEDRIVE_MCP_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/onedrive-mcp}"
CONFIG_DIR="$ONEDRIVE_MCP_CONFIG_DIR"
install -d -m 700 "$CONFIG_DIR"
cp .env.example "$CONFIG_DIR/.env"
```

Set `AZURE_CLIENT_ID` in `"$CONFIG_DIR/.env"`, restrict the file, and sign in:

```bash
chmod 600 "$CONFIG_DIR/.env"
./venv/bin/python scripts/setup_auth.py
./venv/bin/python scripts/smoke_test.py
```

The token cache and downloads default to the stable per-user data directory
(`$XDG_DATA_HOME/onedrive-mcp` or `~/.local/share/onedrive-mcp`), not the
checkout or package install directory. The smoke test reads drive information
and lists the root folder. It does not download or modify files.

## Connect a client

Complete the quick start before configuring a client. The MCP host starts this
server when needed; do not leave a separate standalone process running.

| Client                      | Transport               | Guide                                                        |
| --------------------------- | ----------------------- | ------------------------------------------------------------ |
| VS Code with GitHub Copilot | stdio                   | [VS Code setup](docs/clients.md#vs-code-with-github-copilot) |
| Hermes                      | stdio                   | [Hermes setup](docs/clients.md#hermes)                       |
| pi (pi.dev)                 | stdio                   | [pi setup](docs/clients.md#pi-pi-dev)                         |
| npx launcher                | stdio                   | [npm installation](docs/npm.md)                               |
| Open WebUI                  | OpenAPI/HTTP via `mcpo` | [Bridge deployment](docs/deployment.md)                      |

Example VS Code workspace configuration:

```json
{
  "servers": {
    "onedrive": {
      "type": "stdio",
      "command": "${workspaceFolder}/venv/bin/python",
      "args": ["${workspaceFolder}/server.py"]
    }
  }
}
```

Use absolute paths for user-level or remote-user configuration. No tokens or
`.env` values belong in client configuration.

## Tools

| Tool                                             | Description                                |
| ------------------------------------------------ | ------------------------------------------ |
| `search_onedrive(query, top=20, next_link=None)` | Search the drive one page at a time        |
| `list_folder(path='/', top=50, next_link=None)`  | List a folder's children                   |
| `get_item_metadata(path_or_id)`                  | Return metadata for one file or folder     |
| `download_file(path_or_id, dest_filename=None)`  | Download a file into `DOWNLOAD_DIR`        |
| `get_drive_info()`                               | Return drive, owner, and quota information |

Paths such as `/Documents/report.pdf` and raw Graph item IDs are accepted where
`path_or_id` is documented. Pagination continuations are opaque and must be
passed back to the same tool with the original arguments.

See the [Tool reference](docs/tools.md) for complete inputs, outputs, and
pagination behavior.

Example prompts:

- `Use OneDrive to list /Documents without downloading anything.`
- `Search OneDrive for "invoice" and tell me if more pages are available.`
- `Get metadata for /Documents/report.pdf without downloading it.`
- `Download /Documents/report.pdf as report-copy.pdf.`

Downloads remain on the machine running the server. The tool returns a local
path and metadata, not the file's contents.

## Security and privacy

- Microsoft Graph operations use the GET-only helper in `graph_client.py` and
  read-only delegated scopes; this is not a guarantee against future code changes.
- The token cache and downloads are stored with owner-only POSIX permissions.
- Signed Graph download URLs are never returned in tool results or errors.
- Downloads have configurable per-file and directory-wide limits.
- Existing files are never overwritten.
- The optional HTTP bridge requires an API key and defaults to loopback.

Read-only access is still sensitive: names, paths, metadata, and quota details
returned by tools enter the MCP client's context. Use only accounts and files
you intend to make available, and never share `token_cache.bin`.

See [Security](docs/security.md) for the trust model, safeguards, and
operational limitations.

## Documentation

| Guide                                       | Covers                                                                     |
| ------------------------------------------- | -------------------------------------------------------------------------- |
| [Setup](docs/setup.md)                      | Azure registration, local installation, environment variables, and sign-in |
| [Client configuration](docs/clients.md)     | VS Code, Hermes, pi, and stdio operation                                    |
| [npm installation](docs/npm.md)              | Version-pinned npm launcher and separate device-code setup                  |
| [Tool reference](docs/tools.md)             | Tool inputs, response shapes, pagination, and downloads                    |
| [Open WebUI deployment](docs/deployment.md) | Authenticated `mcpo` bridge and systemd                                    |
| [Security](docs/security.md)                | Read-only enforcement, local storage, pagination, and privacy              |
| [Development](docs/development.md)          | Tests, dependency locks, smoke tests, and project structure                |
| [Troubleshooting](docs/troubleshooting.md)  | Common authentication, Graph, client, and dependency errors                |

## Development

Run the credential-free test suite:

```bash
./venv/bin/python -m pytest -v
```

Tests mock Microsoft Graph and MSAL traffic; they do not access a real
OneDrive account. See [Development](docs/development.md) for maintenance and
contribution details.

## License

This project is licensed under the [MIT License](LICENSE). It is an
independent community project and is not affiliated with or endorsed by
Microsoft.
