---

📑 Table of Contents

• Why sharepoint-mcp?
• What Your Agent Can Do
• Features
• Quickstart
• Docker
• Transport Modes
• Integrations — Claude Desktop · VS Code Copilot · Cursor
• All 14 Tools
• Configuration Reference
• Limitations
• Troubleshooting
• Development
• Documentation
• Contributing
• 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

pip install sharepoint-mcp

Or from source:

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

2️⃣ Configure

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

🔑 New to Azure AD? Follow the step-by-step guide →
🔀 Choose Your API: SharePoint MCP supports both Office365 REST API (default) and Microsoft Graph API. See API Configuration Guide →

Optional: Scope to a subfolder

By default, the server accesses your entire document library root. To restrict operations to a specific subfolder:

# 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

# 🔍 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:

# 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:

# 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:

# 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:

# 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

# 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:

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

{
  "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):

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

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:

docker logs sharepoint-mcp

Debug Logging

Enable verbose output by setting LOG_LEVEL=DEBUG:

LOG_LEVEL=DEBUG sharepoint-mcp

For Docker, add to your .env file or docker-compose.yml:

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

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	Full setup guide
⚙️ Configuration	All environment variables
🛠️ Tools Reference	Detailed tool parameters
🏛️ Architecture	Design and layer diagram
🔑 Azure Setup	Azure AD app registration guide
🗺️ Roadmap	Planned features
📅 Changelog	Version history

---

🤝 Contributing

Contributions are welcome! Please read docs/contributing.md and our Code of Conduct.

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 or see SECURITY.md.

---