SharePoint MCP Server

# SharePoint MCP Server A production-ready Model Context Protocol (MCP) server for Microsoft SharePoint integration. Enables Claude Desktop and Claude Code to interact with SharePoint sites, document libraries, and files via the Microsoft Graph API. ## Features - **Site Management**: List and browse SharePoint sites - **File Operations**: Browse, search, upload, and download files - **Document Libraries**: Access and manage document libraries - **Sharing**: Create sharing links for files - **Search**: Full-text search across SharePoint - **Lists**: Read and create SharePoint list items - **OAuth Authentication**: Secure browser-based login with automatic token refresh - **Structured Output**: All responses use Pydantic models for type safety ## Available Tools | Tool | Description | |------|-------------| | `list_sites` | List SharePoint sites you have access to | | `list_libraries` | Get document libraries for a site | | `list_files` | Browse files in a library/folder (with pagination) | | `search_files` | Search files across SharePoint | | `get_file_content` | Download and read file content | | `upload_file` | Upload a file to a library | | `get_file_metadata` | Get detailed file metadata | | `create_sharing_link` | Generate a sharing link for a file | | `list_items` | Get items from a SharePoint list | | `create_list_item` | Add an item to a SharePoint list | ## Quick Start ### Prerequisites 1. **Python 3.11+** and **uv** package manager ```bash # Install uv if you don't have it curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. **Azure AD App Registration** (see [Azure Setup Guide](docs/azure-setup.md)) - Client ID - Tenant ID - Required permissions: Sites.Read.All, Files.ReadWrite.All, User.Read, offline_access - Redirect URI: `http://localhost:8765/callback` ### Installation #### Option A: Using uvx (Recommended for End Users) Add to your Claude Desktop config at `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "sharepoint": { "command": "uvx", "args": ["sharepoint-mcp"], "env": { "AZURE_CLIENT_ID": "your-azure-app-client-id", "AZURE_TENANT_ID": "your-azure-tenant-id" } } } } ``` Restart Claude Desktop. The first time you use a SharePoint command, a browser window will open for authentication. #### Option B: Using uv --directory (For Development) Clone this repository and add to your Claude Desktop config: ```json { "mcpServers": { "sharepoint": { "command": "uv", "args": ["--directory", "/path/to/sharepoint-mcp", "run", "sharepoint-mcp"], "env": { "AZURE_CLIENT_ID": "your-azure-app-client-id", "AZURE_TENANT_ID": "your-azure-tenant-id" } } } } ``` #### Option C: Using Claude Code ```bash # Add to Claude Code's MCP configuration claude mcp add sharepoint -- uvx sharepoint-mcp # Or manually edit ~/.claude/claude_code_config.json ``` ### First Run 1. Open Claude Desktop and ask: "List my SharePoint sites" 2. A browser window will open automatically 3. Sign in with your Microsoft account 4. Grant the requested permissions 5. Return to Claude - you're authenticated! Tokens are securely stored in your OS keychain and refreshed automatically. ## Configuration ### Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `AZURE_CLIENT_ID` | Yes | Azure AD application client ID | | `AZURE_TENANT_ID` | Yes | Azure AD tenant ID | | `REDIRECT_URI` | No | OAuth redirect URI (default: `http://localhost:8765/callback`) | | `LOG_LEVEL` | No | Logging level (default: `INFO`) | ### Config File (Alternative) Create `~/.config/sharepoint-mcp/config.json`: ```json { "client_id": "your-azure-app-client-id", "tenant_id": "your-azure-tenant-id", "redirect_uri": "http://localhost:8765/callback", "log_level": "INFO" } ``` ## Usage Examples ### Browse Files ``` "Show me the files in my Marketing site's Documents library" ``` The assistant will: 1. Call `list_sites` with search="Marketing" 2. Call `list_libraries` for that site 3. Call `list_files` for the Documents library 4. Show you the file list ### Search for a Document ``` "Find all PDFs related to Q4 reports" ``` The assistant will call `search_files` with query="Q4 reports filetype:pdf" ### Upload a File ``` "Upload this content to the Projects library in my main SharePoint site as 'proposal.txt'" ``` The assistant will: 1. Find the site and library 2. Call `upload_file` with the content 3. Confirm the upload ### Create a Sharing Link ``` "Create a view-only link for the budget.xlsx file that expires in 7 days" ``` The assistant will: 1. Search for or browse to the file 2. Call `create_sharing_link` with link_type="view" and expiration_days=7 3. Return the shareable URL ## Azure AD App Setup You need to register an application in Azure AD to use this MCP server. See the detailed guide: [docs/azure-setup.md](docs/azure-setup.md) **Quick summary:** 1. Go to [Azure Portal](https://portal.azure.com) → Azure Active Directory → App registrations 2. Create a new registration: - Name: "SharePoint MCP Server" - Supported account types: "Accounts in this organizational directory only" - Redirect URI: Web → `http://localhost:8765/callback` 3. Add API permissions: - Microsoft Graph → Delegated permissions: - `Sites.Read.All` - `Files.ReadWrite.All` - `User.Read` - `offline_access` - Grant admin consent (if required) 4. Authentication → Enable "Allow public client flows" 5. Copy the Client ID and Tenant ID for your configuration ## Development ### Setup ```bash # Clone the repository git clone https://github.com/yourusername/sharepoint-mcp.git cd sharepoint-mcp # Install with dev dependencies uv sync --dev # Run tests uv run pytest # Type checking uv run mypy src # Linting uv run ruff check src ``` ### Project Structure ``` sharepoint-mcp/ ├── src/sharepoint_mcp/ │ ├── __init__.py # Entry point │ ├── server.py # FastMCP server with all tools │ ├── auth.py # OAuth authentication │ ├── graph.py # Microsoft Graph API client │ ├── config.py # Configuration management │ └── models/ # Pydantic models │ ├── site.py │ ├── file.py │ └── list_item.py ├── tests/ # Test suite ├── docs/ # Documentation └── pyproject.toml # Project configuration ``` ### Testing ```bash # Run all tests uv run pytest # Run with coverage uv run pytest --cov=sharepoint_mcp --cov-report=html # Run specific test file uv run pytest tests/test_server.py ``` ## Troubleshooting ### Authentication Issues **Problem**: "Missing configuration" error **Solution**: Ensure you've set `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` environment variables in your MCP config. --- **Problem**: Browser doesn't open for authentication **Solution**: The server starts a local web server on port 8765. Ensure this port isn't blocked by a firewall. --- **Problem**: "Authentication timed out" **Solution**: Complete the authentication within 2 minutes. If you miss the window, try the command again. ### Re-authentication To clear stored tokens and re-authenticate: ```bash # macOS/Linux python -c "import keyring; keyring.delete_password('sharepoint-mcp', 'YOUR_CLIENT_ID')" # Or use the Python keyring CLI keyring del sharepoint-mcp YOUR_CLIENT_ID ``` Then restart Claude Desktop and try a SharePoint command again. ### Permission Errors **Problem**: "Access denied" or "Insufficient permissions" **Solution**: 1. Verify the Azure AD app has the required permissions 2. Ensure admin consent has been granted (if required by your organization) 3. Check that your Microsoft account has access to the SharePoint site/file ### Debug Logging Enable debug logging by setting `LOG_LEVEL=DEBUG` in your MCP config: ```json { "mcpServers": { "sharepoint": { "command": "uvx", "args": ["sharepoint-mcp"], "env": { "AZURE_CLIENT_ID": "...", "AZURE_TENANT_ID": "...", "LOG_LEVEL": "DEBUG" } } } } ``` Check logs at: - **macOS**: `~/Library/Logs/Claude/mcp-server-sharepoint.log` - **Windows**: `%APPDATA%\Claude\Logs\mcp-server-sharepoint.log` ## Limitations - **File size**: Downloads limited to 10MB (configurable in code) - **Pagination**: List operations return up to 200 items per page (use cursor for more) - **Search**: Uses Microsoft Search, results depend on indexing - **Rate limiting**: Graph API has rate limits; the client implements automatic retry with backoff ## Security - **OAuth tokens** are stored securely in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) - **No passwords** are stored - only temporary OAuth tokens - **Automatic refresh** - access tokens are refreshed automatically before expiration - **Local callback server** - runs only during authentication, binds to localhost only ## Contributing Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Add tests for new functionality 4. Ensure all tests pass and type checking succeeds 5. Submit a pull request ## License MIT License - see [LICENSE](LICENSE) for details ## Support - **Issues**: [GitHub Issues](https://github.com/yourusername/sharepoint-mcp/issues) - **Discussions**: [GitHub Discussions](https://github.com/yourusername/sharepoint-mcp/discussions) - **Documentation**: [docs/](docs/) ## Acknowledgments Built with: - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - FastMCP framework - [MSAL](https://github.com/AzureAD/microsoft-authentication-library-for-python) - Microsoft Authentication Library - [httpx](https://www.python-httpx.org/) - Async HTTP client - [Pydantic](https://docs.pydantic.dev/) - Data validation