SharePoint MCP Server
MCP server for Microsoft SharePoint — manage folders, documents, and metadata.
Open source Open in the app JSON README (API)
About
MCP server for Microsoft SharePoint — manage folders, documents, and metadata.
Details
- Kind
- MCP servers
- Topic
- Productivity
- Publisher
- ravikant1918
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.1.1
- Stars
- 12
- Forks
- 4
- Last push
- 2026-03-15T11:30:25Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:16
- Updated
- 2026-08-29 04:01:16
- Origin id
io.github.ravikant1918/sharepoint-mcp
README
<div align="center">
<!-- mcp-name: io.github.ravikant1918/sharepoint-mcp -->
# 🗂️ sharepoint-mcp
### **The MCP Server that gives your AI agent a brain for Microsoft SharePoint**
[](https://github.com/ravikant1918/sharepoint-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/sharepoint-mcp/)
[](https://pypi.org/project/sharepoint-mcp/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/ravikant1918/sharepoint-mcp#-docker)
[](https://modelcontextprotocol.io)
A production-grade **Model Context Protocol (MCP) server** for **Microsoft SharePoint**.
Connect **Claude Desktop**, **VS Code Copilot**, **Cursor**, **Continue**, or any MCP-compatible AI agent
to your SharePoint — read files, manage folders, and reason over your organisation's knowledge.
[📚 Docs](docs/) · [🗺️ Roadmap](docs/roadmap.md) · [🐛 Bugs](https://github.com/ravikant1918/sharepoint-mcp/issues) · [💡 Features](https://github.com/ravikant1918/sharepoint-mcp/issues/new?template=feature_request.yml)
</div>
---
## 📑 Table of Contents
- [Why sharepoint-mcp?](#-why-sharepoint-mcp)
- [What Your Agent Can Do](#-what-your-agent-can-do)
- [Features](#-features)
- [Quickstart](#-quickstart)
- [Docker](#-docker)
- [Transport Modes](#-transport-modes)
- [Integrations](#-integrations) — Claude Desktop · VS Code Copilot · Cursor
- [All 14 Tools](#️-all-14-tools)
- [Configuration Reference](#️-full-configuration-reference)
- [Limitations](#️-limitations)
- [Troubleshooting](#-troubleshooting)
- [Development](#-development)
- [Documentation](#-documentation)
- [Contributing](#-contributing)
- [Security](#-security)
---
## 🧠 Why sharepoint-mcp?
> Most AI agents only know what's in their training data.
> **sharepoint-mcp** gives your agent _live access_ to your organisation's real knowledge.
| Without sharepoint-mcp | With sharepoint-mcp |
| ---------------------------------- | --------------------------------------- |
| 🤷 Agent guesses or hallucinates | Agent reads the actual document |
| 📋 You copy-paste content manually | Agent fetches files automatically |
| 🔒 Knowledge locked in SharePoint | Knowledge flows into your AI workflow |
| 🐌 Static, one-shot answers | Agent reasons, rewrites, and saves back |
---
## 🚀 What Your Agent Can Do
### 📖 Understand Any Document
```
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
```
### ✏️ Read → Reason → Write
```
You: "Translate the proposal to French and save it"
Agent: → Get_Document_Content → translate → Upload_Document
```
### 🗂️ Navigate Your Library
```
You: "What files are in the Legal/Contracts folder?"
Agent: → List_SharePoint_Documents("Legal/Contracts")
```
### 📊 Supported File Formats
| 📄 Format | 🤖 What the Agent Gets |
| -------------------------------------------- | ----------------------------- |
| **PDF** | Full text from every page |
| **Word** `.docx` `.doc` | Complete document content |
| **Excel** `.xlsx` `.xls` | All sheets as structured text |
| **Text, JSON, Markdown, HTML, YAML, Python** | Raw content as-is |
| **Images, ZIP, binaries** | File type + Base64 |
---
## ✨ Features
| | Feature | Description |
| --- | -------------------------- | ------------------------------------------------------ |
| 🔀 | **Dual API Support** | Choose Office365 REST or Microsoft Graph API |
| 📁 | **Folder Management** | List, create, delete, get full recursive tree |
| 📄 | **Document Management** | Upload, download, update, delete, search, read content |
| 🏷️ | **Metadata Management** | Read and update SharePoint list-item fields |
| 🔍 | **Smart Parsing** | Auto-detects PDF / Word / Excel / text |
| 🔎 | **KQL Search** | Native SharePoint KQL search for semantic file finding |
| 📂 | **Flexible Library Scope** | Scope to a subfolder or access the entire library root |
| 🔁 | **Auto-Retry** | Exponential backoff on SharePoint 429/503 throttling |
| 🚀 | **Dual Transport** | `stdio` for desktop · `http` for Docker/remote |
| 🪵 | **Structured Logging** | JSON in production · coloured console in dev |
| 🐳 | **Docker-Ready** | Single command: `docker compose up -d` |
| 🛡️ | **Non-Root Container** | Runs as unprivileged user inside Docker |
| 🩺 | **Health Check** | Live `/health` endpoint with real SharePoint check |
| 🤖 | **CI/CD** | Tested on Python 3.10 · 3.11 · 3.12 · 3.13 |
---
## ⚡ Quickstart
### 1️⃣ Install
```bash
pip install sharepoint-mcp
```
Or from source:
```bash
git clone https://github.com/ravikant1918/sharepoint-mcp.git
cd sharepoint-mcp && pip install -e .
```
### 2️⃣ Configure
```bash
cp .env.example .env
# Open .env and fill in your Azure AD credentials
```
```env
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
```
> 🔑 **New to Azure AD?** Follow the [step-by-step guide →](docs/azure-setup.md)
> 🔀 **Choose Your API**: SharePoint MCP supports both **Office365 REST API** (default) and **Microsoft Graph API**. See [API Configuration Guide →](docs/api-configuration.md)
#### Optional: Scope to a subfolder
By default, the server accesses your **entire document library root**. To restrict operations to a specific subfolder:
```env
# 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️⃣ Run
```bash
# 🔍 Interactive testing with MCP Inspector
npx @modelcontextprotocol/inspector -- sharepoint-mcp
# ▶️ Run directly
sharepoint-mcp
```
---
## 🐳 Docker
The fastest way to deploy for remote or cloud use.
### 📋 Usage Scenarios
#### Scenario A: Pull Latest Version from DockerHub (Recommended)
Use this for production deployments with the latest stable release:
```bash
# 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
```
**What happens:** Pulls `ravikant1918/sharepoint-mcp:latest` from DockerHub with automatic architecture detection (Intel/ARM).
---
#### Scenario B: Use Specific Version
Lock to a specific version for stability or testing:
```bash
# 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
```
**What happens:** Pulls `ravikant1918/sharepoint-mcp:v1.0.1` instead of `latest`.
---
#### Scenario C: Build Locally from Source
Use this for development or when you've made local code changes:
```bash
# 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
```
**What happens:** Builds image from local `Dockerfile`, tags as `ravikant1918/sharepoint-mcp:latest`, and starts container.
---
#### Scenario D: Use Custom Image/Fork
If you've forked the repo and published to your own DockerHub:
```bash
# 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
```
**What happens:** Pulls from your custom registry/repository.
---
### 🔧 Common Commands
```bash
# 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
```
> **Using Podman?** Just replace `docker` with `podman` — fully compatible.
### Docker Environment Variables
| Variable | Default | Description |
| ------------ | --------- | ------------------- |
| `TRANSPORT` | `http` | `stdio` or `http` |
| `HTTP_HOST` | `0.0.0.0` | Bind address |
| `HTTP_PORT` | `8000` | Port |
| `LOG_FORMAT` | `json` | `json` or `console` |
---
## 🔌 Transport Modes
| Mode | Best For | Set With |
| ------- | ---------------------------------------------------- | ----------------------------- |
| `stdio` | Claude Desktop, Cursor, MCP Inspector | `TRANSPORT=stdio` _(default)_ |
| `http` | Docker, remote agents, VS Code Copilot, REST clients | `TRANSPORT=http` |
---
## 🔗 Integrations
### 🤖 Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```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"
}
}
}
}
```
> 💡 Omit `SHP_DOC_LIBRARY` to access the full library root. If your org uses Office365 REST API and renamed the default library, also set `SHP_LIBRARY_NAME`.
### 💻 VS Code Copilot (Agent Mode)
1. Start the server via Docker or `TRANSPORT=http sharepoint-mcp`
2. Create `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"sharepoint": {
"url": "http://localhost:8000/mcp/",
"type": "http"
}
}
}
```
3. Open Copilot Chat → switch to **Agent mode** → your 14 SharePoint tools are available.
> ⚠️ **Trailing slash matters** — the URL must end with `/mcp/` (not `/mcp`).
### ⌨️ Cursor / Continue
Add to your MCP config (uses stdio transport):
```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"
}
}
}
}
```
---
## 🛠️ All 14 Tools
### 📁 Folder Management
| Tool | What It Does |
| ------------------------- | ---------------------------------------- |
| `List_SharePoint_Folders` | 📋 List all sub-folders in a directory |
| `Get_SharePoint_Tree` | 🌳 Get full recursive folder + file tree |
| `Create_Folder` | ➕ Create a new folder |
| `Delete_Folder` | 🗑️ Delete an empty folder |
### 📄 Document Management
| Tool | What It Does |
| --------------------------- | -------------------------------------------------- |
| `List_SharePoint_Documents` | 📋 List all files with metadata |
| `Search_SharePoint` | 🔎 Search documents using KQL queries |
| `Get_Document_Content` | 📖 Read & parse file content (PDF/Word/Excel/text) |
| `Upload_Document` | ⬆️ Upload file as string or Base64 |
| `Upload_Document_From_Path` | 📂 Upload a local file directly |
| `Update_Document` | ✏️ Overwrite existing file content |
| `Delete_Document` | 🗑️ Permanently delete a file |
| `Download_Document` | ⬇️ Download file to local filesystem |
### 🏷️ Metadata Management
| Tool | What It Does |
| ---------------------- | -------------------------------------- |
| `Get_File_Metadata` | 🔍 Get all SharePoint list-item fields |
| `Update_File_Metadata` | ✏️ Update metadata fields |
---
## ⚙️ Full Configuration Reference
| Variable | Required | Default | Description |
| --------------------------- | -------- | ------------------------ | ----------------------------------------------------------- |
| `SHP_ID_APP` | ✅ | | Azure AD app client ID |
| `SHP_ID_APP_SECRET` | ✅ | | Azure AD client secret |
| `SHP_TENANT_ID` | ✅ | | Microsoft tenant ID |
| `SHP_SITE_URL` | ✅ | | SharePoint site URL |
| `SHP_API_TYPE` | | `office365` | `office365`, `graph`, or `graphql` |
| `SHP_LIBRARY_NAME` | | `Shared Documents` | Library name (Office365 REST only; Graph auto-detects) |
| `SHP_DOC_LIBRARY` | | _(empty = full library)_ | Subfolder scope (e.g. `mcp_server`). Empty = entire library |
| `SHP_MAX_DEPTH` | | `15` | Max tree depth |
| `SHP_MAX_FOLDERS_PER_LEVEL` | | `100` | Folders per batch |
| `SHP_LEVEL_DELAY` | | `0.5` | Delay (s) between tree levels |
| `TRANSPORT` | | `stdio` | `stdio` or `http` |
| `HTTP_HOST` | | `0.0.0.0` | HTTP bind host |
| `HTTP_PORT` | | `8000` | HTTP port |
| `LOG_LEVEL` | | `INFO` | `DEBUG` `INFO` `WARNING` `ERROR` |
| `LOG_FORMAT` | | `console` | `console` or `json` |
---
## ⚠️ Limitations
| Limitation | Details |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| **Single site** | Connects to one SharePoint site per server instance (multi-site planned for v2.0) |
| **Sync client** | Uses synchronous SharePoint REST API calls (async client planned for v1.3) |
| **No sharing** | Cannot create sharing links yet (planned for v1.1) |
| **Large files** | Very large files may hit memory limits during content extraction |
| **Rate limits** | SharePoint throttling (429/503) is handled with auto-retry, but sustained bulk operations may be slow |
---
## 🔧 Troubleshooting
### Authentication Errors
**Problem:** `Missing or invalid SharePoint credentials`
**Solution:** Verify all 4 required environment variables are set:
```bash
echo $SHP_ID_APP $SHP_ID_APP_SECRET $SHP_TENANT_ID $SHP_SITE_URL
```
### Connection Issues (HTTP Transport)
**Problem:** Agent can't connect to the MCP server
**Solution:**
1. Ensure the server is running: `curl http://localhost:8000/mcp/`
2. Check the URL ends with `/mcp/` (trailing slash required)
3. Verify the port is not blocked by a firewall
### Docker Container Unhealthy
**Problem:** `podman ps` / `docker ps` shows `(unhealthy)`
**Solution:** Check container logs for errors:
```bash
docker logs sharepoint-mcp
```
### Debug Logging
Enable verbose output by setting `LOG_LEVEL=DEBUG`:
```bash
LOG_LEVEL=DEBUG sharepoint-mcp
```
For Docker, add to your `.env` file or `docker-compose.yml`:
```env
LOG_LEVEL=DEBUG
LOG_FORMAT=console
```
### Permission Errors
**Problem:** `Access denied` from SharePoint
**Solution:**
1. Verify the Azure AD app has the required API permissions
2. Ensure admin consent has been granted (if required by your org)
3. Confirm `SHP_SITE_URL` points to a site your app has access to
---
## 🧪 Development
```bash
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
```
---
## 📚 Documentation
| 📄 Doc | 📝 Description |
| --------------------------------------------- | ------------------------------- |
| [⚡ Getting Started](docs/getting-started.md) | Full setup guide |
| [⚙️ Configuration](docs/configuration.md) | All environment variables |
| [🛠️ Tools Reference](docs/tools-reference.md) | Detailed tool parameters |
| [🏛️ Architecture](docs/architecture.md) | Design and layer diagram |
| [🔑 Azure Setup](docs/azure-setup.md) | Azure AD app registration guide |
| [🗺️ Roadmap](docs/roadmap.md) | Planned features |
| [📅 Changelog](docs/changelog.md) | Version history |
---
## 🤝 Contributing
Contributions are welcome! Please read [docs/contributing.md](docs/contributing.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
1. 🍴 Fork the repo
2. 🌿 Create a branch: `git checkout -b feat/my-tool`
3. ✅ Add tests: `make test`
4. 📬 Open a Pull Request
---
## 🔒 Security
Found a vulnerability? Please **do not** open a public issue.
Report privately via [GitHub Security Advisories](https://github.com/ravikant1918/sharepoint-mcp/security/advisories/new) or see [SECURITY.md](SECURITY.md).
---
<div align="center">
**MIT License © 2026 [Ravi Kant](https://github.com/ravikant1918)**
⭐ If this project helps you, please star it on GitHub!
</div>