Google Drive MCP Server

AI-powered Google Drive integration through Model Context Protocol (MCP) providing intelligent file management, content analysis, and organization insights.

🚀 Features

Core MCP Tools

• list_files - List files and folders with advanced filtering and pagination
• get_file_content - Extract and retrieve file content with metadata
• search_files - Full-text search with relevance scoring and filtering
• analyze_content - AI-powered content analysis with summarization and categorization
• get_organization_insights - Drive organization analysis with actionable recommendations

Key Capabilities

• 🔐 Secure OAuth2 Authentication with Google Drive API
• 📊 Content Analysis - AI-powered summarization, categorization, and keyword extraction
• 🔍 Advanced Search - Full-text search with relevance scoring and filtering
• 📁 Organization Insights - Duplicate detection and structure optimization
• ⚡ Performance Optimized - Intelligent caching and rate limiting
• 🛡️ Production Ready - Comprehensive error handling and logging

📋 Prerequisites

• Node.js 18.0.0 or higher
• Google Cloud Project with Drive API enabled
• OAuth2 Credentials from Google Cloud Console

🛠️ Installation

1. Clone and Install Dependencies

git clone <repository-url>
cd gdrive-sparc-mcp
npm install

2. Google Cloud Setup

1. Create Google Cloud Project

   • Go to Google Cloud Console
   • Create a new project or select existing one

2. Enable Google Drive API

   # Using gcloud CLI
   gcloud services enable drive.googleapis.com
   

3. Create OAuth2 Credentials

   • Navigate to APIs & Services > Credentials
   • Click "Create Credentials" > "OAuth 2.0 Client IDs"
   • Application type: "Web application"
   • Add authorized redirect URI: http://localhost:3000/auth/callback
   • Download credentials JSON

3. Environment Configuration

Create .env file from template:

cp .env.example .env

Configure required environment variables:

# Google OAuth Configuration (Required)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback

# Session Configuration (Required)
SESSION_SECRET=your-secure-session-secret-at-least-32-characters

# Optional Configuration
NODE_ENV=production
LOG_LEVEL=info
CACHE_TTL=300
CACHE_MAX_SIZE=1000
RATE_LIMIT_WINDOW=60000
RATE_LIMIT_MAX_REQUESTS=100

4. Build and Start

# Build TypeScript
npm run build

# Start server
npm start

# Or for development
npm run dev

🔧 Configuration

Environment Variables

Variable	Required	Default	Description
GOOGLE_CLIENT_ID	✅	-	Google OAuth2 Client ID
GOOGLE_CLIENT_SECRET	✅	-	Google OAuth2 Client Secret
GOOGLE_REDIRECT_URI	✅	-	OAuth2 Redirect URI
SESSION_SECRET	✅	-	Session encryption secret (32+ chars)
NODE_ENV	❌	development	Environment mode
LOG_LEVEL	❌	info	Logging level (error, warn, info, debug)
CACHE_TTL	❌	300	Cache TTL in seconds
CACHE_MAX_SIZE	❌	1000	Maximum cache entries
RATE_LIMIT_WINDOW	❌	60000	Rate limit window (ms)
RATE_LIMIT_MAX_REQUESTS	❌	100	Max requests per window

Google Drive API Scopes

The server requests the following OAuth2 scopes:

• https://www.googleapis.com/auth/drive.readonly - Read access to Google Drive files
• https://www.googleapis.com/auth/userinfo.profile - Basic profile information

📖 Usage

MCP Client Integration

Add to your MCP client configuration:

{
  "mcpServers": {
    "gdrive-sparc-mcp": {
      "command": "node",
      "args": ["path/to/gdrive-sparc-mcp/dist/server.js"]
    }
  }
}

Tool Examples

List Files

{
  "name": "list_files",
  "arguments": {
    "folderId": "optional-folder-id",
    "recursive": true,
    "maxResults": 50,
    "orderBy": "modifiedTime"
  }
}

Search Files

{
  "name": "search_files",
  "arguments": {
    "query": "project proposal",
    "filters": {
      "mimeTypes": ["application/pdf", "application/vnd.google-apps.document"]
    },
    "options": {
      "maxResults": 20,
      "includeSnippets": true
    }
  }
}

Analyze Content

{
  "name": "analyze_content",
  "arguments": {
    "fileIds": ["file-id-1", "file-id-2"],
    "analysisOptions": {
      "enableSummarization": true,
      "enableCategorization": true,
      "enableKeywordExtraction": true
    }
  }
}

Get Organization Insights

{
  "name": "get_organization_insights",
  "arguments": {
    "scope": {
      "folderId": "optional-folder-id",
      "includeSubfolders": true,
      "fileLimit": 1000
    },
    "analysisOptions": {
      "enableDuplicateDetection": true,
      "enableStructureAnalysis": true
    }
  }
}

🧪 Testing

Run Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suite
npm test -- tests/auth/auth-service.test.ts

# Run integration tests
npm test -- tests/integration/

Test Server

Test the MCP server functionality:

# Test server startup and tool listing
node test-server.js

🚀 Deployment

Docker Deployment

1. Build Docker Image

   docker build -t gdrive-sparc-mcp .
   

2. Run Container

   docker run -d \
     --name gdrive-mcp \
     -p 3000:3000 \
     --env-file .env \
     gdrive-sparc-mcp
   

Production Deployment

1. Environment Setup

   # Set production environment
   export NODE_ENV=production
   export LOG_LEVEL=warn
   
   # Configure production secrets
   export SESSION_SECRET="your-production-session-secret"
   export GOOGLE_CLIENT_ID="your-production-client-id"
   export GOOGLE_CLIENT_SECRET="your-production-client-secret"
   

2. Process Management

   # Using PM2
   npm install -g pm2
   pm2 start dist/server.js --name gdrive-mcp
   pm2 save
   pm2 startup
   

3. Health Monitoring

   # Check server health
   curl -X POST http://localhost:3000 \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   

🔍 Monitoring and Logging

Log Levels

• error - Error conditions only
• warn - Warning and error conditions
• info - Informational, warning, and error messages (default)
• debug - All messages including debug information

Performance Metrics

• Request/response times
• Cache hit/miss ratios
• Rate limiting statistics
• Authentication success/failure rates

Health Checks

• Configuration validation
• Google API connectivity
• Cache system status
• Memory and performance metrics

🛡️ Security

Authentication

• Secure OAuth2 flow with Google
• Session-based authentication
• Automatic token refresh
• Secure credential storage

Data Protection

• No persistent storage of user data
• Encrypted session management
• Rate limiting and abuse prevention
• Input validation and sanitization

Best Practices

• Regular security updates
• Environment variable protection
• Secure communication (HTTPS in production)
• Audit logging for security events

🐛 Troubleshooting

Common Issues

Configuration Errors

# Check configuration validation
npm run build && node dist/server.js

Authentication Issues

• Verify Google Cloud credentials
• Check OAuth2 redirect URI configuration
• Ensure Drive API is enabled

Performance Issues

• Monitor cache hit rates
• Check rate limiting settings
• Review log levels and output

Connection Issues

• Verify network connectivity
• Check firewall settings
• Validate environment variables

Debug Mode

# Enable debug logging
export LOG_LEVEL=debug
npm start

Support

• Check documentation
• Review troubleshooting guide
• Submit issues on GitHub

📚 Documentation

• Functional Requirements
• Domain Model
• API Specifications
• Implementation Architecture
• Testing and Deployment

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol for the MCP specification
• Google Drive API for file access capabilities
• SPARC Development Team for the development methodology

---

Version: 1.0.0
Last Updated: 2025-01-30
Maintainer: SPARC Development Team