SharePoint Bridge

中文 · English

中文

一个可从 GitHub 下载的本地 MCP 项目：Chromium 扩展负责从已登录的 SharePoint Online 页面捕获会话上下文，Node.js MCP 服务负责通过 Microsoft Graph / SharePoint REST 提供受监督的 SharePoint 操作。

项目不要求注册 Entra 应用，也不把 token 上传到云端。MCP 服务、HTTP bridge 和运行时数据都在本机运行；bridge 只监听 http://127.0.0.1:17374。

适合谁

• 想在 Claude Desktop、Cursor、VS Code 或其他支持 stdio MCP 的客户端中操作 SharePoint Online 的普通用户。
• 需要读取或维护列表、列表项、视图格式、权限、站点组、现代页面和文档库文件的用户。
• 接受“浏览器登录 + 本地扩展 + 本地 MCP 服务”工作方式的团队。

SharePoint Server（本地部署）、租户管理、无人值守登录和任意 SPFx/DOM 编辑不在项目范围内。

5 分钟安装

1. 下载并构建

从 GitHub 选择 Code → Download ZIP，解压到一个不会被移动的目录；或者使用 git clone。需要 Node.js 20 或更高版本，以及 Chrome 或 Edge。

在项目目录运行：

npm install
npm run build
npm run doctor

npm run build 会生成 dist/server/index.js 和 dist/extension。不要直接加载源码目录，扩展必须加载构建后的目录。

2. 加载 Chromium 扩展

1. 打开 edge://extensions 或 chrome://extensions。
2. 开启 Developer mode。
3. 选择 Load unpacked。
4. 选择项目下的 dist/extension 文件夹。
5. 打开或刷新目标 SharePoint Online 页面。

扩展需要读取 SharePoint/Graph 请求头，并把短期 token 发送给本机 bridge。首次安装前请确认代码来自你信任的 GitHub 仓库；权限原因见 安全说明。

3. 配置 MCP 客户端

MCP 客户端应启动构建后的 stdio 入口，而不是启动一个对外开放的 HTTP 服务。复制 Windows 配置示例，将路径替换成你的实际项目路径，再合并到客户端的 MCP 配置中。完整说明见 MCP 客户端配置。

Windows 配置的核心内容如下：

{
  "mcpServers": {
    "sharepoint-local": {
      "command": "node",
      "args": ["C:\\path\\to\\sharepoint-mcp\\dist\\server\\index.js"],
      "env": {
        "SHAREPOINT_MCP_DATA_DIR": "C:\\path\\to\\sharepoint-mcp\\data"
      }
    }
  }
}

配置保存后，重启 MCP 客户端。若客户端已经有旧配置，请确认它指向当前项目的 dist/server/index.js。

第一次使用

在 MCP 客户端中按以下顺序执行：

1. get_health：确认本地服务和 token audience 状态。
2. list_captured_sites：查看扩展捕获到的 SharePoint 站点。
3. resolve_site：在有可用 Graph token 或 SharePoint REST token 时解析目标站点。
4. set_active_site，或在当前标签页已解析成功时使用 set_active_site_from_tab。
5. get_active_site：再次确认 siteId 和 siteUrl。
6. 执行读取或写入工具。

每次写入前都要确认 active-site lock；删除、权限、更新和格式化操作必须先使用对应的 preview_* 工具，只能应用刚刚返回的 previewId。扩展弹窗还提供当前站点、连接状态、操作历史和可选的 token 自动刷新开关。

更新、停止和卸载

更新代码后：

git pull
npm install
npm run build

然后在扩展管理页对 dist/extension 点击 Reload，并重启 MCP 客户端。停止 MCP 客户端即可停止 stdio 服务；如果是手动运行 npm start，在对应终端按 Ctrl+C。

卸载时，先从 MCP 客户端删除 sharepoint-local 配置，再从 Chromium 扩展页 Remove。data/ 目录是本地会话和历史状态；如不再需要，可在确认备份后手动删除。

项目结构

extension/       Chromium MV3 扩展源码
server/          stdio MCP 服务、bridge、SharePoint API clients 和安全策略
scripts/         构建、诊断和真实站点测试脚本
tests/           单元测试和契约测试
skills/          SharePoint MCP 的安全使用说明与工具目录
docs/            面向用户和维护者的说明
examples/        MCP 客户端配置模板
data/            本地运行时数据（不会提交）
dist/            构建产物（不会提交）

Token、API 和本地数据

扩展只把浏览器当前捕获的 SharePoint 和 Graph bearer token 发给本机 bridge。token 会保存在本地运行时状态的 data/session.json 中；data/token-audit.json 和操作历史会去除 token 值，但整个 data/ 目录仍应按敏感数据处理，不能提交到 GitHub。

列表、列表项、列和现代页面优先使用 Graph token；在适用场景下可回退到 SharePoint REST v2。Drive/文件仍然只使用 Graph。站点组、权限、视图和格式化使用 SharePoint REST。SharePoint REST token 不会被冒充成 Graph token。

bridge 必须保持在 127.0.0.1，不要把端口转发、绑定到 0.0.0.0，也不要将 token 写入日志、Issue、截图或配置文件。

检查与真实站点测试

本地提交前运行：

npm run check

该命令包含 TypeScript 类型检查、测试和构建。真实站点脚本只用于维护者验证，会在 CN_BX_Site 创建带时间戳的持久测试对象，必须先获得明确的网站所有者批准：

$env:SHAREPOINT_MCP_REAL_SITE_SMOKE = 'true'
npm run test:real-site-list

Gallery 测试还需要明确批准的 SHAREPOINT_MCP_LIST_ID 和 SHAREPOINT_MCP_VIEW_ID。持久化 JSON 不等于 UI 已正确渲染，必须同时做 API readback 和 SharePoint UI 检查。

完整文档

• 安装与首次运行
• MCP 客户端配置
• 故障排查
• 架构与数据流
• 发布前检查
• 安全说明
• SharePoint 工具目录

Current Limits

• SharePoint Server、租户管理、Microsoft 365 group administration、classic ASPX、custom SPFx 和 unattended authentication 不支持。
• Modern-page 支持限制为 list、get、create、layout preview/apply 和 publish；不提供 page deletion 或 WebPart CRUD。
• Gallery JSON formatting 可以持久化为 view property，但必须在 SharePoint UI 中确认实际渲染效果。

---

English

A local MCP project that can be downloaded from GitHub. The Chromium extension captures session context from a signed-in SharePoint Online page, while the Node.js MCP server exposes supervised SharePoint operations through Microsoft Graph and SharePoint REST.

The project does not require an Entra app registration and does not upload tokens to the cloud. The MCP server, HTTP bridge, and runtime data run locally; the bridge listens only on http://127.0.0.1:17374.

Who is this for?

• Users who want to operate SharePoint Online from Claude Desktop, Cursor, VS Code, or another stdio-compatible MCP client.
• Teams that need to read or maintain lists, list items, view formatting, permissions, site groups, modern pages, and document-library files.
• Users who accept the local workflow of browser sign-in, a Chromium extension, and a local MCP server.

SharePoint Server (on-premises), tenant administration, unattended authentication, and arbitrary SPFx/DOM editing are out of scope.

5-minute installation

1. Download and build

On GitHub, choose Code → Download ZIP and extract it to a stable directory, or clone the repository with git clone. You need Node.js 20 or newer, plus Chrome or Edge.

From the project directory, run:

npm install
npm run build
npm run doctor

npm run build creates dist/server/index.js and dist/extension. Do not load the source directory directly; the extension must be loaded from the built directory.

2. Load the Chromium extension

1. Open edge://extensions or chrome://extensions.
2. Enable Developer mode.
3. Choose Load unpacked.
4. Select the project’s dist/extension folder.
5. Open or refresh the target SharePoint Online page.

The extension reads SharePoint/Graph request headers and sends short-lived tokens to the local bridge. Before installing, make sure the code comes from a GitHub repository you trust; see Security for the permission rationale.

3. Configure the MCP client

Your MCP client should launch the built stdio entry point, not an externally exposed HTTP service. Copy the Windows configuration example, replace the paths with your actual project path, and merge it into the client’s MCP configuration. See MCP client configuration for the full guide.

The essential Windows configuration is:

{
  "mcpServers": {
    "sharepoint-local": {
      "command": "node",
      "args": ["C:\\path\\to\\sharepoint-mcp\\dist\\server\\index.js"],
      "env": {
        "SHAREPOINT_MCP_DATA_DIR": "C:\\path\\to\\sharepoint-mcp\\data"
      }
    }
  }
}

Save the configuration and restart the MCP client. If an older server entry already exists, make sure it points to the current project’s dist/server/index.js.

First use

Run these steps in your MCP client:

1. get_health: confirm the local service and token-audience status.
2. list_captured_sites: review the SharePoint sites captured by the extension.
3. resolve_site: resolve the target site when a usable Graph or SharePoint REST token is available.
4. set_active_site, or set_active_site_from_tab when the current tab has already been resolved.
5. get_active_site: confirm the siteId and siteUrl again.
6. Run the required read or write tool.

Confirm the active-site lock before every write. Deletes, permission changes, updates, and formatting changes must use the matching preview_* tool first and apply only the returned previewId. The extension popup also shows the current site, connection state, operation history, and an optional automatic token-refresh setting.

Update, stop, and uninstall

After updating the source:

git pull
npm install
npm run build

Click Reload for dist/extension in the extension-management page and restart the MCP client. Stopping the MCP client stops the stdio service; if you started it manually with npm start, press Ctrl+C in that terminal.

To uninstall, remove the sharepoint-local entry from the MCP client first, then click Remove on the Chromium extension page. The data/ directory contains local session and history state; if it is no longer needed, delete it manually after confirming that no backup is required.

Project structure

extension/       Chromium MV3 extension source
server/          stdio MCP server, bridge, SharePoint API clients, and safety rules
scripts/         build, diagnostics, and real-site test scripts
tests/           unit and contract tests
skills/          SharePoint MCP safety guidance and tool catalog
docs/            user and maintainer documentation
examples/        MCP client configuration templates
data/            local runtime data (not committed)
dist/            build output (not committed)

Tokens, APIs, and local data

The extension sends captured SharePoint and Graph bearer tokens only to the local bridge. Tokens are stored in the local runtime state file data/session.json; data/token-audit.json and operation history remove token values, but the entire data/ directory must still be treated as sensitive and must not be committed to GitHub.

Lists, list items, columns, and modern pages prefer a Graph token and can fall back to SharePoint REST v2 where applicable. Drives and files remain Graph-only. Site groups, permissions, views, and formatting use SharePoint REST. A SharePoint REST token is never used as a Graph token.

Keep the bridge bound to 127.0.0.1. Do not forward the port, bind it to 0.0.0.0, or write tokens to logs, issues, screenshots, or configuration files.

Checks and real-site tests

Run this before submitting local changes:

npm run check

This runs TypeScript type checking, tests, and the build. Real-site scripts are for maintainers only. They create timestamped persistent test objects in CN_BX_Site and require explicit approval from the site owner:

$env:SHAREPOINT_MCP_REAL_SITE_SMOKE = 'true'
npm run test:real-site-list

The Gallery test also requires explicitly approved SHAREPOINT_MCP_LIST_ID and SHAREPOINT_MCP_VIEW_ID values. Persisted JSON is not proof that the UI rendered correctly; verify both API readback and the SharePoint UI.

Full documentation

• Installation and first run
• MCP client configuration
• Troubleshooting
• Architecture and data flow
• Release checklist
• Security
• SharePoint tool catalog

Current limits

• SharePoint Server, tenant administration, Microsoft 365 group administration, classic ASPX, custom SPFx, and unattended authentication are unsupported.
• Modern-page support is limited to list, get, create, layout preview/apply, and publish; page deletion and WebPart CRUD are not available.
• Gallery JSON formatting can be persisted as a view property, but the rendered result must be confirmed in the SharePoint UI.