Sharepoint Mcp

---

📑 目录

• 为什么选择 sharepoint-mcp？
• 你的 Agent 能做什么
• 功能
• 快速开始
• Docker
• 传输模式
• 集成 — Claude Desktop · VS Code Copilot · Cursor
• 全部 14 个工具
• 配置参考
• 限制
• 故障排除
• 开发
• 文档
• 参与贡献
• 安全

---

🧠 为什么选择 sharepoint-mcp？

大多数 AI Agent 只了解训练数据中的内容。
sharepoint-mcp 让你的 Agent 实时访问 组织中的真实知识。

没有 sharepoint-mcp	使用 sharepoint-mcp
🤷 Agent 猜测或产生幻觉	Agent 读取实际文档
📋 你手动复制粘贴内容	Agent 自动获取文件
🔒 知识被锁在 SharePoint 中	知识融入你的 AI 工作流
🐌 回答静态且只能生成一次	Agent 进行推理、改写并保存结果

---

🚀 你的 Agent 能做什么

📖 理解任何文档

You: "Summarise the Q3 report in the Finance folder"
Agent: → Get_Document_Content("Finance", "Q3_Report.pdf")
       → Reads full extracted text
       → Returns a sharp, accurate summary

✏️ 读取 → 推理 → 写入

You: "Translate the proposal to French and save it"
Agent: → Get_Document_Content → translate → Upload_Document

🗂️ 浏览你的文档库

You: "What files are in the Legal/Contracts folder?"
Agent: → List_SharePoint_Documents("Legal/Contracts")

📊 支持的文件格式

📄 格式	🤖 Agent 获取的内容
PDF	每一页的完整文本
Word .docx .doc	完整文档内容
Excel .xlsx .xls	所有工作表的结构化文本
文本、JSON、Markdown、HTML、YAML、Python	原始内容
图片、ZIP、二进制文件	文件类型 + Base64

---

✨ 功能

	功能	描述
🔀	双 API 支持	可选择 Office365 REST 或 Microsoft Graph API
📁	文件夹管理	列出、创建、删除文件夹，并获取完整的递归树
📄	文档管理	上传、下载、更新、删除、搜索文档并读取内容
🏷️	元数据管理	读取和更新 SharePoint 列表项字段
🔍	智能解析	自动检测 PDF / Word / Excel / 文本
🔎	KQL 搜索	使用 SharePoint 原生 KQL 搜索语义相关文件
📂	灵活的库范围	可限定到子文件夹，也可访问整个库根目录
🔁	自动重试	遇到 SharePoint 429/503 限流时使用指数退避
🚀	双传输方式	stdio 用于桌面端 · http 用于 Docker/远程端
🪵	结构化日志	生产环境使用 JSON · 开发环境使用彩色控制台输出
🐳	支持 Docker	一条命令即可运行：docker compose up -d
🛡️	非 Root 容器	在 Docker 内以非特权用户运行
🩺	运行状况检查	提供实时 /health 端点，并检查 SharePoint 状态
🤖	CI/CD	已在 Python 3.10 · 3.11 · 3.12 · 3.13 上测试

---

⚡ 快速开始

1️⃣ 安装

pip install sharepoint-mcp

或从源代码安装：

git clone https://github.com/ravikant1918/sharepoint-mcp.git
cd sharepoint-mcp && pip install -e .

2️⃣ 配置

cp .env.example .env
# Open .env and fill in your Azure AD credentials

SHP_ID_APP=your-azure-app-client-id
SHP_ID_APP_SECRET=your-azure-app-secret
SHP_TENANT_ID=your-tenant-id
SHP_SITE_URL=https://your-tenant.sharepoint.com/sites/your-site
SHP_API_TYPE=office365   # or "graph" / "graphql" for Microsoft Graph API

🔑 刚开始使用 Azure AD？ 请参阅分步指南 →
🔀 选择 API：SharePoint MCP 同时支持 Office365 REST API（默认）和 Microsoft Graph API。请参阅 API 配置指南 →

可选：限定到子文件夹

默认情况下，服务可访问整个文档库根目录。若要将操作限制在特定子文件夹中：

# Only operate within this subfolder (omit for full library access)
SHP_DOC_LIBRARY=mcp_server

# Library name (only needed if your org renamed "Shared Documents")
# Graph API auto-detects the default drive — this is only for Office365 REST API
# SHP_LIBRARY_NAME=Shared Documents

3️⃣ 运行

# 🔍 Interactive testing with MCP Inspector
npx @modelcontextprotocol/inspector -- sharepoint-mcp

# ▶️ Run directly
sharepoint-mcp

---

🐳 Docker

远程或云端部署最快捷的方式。

📋 使用场景

场景 A：从 DockerHub 拉取最新版本（推荐）

用于使用最新稳定版本进行生产部署：

# Step 1: Clone repository
git clone https://github.com/ravikant1918/sharepoint-mcp.git
cd sharepoint-mcp

# Step 2: Create .env file with your SharePoint credentials
cp .env.example .env
# Edit .env and fill in:
# SHP_ID_APP=your-app-id
# SHP_ID_APP_SECRET=your-secret
# SHP_TENANT_ID=your-tenant-id
# SHP_SITE_URL=https://yourcompany.sharepoint.com/sites/yoursite

# Step 3: Start container (pulls from DockerHub automatically)
docker compose up -d

# Step 4: Verify it's running
docker compose ps
curl http://localhost:8000/health

# View logs
docker compose logs -f

# Stop container
docker compose down

执行效果： 从 DockerHub 拉取 ravikant1918/sharepoint-mcp:latest，并自动检测架构（Intel/ARM）。

---

场景 B：使用指定版本

为确保稳定性或进行测试，固定使用某个版本：

# Step 1: Set version via environment variable
SHAREPOINT_MCP_VERSION=v1.0.1 docker compose up -d

# Or add to .env file
echo "SHAREPOINT_MCP_VERSION=v1.0.1" >> .env
docker compose up -d

执行效果： 拉取 ravikant1918/sharepoint-mcp:v1.0.1，而非 latest。

---

场景 C：从源代码在本地构建

用于开发或本地修改了代码的情况：

# Step 1: Clone and setup
git clone https://github.com/ravikant1918/sharepoint-mcp.git
cd sharepoint-mcp
cp .env.example .env
# Edit .env with your credentials

# Step 2: Build from local Dockerfile and start
docker compose up -d --build

# Step 3: Rebuild after code changes
docker compose down
docker compose up -d --build

执行效果： 使用本地 Dockerfile 构建镜像，将其标记为 ravikant1918/sharepoint-mcp:latest，并启动容器。

---

场景 D：使用自定义镜像/分支

如果你已分叉此仓库并发布到自己的 DockerHub：

# Use your custom image
SHAREPOINT_MCP_IMAGE=myusername/sharepoint-mcp \
SHAREPOINT_MCP_VERSION=dev \
docker compose up -d

# Or add to .env
echo "SHAREPOINT_MCP_IMAGE=myusername/sharepoint-mcp" >> .env
echo "SHAREPOINT_MCP_VERSION=dev" >> .env
docker compose up -d

执行效果： 从你的自定义注册表/仓库拉取镜像。

---

🔧 常用命令

# Start in detached mode
docker compose up -d

# Start with live logs
docker compose up

# View logs
docker compose logs -f

# Stop container
docker compose down

# Restart container
docker compose restart

# Pull latest image
docker compose pull

# Rebuild and restart
docker compose up -d --build

# Remove everything (including volumes)
docker compose down -v

使用 Podman？ 只需将 docker 替换为 podman，两者完全兼容。

Docker 环境变量

变量	默认值	描述
TRANSPORT	http	stdio 或 http
HTTP_HOST	0.0.0.0	绑定地址
HTTP_PORT	8000	端口
LOG_FORMAT	json	json 或 console

---

🔌 传输模式

模式	适用场景	设置方式
stdio	Claude Desktop、Cursor、MCP Inspector	TRANSPORT=stdio (默认)
http	Docker、远程 Agent、VS Code Copilot、REST 客户端	TRANSPORT=http

---

🔗 集成

🤖 Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "sharepoint": {
      "command": "sharepoint-mcp",
      "env": {
        "SHP_ID_APP": "your-app-id",
        "SHP_ID_APP_SECRET": "your-app-secret",
        "SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
        "SHP_TENANT_ID": "your-tenant-id",
        "SHP_DOC_LIBRARY": "my-subfolder"
      }
    }
  }
}

💡 省略 SHP_DOC_LIBRARY 即可访问整个库的根目录。如果你的组织使用 Office365 REST API 并重命名了默认库，也请设置 SHP_LIBRARY_NAME。

💻 VS Code Copilot（Agent 模式）

1. 通过 Docker 或 TRANSPORT=http sharepoint-mcp 启动服务
2. 在工作区中创建 .vscode/mcp.json：

{
  "servers": {
    "sharepoint": {
      "url": "http://localhost:8000/mcp/",
      "type": "http"
    }
  }
}

3. 打开 Copilot Chat → 切换到 Agent 模式 → 即可使用 14 个 SharePoint 工具。

⚠️ 末尾的斜杠很重要——URL 必须以 /mcp/ 结尾（不能是 /mcp）。

⌨️ Cursor / Continue

添加到 MCP 配置中（使用 stdio 传输）：

{
  "mcpServers": {
    "sharepoint": {
      "command": "sharepoint-mcp",
      "env": {
        "SHP_ID_APP": "your-app-id",
        "SHP_ID_APP_SECRET": "your-app-secret",
        "SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
        "SHP_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

---

🛠️ 全部 14 个工具

📁 文件夹管理

工具	功能
List_SharePoint_Folders	📋 列出目录中的所有子文件夹
Get_SharePoint_Tree	🌳 获取完整的递归文件夹和文件树
Create_Folder	➕ 创建新文件夹
Delete_Folder	🗑️ 删除空文件夹

📄 文档管理

工具	功能
List_SharePoint_Documents	📋 列出所有文件及其元数据
Search_SharePoint	🔎 使用 KQL 查询搜索文档
Get_Document_Content	📖 读取并解析文件内容（PDF/Word/Excel/文本）
Upload_Document	⬆️ 以字符串或 Base64 上传文件
Upload_Document_From_Path	📂 直接上传本地文件
Update_Document	✏️ 覆盖现有文件内容
Delete_Document	🗑️ 永久删除文件
Download_Document	⬇️ 将文件下载到本地文件系统

🏷️ 元数据管理

工具	功能
Get_File_Metadata	🔍 获取所有 SharePoint 列表项字段
Update_File_Metadata	✏️ 更新元数据字段

---

⚙️ 完整配置参考

变量	必需	默认值	说明
SHP_ID_APP	✅		Azure AD 应用客户端 ID
SHP_ID_APP_SECRET	✅		Azure AD 客户端密钥
SHP_TENANT_ID	✅		Microsoft 租户 ID
SHP_SITE_URL	✅		SharePoint 站点 URL
SHP_API_TYPE		office365	office365、graph 或 graphql
SHP_LIBRARY_NAME		Shared Documents	库名称（仅限 Office365 REST；Graph 会自动检测）
SHP_DOC_LIBRARY		(empty = full library)	子文件夹范围（例如 mcp_server）。留空表示整个库
SHP_MAX_DEPTH		15	最大树深度
SHP_MAX_FOLDERS_PER_LEVEL		100	每批文件夹数
SHP_LEVEL_DELAY		0.5	树层级之间的延迟（秒）
TRANSPORT		stdio	stdio 或 http
HTTP_HOST		0.0.0.0	HTTP 绑定主机
HTTP_PORT		8000	HTTP 端口
LOG_LEVEL		INFO	DEBUG INFO WARNING ERROR
LOG_FORMAT		console	console 或 json

---

⚠️ 限制

限制	详情
单个站点	每个服务实例仅连接一个 SharePoint 站点（计划在 v2.0 中支持多站点）
同步客户端	使用同步 SharePoint REST API 调用（计划在 v1.3 中提供异步客户端）
不支持共享	暂时无法创建共享链接（计划在 v1.1 中支持）
大文件	提取内容时，非常大的文件可能会触及内存限制
速率限制	SharePoint 限流（429/503）会通过自动重试处理，但持续的批量操作可能较慢

---

🔧 故障排除

身份验证错误

问题： Missing or invalid SharePoint credentials
解决方案： 确认已设置所有 4 个必需的环境变量：

echo $SHP_ID_APP $SHP_ID_APP_SECRET $SHP_TENANT_ID $SHP_SITE_URL

连接问题（HTTP 传输）

问题： Agent 无法连接到 MCP 服务
解决方案：

1. 确保服务正在运行：curl http://localhost:8000/mcp/
2. 检查 URL 是否以 /mcp/ 结尾（必须带末尾斜杠）
3. 确认端口未被防火墙阻止

Docker 容器状态不健康

问题： podman ps / docker ps 显示 (unhealthy)
解决方案： 检查容器日志中的错误：

docker logs sharepoint-mcp

调试日志

设置 LOG_LEVEL=DEBUG 以启用详细输出：

LOG_LEVEL=DEBUG sharepoint-mcp

对于 Docker，将其添加到 .env 文件或 docker-compose.yml 中：

LOG_LEVEL=DEBUG
LOG_FORMAT=console

权限错误

问题： SharePoint 返回 Access denied
解决方案：

1. 验证 Azure AD 应用具有所需的 API 权限
2. 确保已授予管理员同意（如果组织要求）
3. 确认 SHP_SITE_URL 指向应用有权访问的站点

---

🧪 开发

git clone https://github.com/ravikant1918/sharepoint-mcp.git
cd sharepoint-mcp
pip install -e ".[dev]"

make test      # run all tests
make inspect   # 🔍 launch MCP Inspector
make check     # quick import sanity check
make clean     # 🧹 remove caches

---

📚 文档

📄 文档	📝 描述
⚡ 入门指南	完整的设置指南
⚙️ 配置	所有环境变量
🛠️ 工具参考	详细的工具参数
🏛️ 架构	设计和分层图
🔑 Azure 设置	Azure AD 应用注册指南
🗺️ 路线图	计划中的功能
📅 更新日志	版本历史

---

🤝 参与贡献

欢迎贡献！请阅读 docs/contributing.md 和我们的行为准则。

1. 🍴 Fork 此仓库
2. 🌿 创建分支：git checkout -b feat/my-tool
3. ✅ 添加测试：make test
4. 📬 发起拉取请求

---

🔒 安全

发现漏洞？请不要公开提交 issue。
请通过 GitHub Security Advisories 私下报告，或参阅 SECURITY.md。

---