Metadata-Version: 2.4
Name: mcp-sharepoint-cert
Version: 0.2.1
Summary: MCP Server to integrate with SharePoint
Project-URL: Homepage, https://github.com/peacockery-studio/mcp-sharepoint-cert
Project-URL: Repository, https://github.com/peacockery-studio/mcp-sharepoint-cert
Project-URL: Issues, https://github.com/peacockery-studio/mcp-sharepoint-cert/issues
Author-email: Chi Ejimofor <chi@peacockery.studio>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: mcp>=1.2.1
Requires-Dist: office365-rest-python-client>=2.6.1
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pymupdf>=1.23.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# 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. Create Azure App & Certificate

```bash
# Generate certificate for authentication
uvx mcp-sharepoint-cert-setup
# Or if installed: mcp-sharepoint-cert-setup
```

This creates a certificate and shows you exactly what to do next.

### 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 Environment

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

```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
