SharePoint MCP Server

# Troubleshooting Guide Common issues and solutions for the SharePoint MCP server. ## Authentication Issues ### Browser Doesn't Open **Symptoms**: When authentication is needed, no browser window opens. **Possible Causes**: 1. Port 8765 is already in use 2. Firewall blocking localhost connections 3. No default browser configured **Solutions**: 1. **Check if port is in use**: ```bash # macOS/Linux lsof -i :8765 # Windows netstat -ano | findstr :8765 ``` If the port is in use, configure a different port (see [Azure Setup Guide](azure-setup.md#custom-redirect-port)) 2. **Manually open the URL**: - Check the MCP server logs for the authentication URL - Copy and paste it into your browser manually 3. **Verify your redirect URI**: - Ensure it matches exactly in Azure AD and your configuration - Default: `http://localhost:8765/callback` ### Authentication Timeout **Symptoms**: "Authentication timed out or was cancelled" **Cause**: You didn't complete the authentication within 2 minutes. **Solution**: 1. Try the command again in Claude 2. Complete the browser authentication more quickly 3. If you need more time, you can modify the timeout in `auth.py` (search for `server.timeout`) ### Token Refresh Failed **Symptoms**: "Token refresh failed" in logs, need to re-authenticate frequently **Possible Causes**: 1. Refresh token has expired (90 days by default) 2. Azure AD policy changes 3. User password changed **Solutions**: 1. Clear stored tokens and re-authenticate: ```bash # macOS/Linux python3 -c "import keyring; keyring.delete_password('sharepoint-mcp', 'YOUR_CLIENT_ID')" ``` 2. Check Azure AD conditional access policies 3. Re-authenticate through Claude ### "Invalid client" Error **Symptoms**: AADSTS7000215 or "Invalid client secret" **Cause**: Using client secret authentication (not supported). **Solution**: 1. This MCP server uses **public client flows**, not client secrets 2. Ensure "Allow public client flows" is enabled in Azure AD 3. Remove any client secrets from your configuration ## Permission Issues ### "Insufficient privileges" **Symptoms**: Can list sites but can't access files, or "Access denied" errors **Possible Causes**: 1. Missing Microsoft Graph API permissions 2. Admin consent not granted 3. User doesn't have access to the SharePoint site **Solutions**: 1. **Verify API permissions**: - Go to Azure AD → App registrations → Your app → API permissions - Ensure these are present: - Sites.Read.All - Files.ReadWrite.All - User.Read - offline_access 2. **Grant admin consent**: - If you see "Not granted for [Organization]", admin consent is needed - Click "Grant admin consent" (requires admin rights) - Or ask your IT administrator 3. **Check SharePoint permissions**: - Verify you can access the site directly at sharepoint.com - You need at least read access to view files - You need contribute access to upload files ### "Consent required" **Symptoms**: "AADSTS65001: The user or administrator has not consented" **Cause**: User or admin hasn't approved the permissions. **Solution**: 1. The first authentication should prompt for consent 2. Clear tokens and re-authenticate to trigger consent prompt 3. If admin consent is required, contact your IT administrator ## Configuration Issues ### "Missing configuration" **Symptoms**: ConfigurationError: Missing configuration **Cause**: `AZURE_CLIENT_ID` and `AZURE_TENANT_ID` not set. **Solutions**: 1. **For Claude Desktop**, ensure your config file has the env vars: ```json { "mcpServers": { "sharepoint": { "command": "uvx", "args": ["sharepoint-mcp"], "env": { "AZURE_CLIENT_ID": "your-client-id", "AZURE_TENANT_ID": "your-tenant-id" } } } } ``` 2. **For Claude Code**, set environment variables or create config file 3. **Verify the values**: - Client ID should be a GUID (e.g., `12345678-1234-1234-1234-123456789abc`) - Tenant ID should also be a GUID - No extra spaces or quotes ### "Invalid tenant" **Symptoms**: AADSTS90002 or "Tenant not found" **Cause**: Wrong tenant ID. **Solution**: 1. Go to Azure AD → Overview 2. Copy the **Directory (tenant) ID** exactly 3. Update your configuration 4. Restart Claude Desktop ## Connection Issues ### "Connection refused" or timeout **Symptoms**: Can't connect to Microsoft Graph API **Possible Causes**: 1. No internet connection 2. Corporate firewall blocking Microsoft endpoints 3. Proxy configuration needed **Solutions**: 1. **Test connectivity**: ```bash curl https://graph.microsoft.com/v1.0/ ``` 2. **Check proxy settings**: - If behind a corporate proxy, you may need to configure httpx - Set `HTTP_PROXY` and `HTTPS_PROXY` environment variables 3. **Verify firewall**: - Ensure access to `*.microsoft.com` and `*.microsoftonline.com` ### "Rate limited" **Symptoms**: "Rate limited, waiting 5s" in logs, slow responses **Cause**: Making too many requests to Graph API. **Solution**: - The client automatically retries with backoff - If persistent, reduce the frequency of requests - Consider increasing pagination limits to reduce number of calls ## File Operation Issues ### "File too large" **Symptoms**: "File too large (X bytes). Max: 10485760" **Cause**: File exceeds 10MB limit. **Solutions**: 1. **For downloads**: The limit is set in `graph.py` (`MAX_FILE_SIZE`) 2. **For uploads**: Use the Microsoft Graph large file upload API (not currently implemented) 3. **Workaround**: Download/upload files manually and provide Claude with summaries ### "File not found" **Symptoms**: 404 error when trying to access a file **Possible Causes**: 1. File was deleted or moved 2. Incorrect file_id or site_id 3. Permissions changed **Solutions**: 1. Use `search_files` to find the current location 2. Use `list_files` to browse and get correct IDs 3. Verify you still have access to the file ### Upload fails with 409 conflict **Symptoms**: "An item with this name already exists" **Cause**: File with the same name exists at the destination. **Solutions**: 1. Use a different file name 2. Delete the existing file first (not automated - do manually) 3. Add a timestamp to the filename for uniqueness ## Debug Mode ### Enable detailed logging Add `LOG_LEVEL: DEBUG` to your MCP configuration: ```json { "mcpServers": { "sharepoint": { "command": "uvx", "args": ["sharepoint-mcp"], "env": { "AZURE_CLIENT_ID": "...", "AZURE_TENANT_ID": "...", "LOG_LEVEL": "DEBUG" } } } } ``` Restart Claude Desktop and check the logs: **macOS**: `~/Library/Logs/Claude/mcp-server-sharepoint.log` **Windows**: `%APPDATA%\Claude\Logs\mcp-server-sharepoint.log` **Linux**: `~/.local/state/Claude/logs/mcp-server-sharepoint.log` ### Test the MCP server standalone Run the server directly to see detailed output: ```bash # Set environment variables export AZURE_CLIENT_ID="your-client-id" export AZURE_TENANT_ID="your-tenant-id" export LOG_LEVEL="DEBUG" # Run the server uvx sharepoint-mcp # Or if you have the repo: uv run sharepoint-mcp ``` The server will output logs to stderr, which you can review for errors. ## Platform-Specific Issues ### macOS Keychain Access **Symptoms**: "Failed to load token from keyring" or keychain prompts **Solutions**: 1. Grant keychain access when prompted 2. If keychain is locked, unlock it 3. Reset keychain access: ```bash security delete-generic-password -s "sharepoint-mcp" -a "YOUR_CLIENT_ID" ``` ### Windows Credential Manager **Symptoms**: Can't store or retrieve tokens **Solutions**: 1. Open Credential Manager (Control Panel → Credential Manager) 2. Look for "sharepoint-mcp" entries under Generic Credentials 3. Delete any corrupted entries 4. Re-authenticate ### Linux Secret Service **Symptoms**: "No keyring backend available" **Solutions**: 1. Install a keyring backend: ```bash # For GNOME sudo apt install gnome-keyring # For KDE sudo apt install kwalletmanager ``` 2. Or use file-based storage (less secure): ```bash pip install keyrings.alt ``` ## Getting Help If you're still experiencing issues: 1. **Check the logs** with `LOG_LEVEL=DEBUG` 2. **Search existing issues** on [GitHub Issues](https://github.com/yourusername/sharepoint-mcp/issues) 3. **Create a new issue** with: - Description of the problem - Steps to reproduce - Relevant log excerpts (remove sensitive info) - Your platform (macOS/Windows/Linux) - Python version (`python --version`) ## Common Error Codes | Error Code | Meaning | Solution | |------------|---------|----------| | AADSTS50076 | MFA required | Complete MFA in browser | | AADSTS50079 | User password expired | Reset password | | AADSTS65001 | No consent | Grant permissions | | AADSTS70011 | Invalid scope | Check API permissions | | AADSTS90002 | Invalid tenant | Verify tenant ID | | AADSTS500113 | Invalid redirect URI | Check Azure AD configuration | ## Resetting Everything If all else fails, start fresh: 1. **Clear stored tokens**: ```bash # macOS/Linux python3 -c "import keyring; keyring.delete_password('sharepoint-mcp', 'YOUR_CLIENT_ID')" ``` 2. **Delete config file** (if using file-based config): ```bash rm ~/.config/sharepoint-mcp/config.json ``` 3. **Restart Claude Desktop** 4. **Try a simple command**: "List my SharePoint sites" 5. **Complete authentication** in the browser This should give you a fresh start.