Microsoft 365 Files

@mindstone/mcp-server-microsoft-files

Microsoft 365 OneDrive 文件 MCP 服务——通过 Microsoft Graph API 列出、搜索、获取、下载、上传、删除、移动、复制和共享文件，管理共享权限和版本历史记录，查看文件活动，以及读取文本和 Office 文档内容。

面向 Microsoft 365 OneDrive 的 Cohort 风格 MCP。复用 @mindstone/mcp-server-microsoft-mail 所负责的 OAuth 接入，因此宿主只需登录一次，即可使用文件、邮件、日历、Teams 和 SharePoint，并共享同一组凭据。

状态

• 版本： 0.2.1 · npm
• 身份验证： OAuth（由宿主协调，与 mcp-server-microsoft-mail 共享）(MS_CLIENT_ID)
• 工具： 20（文件、文件夹、共享、权限、版本、活动）
• 接入方式： cloud-api
• 机器可读信息： STATUS.json
• 共享库： @mindstone/mcp-server-microsoft-shared

项目缘起

2026 年 5 月移植本项目时，Microsoft 自家的 Graph MCP 系列尚未提供独立的 OneDrive 服务，当时的社区方案则将 OneDrive 视为独立的登录入口——每个连接器都要单独完成一次 OAuth 流程，并存储自己的刷新令牌副本。我们将 MindstoneRebel 中捆绑的连接器拆分出来，按原样移植，以便同一组由五个连接器组成的 Microsoft 365 套件（邮件、日历、文件、Teams、SharePoint）共享一组凭据、一个用于令牌持久化和请求超时处理的共享库包，以及宿主已知如何恢复的结构化 auth_required 信封。Files 复用 @mindstone/mcp-server-microsoft-mail 的 authenticate_microsoft_account 工具，而不是自行声明该工具。

交互示例

“在我的 OneDrive 中查找 Q3-plan.docx 的最新版本，并提供一个团队可读取的共享链接。”

宿主调用的工具：

1. search_files — name:Q3-plan.docx，返回最新的匹配项。
2. share_file — 为该项创建只读共享链接。

响应（已删节）：

{
  "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..."
  }
}

要求

• Node.js 20+
• npm
• 能够执行 Microsoft OAuth 流程，并将每个帐户的令牌文件写入 ${MS_CONFIG_DIR}/credentials/${sanitised-email}.token.json，且写入 ${MS_CONFIG_DIR}/accounts.json 索引的宿主应用。本服务读取这些文件；不会自行发起 OAuth 流程。

一键安装

点击按钮后，宿主将提示你填写：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"
      }
    }
  }
}

快速入门

安装与构建

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

npx（发布后使用）

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

本地

node dist/index.js

配置

此服务与负责 Microsoft 365 OAuth 流程的宿主应用并行运行。宿主会将凭据写入磁盘；此服务会读取这些凭据。

必需的环境变量

可选的环境变量

宿主配置示例

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"
      }
    }
  }
}

请先通过 @mindstone/mcp-server-microsoft-mail 的 authenticate_microsoft_account 登录；随后，文件工具会复用其写入 ${MS_CONFIG_DIR}/ 的凭据。

本地开发（无需发布到 npm）

{
  "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"
      }
    }
  }
}

工具（20）

安全说明

• 本身不提供身份验证工具；登录由 @mindstone/mcp-server-microsoft-mail 处理，以便整个套件共用一个 OAuth 接口。
• Token 提供程序刷新失败时，会映射为结构化的 auth_required 响应，以便宿主触发重新身份验证，而不会崩溃。
• upload_file 会按照随附连接器的规则验证内容不能为空，拒绝将零字节上传作为误用。
• 二进制文件会分块上传到预先完成身份验证的上传会话 URL，不会携带 Graph 访问令牌，这是 Graph 的要求。发送任何字节前都会验证会话 URL：必须使用默认端口上的 HTTPS、不得包含用户信息，且主机只能是 Microsoft OneDrive / SharePoint；遇到重定向时会拒绝，而不会跟随。
• 在 Microsoft 365 中创建的内容（文件名、被授权者身份、活动执行者和操作键、权限角色、提取的文档文本以及 Graph 错误消息）会放在 <untrusted-content> 信封中返回；权限、版本、活动、上传和文档相关路径上的 Graph 响应会在边界处通过 Zod 验证。功能标识符（权限 / 版本 / 项目 ID）和 webUrl 保持结构化，以便后续工具调用能够原样传递。
• 权限 / 版本 / 活动列表会遵循 @odata.nextLink 分页（设有上限，并提供明确的 truncated 标志）；仅当续页链接指向 Graph 主机时才会跟随，以免访问令牌泄露给其他源。
• read_document 下载会在流传输过程中限制字节数（而不只是依赖声明的元数据大小），并对 Office ZIP 解压设置单个条目和累计上限，以防 ZIP 炸弹占用过多内存。
• read_document 会手动跟随 Graph 重定向到预先完成身份验证的下载 URL：每一跳都会按照与上传会话相同的 OneDrive / SharePoint 主机策略重新验证，跳转次数有限制，且访问令牌只会发送到 Graph 主机，绝不会跨源转发。
• 数值限制（top、maxSize、maxChars）必须为正整数，并会在发起任何网络请求前验证；不符合要求的值会被拒绝。
• 每个工具的 Graph 调用均在调用方与套件组合而成的超时信号下运行。

许可证

FSL-1.1-MIT — Functional Source License，Version 1.1，未来将采用 MIT 许可证。可免费用于非竞争性用途；在 LICENSE 中规定的转换日期后重新授权为 MIT。