# 🗂️ sharepoint-mcp ### **The MCP Server that gives your AI agent a brain for Microsoft SharePoint** [![CI](https://github.com/ravikant1918/sharepoint-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ravikant1918/sharepoint-mcp/actions/workflows/ci.yml) [![PyPI version](https://img.shields.io/pypi/v/sharepoint-mcp.svg)](https://pypi.org/project/sharepoint-mcp/) [![Python](https://img.shields.io/pypi/pyversions/sharepoint-mcp.svg)](https://pypi.org/project/sharepoint-mcp/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white)](https://github.com/ravikant1918/sharepoint-mcp#-docker) [![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet)](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)

--- ## 📑 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). ---

**MIT License © 2026 [Ravi Kant](https://github.com/ravikant1918)** ⭐ If this project helps you, please star it on GitHub!