mcp-sharepoint-cert 0.3.0
MCP Server to integrate with SharePoint
Requires Python: >=3.12

# SharePoint MCP Server (Certificate Auth)

[![PyPI version](https://badge.fury.io/py/mcp-sharepoint-cert.svg)](https://badge.fury.io/py/mcp-sharepoint-cert)
[![CI](https://github.com/peacockery-studio/mcp-sharepoint-cert/actions/workflows/ci.yml/badge.svg)](https://github.com/peacockery-studio/mcp-sharepoint-cert/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/peacockery-studio/mcp-sharepoint-cert/graph/badge.svg)](https://codecov.io/gh/peacockery-studio/mcp-sharepoint-cert)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

A comprehensive MCP Server for seamless integration with Microsoft SharePoint using **certificate-based authentication**. Enables MCP clients to interact with documents, folders and other SharePoint resources securely without client secrets.

## Quick Start

### 1. Install

Using uvx (recommended):

```bash
uvx mcp-sharepoint-cert
```

Or install with uv:

```bash
uv pip install mcp-sharepoint-cert
```

### 2. Run Interactive Setup

```bash
uvx mcp-sharepoint-cert-setup
```

The setup wizard will:
1. Generate a certificate for authentication
2. Guide you through Azure configuration
3. Collect your Azure app details
4. Ask which AI assistant you use (Claude Desktop, Claude Code, Cursor, Windsurf)
5. Output an **AI-ready prompt** that you paste into your assistant to finish configuration

The wizard generates `INSTALL_WITH_AI.md` - just paste it into your AI assistant and let it configure everything for you!

### 3. Configure Azure (One-time setup)

1. Go to [Azure Portal](https://portal.azure.com) → **App registrations** → **New registration**
2. Name it (e.g., `mcp-sharepoint`), click **Register**
3. Save the **Application (client) ID** and **Directory (tenant) ID**
4. Go to **Certificates & secrets** → **Certificates** → **Upload certificate**
   - Upload the `certs/sharepoint.crt` file generated by the setup command
5. Go to **API permissions** → **Add permission** → **SharePoint** → **Application permissions**
   - Add `Sites.FullControl.All` (or `Sites.ReadWrite.All` for read/write only)
   - Click **Grant admin consent**

### 4. Configure Your AI Assistant

The setup wizard outputs `INSTALL_WITH_AI.md` - paste this into your AI assistant (Claude, Cursor, etc.) and it will configure the MCP server for you automatically.

**Or configure manually** - create a `.env` file:

```env
SHP_ID_APP=your-application-client-id
SHP_TENANT_ID=your-directory-tenant-id
SHP_SITE_URL=https://your-tenant.sharepoint.com/sites/your-site
SHP_DOC_LIBRARY=Shared Documents
SHP_CERT_PATH=certs/sharepoint.pem
SHP_CERT_THUMBPRINT=your-certificate-thumbprint
```

### 5. Run (Standalone)

```bash
mcp-sharepoint-cert
```

You should see:
```
Connected to SharePoint: YourSiteName
MCP server ready - waiting for connections...
```

## Claude Desktop Integration

Add to your Claude Desktop config:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "sharepoint": {
      "command": "uvx",
      "args": ["mcp-sharepoint-cert"],
      "env": {
        "SHP_ID_APP": "your-app-id",
        "SHP_TENANT_ID": "your-tenant-id",
        "SHP_SITE_URL": "https://your-tenant.sharepoint.com/sites/your-site",
        "SHP_DOC_LIBRARY": "Shared Documents",
        "SHP_CERT_PATH": "/path/to/certs/sharepoint.pem",
        "SHP_CERT_THUMBPRINT": "your-thumbprint"
      }
    }
  }
}
```

## Available Tools

The server provides **14 tools** for complete SharePoint management:

### Folder Management
- **`List_SharePoint_Folders`** - List folders in a directory
- **`Create_Folder`** - Create new folders
- **`Delete_Folder`** - Delete empty folders
- **`Get_SharePoint_Tree`** - Get recursive folder structure

### Document Management
- **`List_SharePoint_Documents`** - List documents with metadata
- **`Get_Document_Content`** - Read document content (supports PDF, Word, Excel)
- **`Upload_Document`** - Upload new documents (text or binary)
- **`Upload_Document_From_Path`** - Upload from local filesystem
- **`Update_Document`** - Update existing documents
- **`Delete_Document`** - Remove documents
- **`Download_Document`** - Download to local filesystem

### Metadata Operations
- **`Get_File_Metadata`** - Get file metadata fields
- **`Update_File_Metadata`** - Update file metadata

## Content Processing

Intelligent content extraction for common file types:

- **PDF** - Full text extraction via PyMuPDF
- **Word (.docx)** - Paragraphs and tables
- **Excel (.xlsx)** - All sheets, first 50 rows each
- **Text files** - JSON, XML, HTML, MD, code files
- **Binary** - Base64 encoding for other types

## Environment Variables

### Required

| Variable | Description |
|----------|-------------|
| `SHP_ID_APP` | Azure AD application client ID |
| `SHP_TENANT_ID` | Microsoft tenant ID |
| `SHP_SITE_URL` | SharePoint site URL |
| `SHP_DOC_LIBRARY` | Document library path (default: `Shared Documents`) |
| `SHP_CERT_PATH` | Path to certificate PEM file |
| `SHP_CERT_THUMBPRINT` | Certificate thumbprint (SHA1) |

### Optional

| Variable | Default | Description |
|----------|---------|-------------|
| `SHP_MAX_DEPTH` | 15 | Max folder depth for tree operations |
| `SHP_MAX_FOLDERS_PER_LEVEL` | 100 | Max folders per level |
| `SHP_LEVEL_DELAY` | 0.5 | Delay between levels (seconds) |
| `SHP_BATCH_DELAY` | 0.1 | Delay between batches (seconds) |

## Development

### Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)

### Setup

```bash
git clone https://github.com/peacockery-studio/mcp-sharepoint-cert.git
cd mcp-sharepoint-cert
uv sync --group dev
```

### Run Locally

```bash
uv run mcp-sharepoint-cert
```

### Code Quality

```bash
uv run ruff check src/    # Lint
uv run ruff format src/   # Format
uv run ty check src/      # Type check
uv run pytest             # Tests
```

### Debugging with MCP Inspector

```bash
npx @modelcontextprotocol/inspector -- uv run mcp-sharepoint-cert
```

## Troubleshooting

### "Authentication failed" (401)

- Verify certificate is uploaded to Azure AD
- Check thumbprint matches
- Ensure certificate hasn't expired

### "Access denied" (403)

- Grant admin consent for API permissions
- Verify `Sites.FullControl.All` or `Sites.ReadWrite.All` is granted

### "Site not found" (404)

- Check `SHP_SITE_URL` is correct
- Verify site exists and is accessible

## License

MIT License - see [LICENSE](LICENSE) for details.

Copyright (c) 2025 Chieji Mofor