Google Drive MCP Server

# Troubleshooting Guide This guide helps you diagnose and resolve common issues with the Google Drive MCP Server. ## Quick Diagnostics ### Health Check Commands ```bash # Check server status npx google-drive-mcp health # Test authentication npx google-drive-mcp test auth # Validate configuration npx google-drive-mcp config validate # Check cache status npx google-drive-mcp cache status ``` ### Log Analysis ```bash # View recent logs npx google-drive-mcp logs --tail 50 # View error logs only npx google-drive-mcp logs --level error # Enable debug logging export LOG_LEVEL=debug npm start ``` ## Authentication Issues ### Problem: "Authentication failed" or "Invalid credentials" **Symptoms:** - Server fails to start with auth errors - "Invalid client" error messages - OAuth flow doesn't complete **Solutions:** 1. **Verify Credentials File:** ```bash # Check if credentials.json exists and is valid cat credentials.json | jq . ``` 2. **Check OAuth Configuration:** - Ensure redirect URIs are configured correctly - Verify client ID and secret match your Google Cloud project - Confirm OAuth consent screen is properly set up 3. **Re-authenticate:** ```bash # Clear existing tokens rm -rf ~/.google-drive-mcp/tokens # Run auth wizard again npx google-drive-mcp auth setup ``` 4. **Verify API Access:** - Check that Google Drive API is enabled in Google Cloud Console - Ensure your account has access to the OAuth app - Verify you're added as a test user (for external apps) ### Problem: "Token expired" or "Refresh token invalid" **Symptoms:** - Server works initially but fails after some time - "Token has been expired or revoked" errors **Solutions:** 1. **Refresh Tokens:** ```bash # Force token refresh npx google-drive-mcp auth refresh ``` 2. **Check Token Storage:** ```bash # Verify token files exist and are readable ls -la ~/.google-drive-mcp/tokens/ ``` 3. **Re-authenticate if Refresh Fails:** ```bash # Clear and re-authenticate npx google-drive-mcp auth reset npx google-drive-mcp auth setup ``` ## File Processing Issues ### Problem: "Unsupported file format" or Processing Errors **Symptoms:** - Files fail to process or convert - "MIME type not supported" errors - Incomplete content extraction **Solutions:** 1. **Check Supported Formats:** ```bash # List supported MIME types npx google-drive-mcp info formats ``` 2. **Verify File Accessibility:** ```bash # Test file access npx google-drive-mcp test file --id "your-file-id" ``` 3. **Check File Size:** ```bash # Files larger than MAX_FILE_SIZE will be rejected echo $MAX_FILE_SIZE ``` 4. **Debug Processing Pipeline:** ```bash # Enable debug logging for content processing export LOG_LEVEL=debug export DEBUG_CONTENT_PROCESSING=true npm start ``` ### Problem: PDF Processing Fails **Symptoms:** - PDF files don't extract text properly - "PDF parsing error" messages **Solutions:** 1. **Check PDF Dependencies:** ```bash # Verify pdf-parse is installed npm list pdf-parse ``` 2. **Test with Simple PDF:** - Try with a text-based PDF first - Scanned PDFs (images) won't work without OCR 3. **Check PDF Permissions:** - Some PDFs have copy protection that prevents text extraction ### Problem: Google Docs Processing Issues **Symptoms:** - Google Docs don't convert properly - Missing formatting or content **Solutions:** 1. **Verify Google Docs API Access:** ```bash # Check if Google Docs API is enabled npx google-drive-mcp test docs-api ``` 2. **Check Document Permissions:** - Ensure you have read access to the document - Verify the document isn't restricted 3. **Test Export Formats:** ```bash # Try different export formats npx google-drive-mcp export --file-id "doc-id" --format markdown ``` ## Cache Issues ### Problem: Cache Errors or Performance Issues **Symptoms:** - "Cache write failed" errors - Slow performance despite caching - Disk space issues **Solutions:** 1. **Check Cache Directory:** ```bash # Verify cache directory exists and is writable ls -la ./cache/ df -h ./cache/ ``` 2. **Clear Cache:** ```bash # Clear all cached files npx google-drive-mcp cache clear # Clear specific file cache npx google-drive-mcp cache clear --file-id "your-file-id" ``` 3. **Check Cache Configuration:** ```bash # View cache settings npx google-drive-mcp config show cache ``` 4. **Monitor Cache Usage:** ```bash # Check cache statistics npx google-drive-mcp cache stats ``` ## Network and API Issues ### Problem: "Rate limit exceeded" or API Quota Issues **Symptoms:** - "Quota exceeded" errors - Slow API responses - Temporary failures **Solutions:** 1. **Check Current Usage:** - Visit Google Cloud Console → APIs & Services → Dashboard - Review quota usage and limits 2. **Implement Backoff:** ```bash # The server should automatically retry with backoff # Check retry configuration npx google-drive-mcp config show retry ``` 3. **Request Quota Increase:** - Go to Google Cloud Console → APIs & Services → Quotas - Request increases for your project ### Problem: Network Connectivity Issues **Symptoms:** - "Network error" or timeout messages - Intermittent failures **Solutions:** 1. **Test Connectivity:** ```bash # Test Google API connectivity curl -I https://www.googleapis.com/drive/v3/about # Test with authentication npx google-drive-mcp test connectivity ``` 2. **Check Firewall/Proxy:** - Ensure outbound HTTPS (443) is allowed - Configure proxy settings if needed: ```bash export HTTPS_PROXY=http://your-proxy:port ``` 3. **Adjust Timeouts:** ```json // In config.json { "server": { "requestTimeout": 60000 // Increase timeout } } ``` ## MCP Protocol Issues ### Problem: MCP Client Connection Issues **Symptoms:** - MCP client can't connect to server - Tool calls fail or timeout **Solutions:** 1. **Verify Server is Running:** ```bash # Check if server is listening netstat -an | grep :3000 ``` 2. **Test MCP Protocol:** ```bash # Test MCP tool calls directly npx google-drive-mcp test mcp ``` 3. **Check MCP Client Configuration:** - Verify client is pointing to correct server address - Ensure environment variables are set correctly ### Problem: Tool Call Failures **Symptoms:** - Specific MCP tools return errors - Inconsistent tool behavior **Solutions:** 1. **Test Individual Tools:** ```bash # Test each tool separately npx google-drive-mcp test tool drive_search_files npx google-drive-mcp test tool drive_get_file ``` 2. **Check Tool Parameters:** - Verify required parameters are provided - Check parameter types and formats 3. **Review Tool Logs:** ```bash # Enable tool-specific logging export DEBUG_MCP_TOOLS=true npm start ``` ## Performance Issues ### Problem: Slow File Processing **Symptoms:** - Long delays when processing files - High memory usage - Server becomes unresponsive **Solutions:** 1. **Monitor Resource Usage:** ```bash # Check memory and CPU usage top -p $(pgrep -f "google-drive-mcp") ``` 2. **Optimize Cache Settings:** ```json // Reduce cache size if memory is limited { "cache": { "maxSize": "500MB", "cleanupInterval": 60 } } ``` 3. **Process Files in Chunks:** ```bash # Use smaller chunk sizes for large files npx google-drive-mcp content --file-id "id" --chunk-size 2000 ``` 4. **Limit Concurrent Operations:** ```json // In config.json { "processing": { "maxConcurrentFiles": 3 } } ``` ## Configuration Issues ### Problem: Configuration Not Loading **Symptoms:** - Server uses default settings despite config file - Environment variables ignored **Solutions:** 1. **Verify Config File Location:** ```bash # Check if config.json exists in project root ls -la config.json ``` 2. **Validate JSON Syntax:** ```bash # Check for JSON syntax errors cat config.json | jq . ``` 3. **Check Environment Variable Priority:** ```bash # Environment variables override config file env | grep GOOGLE_ ``` 4. **Use Config Validation:** ```bash # Validate configuration npx google-drive-mcp config validate ``` ## Getting Help ### Collect Diagnostic Information Before seeking help, collect this information: ```bash # System information node --version npm --version uname -a # Server information npx google-drive-mcp --version npx google-drive-mcp config show # Recent logs npx google-drive-mcp logs --tail 100 > debug.log ``` ### Support Channels 1. **GitHub Issues**: Report bugs and feature requests 2. **Documentation**: Check the latest docs for updates 3. **Community**: Join discussions in project forums ### Debug Mode For detailed troubleshooting, run in debug mode: ```bash export LOG_LEVEL=debug export DEBUG_AUTH=true export DEBUG_CACHE=true export DEBUG_CONTENT_PROCESSING=true export DEBUG_MCP_TOOLS=true npm start ``` This will provide verbose logging for all components.