SharePoint MCP Server

Official

by ravikant1918 · Python

MCP server for Microsoft SharePoint — manage folders, documents, and metadata.

Manage Microsoft SharePoint folders, documents, and metadata programmatically.

README.md20 KBView on GitHub

🗂️ sharepoint-mcp

The MCP Server that gives your AI agent a brain for Microsoft SharePoint

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 · 🗺️ Roadmap · 🐛 Bugs · 💡 Features

</div>

📑 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

code

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

code

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

🗂️ Navigate Your Library

code

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 →
🔀 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:

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)

Start the server via Docker or TRANSPORT=http sharepoint-mcp
Create .vscode/mcp.json in your workspace:

json

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

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:

Ensure the server is running: curl http://localhost:8000/mcp/
Check the URL ends with /mcp/ (trailing slash required)
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:

Verify the Azure AD app has the required API permissions
Ensure admin consent has been granted (if required by your org)
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	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.

🍴 Fork the repo
🌿 Create a branch: git checkout -b feat/my-tool
✅ Add tests: make test
📬 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.

⭐ If this project helps you, please star it on GitHub!

</div>

Install

Configuration

Environment variables

SHP_ID_APPrequired

Azure AD application (client) ID

SHP_ID_APP_SECRETrequiredsecret

Azure AD client secret

SHP_TENANT_IDrequired

Microsoft Entra (Azure AD) tenant ID

SHP_SITE_URLrequired

SharePoint site URL (e.g. https://tenant.sharepoint.com/sites/MySite)

SHP_DOC_LIBRARYdefault Shared Documents/mcp_server

SharePoint document library path

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "sharepoint-mcp": {
      "command": "uvx",
      "args": [
        "sharepoint-mcp"
      ],
      "env": {
        "SHP_ID_APP": "<YOUR_SHP_ID_APP>",
        "SHP_ID_APP_SECRET": "<YOUR_SHP_ID_APP_SECRET>",
        "SHP_TENANT_ID": "<YOUR_SHP_TENANT_ID>",
        "SHP_SITE_URL": "<YOUR_SHP_SITE_URL>",
        "SHP_DOC_LIBRARY": "Shared Documents/mcp_server"
      }
    }
  }
}