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