@mindstone/mcp-server-microsoft-files

Microsoft 365 OneDrive Files MCP server — list, search, get, download, upload, delete, move, copy, share files, manage sharing permissions and version history, review file activity, and read text and Office document contents via the Microsoft Graph API.

Cohort-style Microsoft 365 OneDrive MCP. Reuses the OAuth surface owned by @mindstone/mcp-server-microsoft-mail, so the host signs in once and gets files plus mail plus calendar plus Teams plus SharePoint from the same credentials.

Status

• Version: 0.2.1 · npm
• Auth: OAuth (host-orchestrated, shared with mcp-server-microsoft-mail) (MS_CLIENT_ID)
• Tools: 20 (files, folders, sharing, permissions, versions, activity)
• Surface: cloud-api
• Machine-readable: STATUS.json
• Shared library: @mindstone/mcp-server-microsoft-shared

Why this exists

When we ported this in May 2026, Microsoft's own Graph MCP lineup did not yet ship a stand-alone OneDrive server, and the community options at the time treated OneDrive as its own login surface — every connector ran a separate OAuth dance and stored its own copy of the refresh token. We pulled the bundled connector out of MindstoneRebel as a 1:1 port so that the same five-connector Microsoft 365 cohort (mail, calendar, files, teams, SharePoint) shares a single set of credentials, a single shared-library package for token persistence and request timeouts, and the structured auth_required envelope the host already knows how to recover from. Files reuses @mindstone/mcp-server-microsoft-mail's authenticate_microsoft_account tool rather than declaring its own.

Example interaction

"Find the latest version of Q3-plan.docx in my OneDrive and give me a sharing link my team can read."

Tools the host calls:

1. search_files — name:Q3-plan.docx, returns the most recent matching item.
2. share_file — creates a read-only sharing link for that item.

Response (trimmed):

{
  "match": {
    "id": "01H7...",
    "name": "Q3-plan.docx",
    "lastModifiedDateTime": "2026-05-18T17:42:00Z"
  },
  "share": {
    "type": "view",
    "scope": "organization",
    "webUrl": "https://example-my.sharepoint.com/:w:/g/personal/.../EZk..."
  }
}

Requirements

• Node.js 20+
• npm
• A host application that performs the Microsoft OAuth flow and writes per-account token files into ${MS_CONFIG_DIR}/credentials/${sanitised-email}.token.json and an ${MS_CONFIG_DIR}/accounts.json index. This server reads those files; it does not initiate OAuth itself.

One-click install

After clicking the button, your host will prompt you to fill: MS_CLIENT_ID, MS_CONFIG_DIR, MS_MCP_PACKAGE_ID, MICROSOFT_REQUEST_TIMEOUT_MS.

{
  "mcpServers": {
    "Microsoft 365 Files": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-microsoft-files"
      ],
      "env": {
        "MS_CLIENT_ID": "",
        "MS_CONFIG_DIR": "",
        "MS_MCP_PACKAGE_ID": "Microsoft365Files",
        "MICROSOFT_REQUEST_TIMEOUT_MS": "60000"
      }
    }
  }
}

Quick Start

Install & build

cd <path-to-repo>/connectors/microsoft-files
npm install
npm run build

npx (once published)

npx -y @mindstone/mcp-server-microsoft-files

Local

node dist/index.js

Configuration

This server runs alongside a host application that owns the Microsoft 365 OAuth flow. The host writes credentials to disk; this server reads them.

Required environment variables

| Name | Description | | ---- | ----------- | | MS_CLIENT_ID | Microsoft Entra (Azure AD) application client ID. | | MS_CONFIG_DIR | Path to the per-user Microsoft config directory (credentials/, accounts.json). |

Optional environment variables

| Name | Description | Default | | ---- | ----------- | ------- | | MS_ACCOUNT_EMAIL | Account email when running in multi-account per-instance mode. | First account in accounts.json. | | MS_MCP_PACKAGE_ID | Logical package ID surfaced in error responses. | Microsoft365Files | | MICROSOFT_REQUEST_TIMEOUT_MS | Override the upstream Microsoft Graph request timeout (max 300000 ms). | 60000 | | MICROSOFT_DISABLE_REFRESH | Set to 1 to disable token refresh on this surface. Tools fail closed with the structured auth_required response so the host can drive reauth. Cloud surfaces set this to 1. | unset |

Host configuration examples

Claude Desktop / Cursor

{
  "mcpServers": {
    "Microsoft365Files": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-microsoft-files"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
      }
    }
  }
}

Sign in via @mindstone/mcp-server-microsoft-mail's authenticate_microsoft_account first; the files tools then reuse the credentials it writes to ${MS_CONFIG_DIR}/.

Local development (no npm publish needed)

{
  "mcpServers": {
    "Microsoft365Files": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/microsoft-files/dist/index.js"],
      "env": {
        "MS_CLIENT_ID": "your-entra-application-client-id",
        "MS_CONFIG_DIR": "/absolute/path/to/microsoft-config"
      }
    }
  }
}

Tools (20)

| Tool | Description | | ---- | ----------- | | list_files | List files and folders in OneDrive (root by default). | | get_file | Get metadata for a specific file or folder. | | download_file | Get a short-lived download URL for a file. | | search_files | Search for files in OneDrive by name or content. | | upload_file | Upload a file to OneDrive (text up to 4 MB; binary as base64 up to 10 MB via a resumable upload session). | | create_folder | Create a new folder in OneDrive. | | delete_file | Delete a file or folder. | | move_file | Move a file or folder to a new location. | | copy_file | Copy a file or folder to a new location. | | get_recent | List recently accessed files. | | get_shared | List files shared with you by others. | | share_file | Create a sharing link for a file or folder. | | read_text_file | Read the contents of a text file. | | invite_to_file | Share a file or folder with specific people by email (read or write). | | list_file_permissions | List the sharing permissions granted on a file or folder. | | revoke_file_permission | Revoke a sharing permission by ID. | | list_file_versions | List the version history of a file. | | restore_file_version | Restore a previous version, replacing the current content. | | list_file_activities | List recent file activity (drive-wide or per item; OneDrive for Business / SharePoint only). | | read_document | Extract the text of a Word (.docx) or PowerPoint (.pptx) file directly. |

Security notes

• No authentication tool of its own; sign-in is delegated to @mindstone/mcp-server-microsoft-mail so the cohort has a single OAuth surface.
• Token-provider refresh failures map to the structured auth_required response so the host can drive reauth without crashing.
• upload_file enforces empty-content validation in line with the bundled connector to reject zero-byte uploads as a misuse.
• Binary uploads chunk to the preauthenticated upload-session URL without the Graph access token, as Graph requires. The session URL is validated before any byte is sent: HTTPS on the default port, no userinfo, Microsoft OneDrive/SharePoint hosts only, and redirects are rejected rather than followed.
• Content authored in Microsoft 365 (file names, grantee identities, activity actors and action keys, permission roles, extracted document text, and Graph error messages) is returned inside <untrusted-content> envelopes; Graph responses on the permission/version/activity/upload/document paths are Zod-validated at the boundary. Functional identifiers (permission/version/item IDs) and webUrls stay structural so they can round-trip into follow-up tool calls.
• Permission/version/activity lists follow @odata.nextLink pagination (bounded, with an explicit truncated flag); continuation links are only followed back to the Graph host so the access token cannot leak to another origin.
• read_document downloads are byte-capped mid-stream (not just by advertised metadata size) and Office ZIP inflation is bounded per-entry and cumulatively, so ZIP bombs cannot expand in memory.
• read_document follows Graph's redirect to the pre-authenticated download URL manually: each hop is revalidated against the same OneDrive/SharePoint host policy as upload sessions, hops are capped, and the access token is only sent to the Graph host — never forwarded across origins.
• Numeric limits (top, maxSize, maxChars) must be positive integers and are rejected before any network request.
• Per-tool Graph calls run under a composed caller + cohort timeout signal.

Licence

FSL-1.1-MIT — Functional Source License, Version 1.1, with MIT future licence. Free for non-competing use; relicenses to MIT on the converter date in LICENSE.