MCP Google Drive Server

# 🛠️ Troubleshooting Guide *Don't worry! Most issues have simple solutions. Let's get you back on track.* ## 🚨 Common Issues & Solutions ### 1. "Node.js is not recognized" or "node: command not found" **Problem:** Node.js isn't installed or not in your system PATH. **Solution:** 1. Download Node.js from [nodejs.org](https://nodejs.org/) (get the LTS version) 2. Install it with default settings 3. **Restart your terminal/command prompt** 4. Test: `node --version` **Still not working?** - On Windows: Make sure you checked "Add to PATH" during installation - Try restarting your computer - Reinstall Node.js with administrator privileges --- ### 2. "Cannot find module" errors **Problem:** Dependencies aren't installed. **Solution:** ```bash cd your-project-folder npm install ``` **If that doesn't work:** ```bash # Delete node_modules and try again rm -rf node_modules package-lock.json # On Mac/Linux # OR on Windows: delete the node_modules folder manually npm install ``` --- ### 3. "Permission denied" or "Access denied" errors **Problem:** The service account doesn't have permission to access your Google Drive folders. **Solution:** 1. Open Google Drive in your web browser 2. Find the folder you want to access 3. Right-click → "Share" 4. Add this email: `mcp-drive-service@scientific-axle-461106-f3.iam.gserviceaccount.com` 5. Set permission to "Editor" (recommended) 6. Click "Send" **Double-check:** - You shared the correct folder - You used the exact service account email - You didn't accidentally revoke the sharing --- ### 4. Claude doesn't see the MCP server **Problem:** Claude Desktop can't find or connect to your MCP server. **Solution checklist:** - ✅ **Correct path**: The path in your config file points to the actual `server.js` file - ✅ **Restarted Claude**: You completely quit and reopened Claude Desktop - ✅ **Valid JSON**: Your config file has proper JSON formatting - ✅ **File exists**: The `server.js` file exists at the specified path **How to fix the path:** 1. Navigate to your project folder 2. Right-click on `server.js` 3. Copy the full path 4. Update your Claude config file with this exact path **Config file locations:** - Windows: `%APPDATA%\Claude\claude_desktop_config.json` - Mac: `~/Library/Application Support/Claude/claude_desktop_config.json` --- ### 5. "Service account file not found" **Problem:** The `service-account.json` file is missing or in the wrong location. **Solution:** 1. **Get the file**: Contact us for the `service-account.json` file 2. **Place it correctly**: Put it in the same folder as `package.json` 3. **Check the name**: File must be named exactly `service-account.json` **Alternative solution** (if you want to create your own): Follow the [Technical Guide](TECHNICAL-GUIDE.md) to create your own service account. --- ### 6. "Authentication failed" or "Invalid credentials" **Problem:** There's an issue with your authentication setup. **Solutions:** **For Service Account users:** 1. Make sure `service-account.json` is in the correct location 2. Verify the file isn't corrupted (should be valid JSON) 3. Check that the service account has the right permissions **For OAuth users:** 1. Run `node auth.js` to refresh your authentication 2. Follow the browser prompts to re-authorize 3. Make sure `credentials.json` and `token.json` exist --- ### 7. "API not enabled" errors **Problem:** Google Drive API isn't enabled for your project. **Solution:** 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 2. Navigate to "APIs & Services" → "Library" 3. Search for "Google Drive API" 4. Click "Enable" *Note: This usually only affects people creating their own service accounts.* --- ### 8. Files not appearing or "No files found" **Problem:** The search isn't finding your files. **Possible causes & solutions:** **Files in Trash:** - The server excludes trashed files by default - Check your Google Drive trash and restore files if needed **Wrong folder:** - Make sure you're searching in the right folder - Try searching without specifying a folder first **Permission issues:** - Verify the service account has access to the folders containing your files - Check if files are in shared drives (may need special permissions) **Search syntax:** - Use simple search terms first: `"document"` - Try searching by file type: `mimeType="application/pdf"` --- ### 9. "Server crashed" or connection lost **Problem:** The MCP server stops working unexpectedly. **Solution:** 1. **Check the terminal**: Look for error messages in your terminal/command prompt 2. **Restart the server**: Close Claude, restart your terminal, restart Claude 3. **Check for updates**: Make sure you have the latest version 4. **Check system resources**: Close other heavy applications **If it keeps crashing:** - Run `node debug-test.js` to check your setup - Check our [GitHub Issues](https://github.com/your-username/mcp-google-drive-server/issues) for similar problems --- ### 10. Slow performance or timeouts **Problem:** Requests take too long or time out. **Solutions:** - **Large files**: Very large files take longer to process - **Many files**: Reduce the `maxResults` in your queries - **Internet connection**: Check your network speed - **Google API limits**: You might be hitting rate limits (wait a few minutes) --- ## 🔍 Debug Commands Use these commands to diagnose issues: ```bash # Test basic setup node test.js # Test authentication node debug-test.js # Check if files exist ls -la # Mac/Linux dir # Windows # Check Node.js and npm versions node --version npm --version ``` ## 📱 Platform-Specific Issues ### Windows Users - **Path separators**: Use forward slashes `/` in config paths, not backslashes `\` - **Permissions**: Run Command Prompt as Administrator if you get permission errors - **Antivirus**: Some antivirus software blocks Node.js - add an exception ### Mac Users - **Hidden files**: Use `Command + Shift + .` to show hidden files in Finder - **Permissions**: You might need to grant terminal permissions in System Preferences - **Xcode tools**: Install Xcode command line tools if you get compilation errors ### Linux Users - **Package manager**: You might need to install Node.js through your package manager - **Permissions**: Use `sudo` carefully, and prefer npm global installs in user directory ## 🆘 Still Stuck? ### Before asking for help, please: 1. ✅ Try the solutions above 2. ✅ Run the debug commands 3. ✅ Check our [FAQ](FAQ.md) 4. ✅ Search existing [GitHub Issues](https://github.com/your-username/mcp-google-drive-server/issues) ### When asking for help, include: - **Your operating system** (Windows 10, macOS Big Sur, etc.) - **Node.js version** (`node --version`) - **Exact error message** (copy and paste) - **What you were trying to do** - **Steps you've already tried** ### Get help: - 💬 [Create a GitHub Issue](https://github.com/your-username/mcp-google-drive-server/issues/new) - 📧 Email: support@yourproject.com - 💻 Discord community (link in main README) ## 💡 Prevention Tips - **Keep backups**: Don't modify the original files until you're comfortable - **Test small**: Start with a few files before connecting your entire Drive - **Read updates**: Check our releases for important updates and bug fixes - **Stay updated**: Keep Node.js and dependencies up to date **Remember: Every expert was once a beginner. You've got this! 💪**