🧠 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 | |---|---|---| | 📁 | Folder Management | List, create, delete, get full recursive tree | | 📄 | Document Management | Upload, download, update, delete, read content | | 🏷️ | Metadata Management | Read and update SharePoint list-item fields | | 🔍 | Smart Parsing | Auto-detects PDF / Word / Excel / text | | 🔁 | 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 | | 🤖 | 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

🔑 New to Azure AD? Follow the step-by-step guide →

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:

cp .env.example .env        # fill in your credentials
docker compose up -d        # start HTTP server on port 8000
curl http://localhost:8000/health

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, REST clients | TRANSPORT=http |

🤖 Claude Desktop Integration

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": "Shared Documents/your-folder"
      }
    }
  }
}

🛠️ All 12 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 | | 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 | required | — | Azure AD app client ID | | SHP_ID_APP_SECRET | required | — | Azure AD client secret | | SHP_TENANT_ID | required | — | Microsoft tenant ID | | SHP_SITE_URL | required | — | SharePoint site URL | | SHP_DOC_LIBRARY | | Shared Documents/mcp_server | Library path | | 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 |

🧪 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.