mcp-google-drive

MCP server for Google Drive integration - Read and list files from Google Drive with comprehensive search and navigation capabilities.

Overview

mcp-google-drive is a Model Context Protocol (MCP) server that enables Claude to interact with Google Drive. This server provides read-only access to files, folders, and drive metadata, making it perfect for document analysis, content search, and file organization tasks.

Features

Phase 1 (Current - v1.0.0)

• Drive Discovery: List and get information about shared drives
• File Operations: List, search, and read file contents
• Folder Navigation: Browse folder structures and hierarchies
• Permissions & Sharing: View file access and sharing settings
• Google Workspace Support: Read Google Docs, Sheets, and Slides

Coming in Phase 2

• File upload and creation
• Folder management
• Permission modifications
• File deletion and trash operations

Prerequisites

Before using this MCP server, you need:

1. Google Cloud Project: Create a project at console.cloud.google.com
2. Enable Google Drive API: Enable the Drive API in your project
3. OAuth 2.0 Credentials: Create OAuth credentials and obtain refresh token
4. Required Scopes:
   • https://www.googleapis.com/auth/drive.readonly
   • https://www.googleapis.com/auth/drive.metadata.readonly

Installation

NPM Installation (Recommended)

# Install globally
npm install -g @chinchillaenterprises/mcp-google-drive

# Or use with npx
npx @chinchillaenterprises/mcp-google-drive

Add to Claude

claude mcp add google-drive -s user \
  -e GOOGLE_CLIENT_ID=your-client-id \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -e GOOGLE_REFRESH_TOKEN=your-refresh-token \
  -- npx @chinchillaenterprises/mcp-google-drive

Local Development Installation

# Clone and build
cd mcp-google-drive
npm install
npm run build

# Add to Claude
claude mcp add google-drive-dev -s user \
  -e GOOGLE_CLIENT_ID=your-client-id \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -e GOOGLE_REFRESH_TOKEN=your-refresh-token \
  -- node /absolute/path/to/mcp-google-drive/dist/index.js

Manual Configuration

Edit your Claude configuration file:

{
  "mcpServers": {
    "google-drive": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@chinchillaenterprises/mcp-google-drive"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_CLIENT_ID | Yes | OAuth 2.0 client ID from Google Cloud Console | | GOOGLE_CLIENT_SECRET | Yes | OAuth 2.0 client secret | | GOOGLE_REFRESH_TOKEN | Yes | Long-lived refresh token for authentication |

Getting OAuth Credentials

1. Create OAuth 2.0 Client ID:

   • Go to Google Cloud Console
   • Navigate to APIs & Services > Credentials
   • Create OAuth 2.0 Client ID (Desktop application)

2. Get Refresh Token:

   # Use Google's OAuth playground or create a simple script
   # Scopes needed: drive.readonly, drive.metadata.readonly

3. Security Note: Keep your credentials secure and never commit them to version control

Available Tools

Drive Discovery

drive_list_drives

List all accessible shared drives.

Parameters:

• pageSize (optional): Maximum number of drives to return (default: 10)
• pageToken (optional): Page token for pagination

Example:

List all my shared drives
Show me the team drives I have access to

drive_get_drive_info

Get drive metadata and quota information.

Parameters:

• driveId (required): ID of the shared drive (use 'root' for My Drive)

Example:

Get info about my main drive
Show me the storage quota for drive ID abc123

File Operations

drive_list_files

List files with pagination and folder support.

Parameters:

• pageSize (optional): Maximum number of files to return (default: 20)
• pageToken (optional): Page token for pagination
• driveId (optional): Specific drive ID to list from
• orderBy (optional): Sort order (e.g., 'name', 'modifiedTime desc')

Example:

List all files in my drive
Show me the 10 most recently modified files
List files ordered by name

drive_get_file

Get file metadata by ID.

Parameters:

• fileId (required): Google Drive file ID

Example:

Get details for file ID xyz789
Show me metadata for this document

drive_search_files

Search files by name, type, or content.

Parameters:

• query (required): Search query (supports Drive query syntax)
• pageSize (optional): Maximum number of results (default: 20)
• pageToken (optional): Page token for pagination
• driveId (optional): Specific drive ID to search in

Example:

Search for files containing "project proposal"
Find all PDF files
Search for spreadsheets modified this week

Advanced Query Examples:

• name contains 'report' - Files with "report" in name
• mimeType = 'application/pdf' - Only PDF files
• modifiedTime > '2024-01-01' - Recently modified files
• '[email protected]' in owners - Files owned by specific user

drive_get_file_content

Read text file contents (docs, sheets, etc.).

Parameters:

• fileId (required): Google Drive file ID
• mimeType (optional): Export MIME type for Google Workspace files

Supported Export Types:

• Google Docs: text/plain, text/html, application/pdf
• Google Sheets: text/csv, application/pdf
• Google Slides: text/plain, application/pdf

Example:

Read the contents of document ID abc123
Get the text from this Google Doc
Export this spreadsheet as CSV

Folder Navigation

drive_list_folder_contents

List contents of a specific folder.

Parameters:

• folderId (required): Folder ID (use 'root' for root folder)
• pageSize (optional): Maximum number of items (default: 20)
• pageToken (optional): Page token for pagination

Example:

List files in the root folder
Show me what's in folder ID folder123
List contents of my Projects folder

drive_get_folder_tree

Get folder structure/hierarchy.

Parameters:

• folderId (optional): Starting folder ID (default: 'root')
• maxDepth (optional): Maximum depth to traverse (default: 3)

Example:

Show me my folder structure
Get the folder tree starting from Projects folder
Display folder hierarchy 2 levels deep

Permissions & Sharing

drive_list_permissions

List who has access to a file.

Parameters:

• fileId (required): File or folder ID

Example:

Show who has access to this document
List permissions for file ID abc123
Who can view this folder?

drive_get_sharing_info

Get sharing settings for a file.

Parameters:

• fileId (required): File or folder ID

Example:

Get sharing settings for this presentation
Show me how this file is shared
Is this document publicly accessible?

Usage Examples

Basic File Discovery

"List all my Google Drive files"
"Search for documents containing 'quarterly report'"
"Show me spreadsheets modified this month"

Folder Navigation

"Show me what's in my Projects folder"
"Get the folder structure of my drive"
"List all files in the Marketing folder"

Content Reading

"Read the contents of the meeting notes document"
"Get the text from the project proposal"
"Export the budget spreadsheet as CSV"

Permissions Audit

"Who has access to the financial reports folder?"
"Show me all publicly shared files"
"List files shared with external users"

File Type Support

Google Workspace Files

• Google Docs: Export as text, HTML, or PDF
• Google Sheets: Export as CSV, TSV, or PDF
• Google Slides: Export as text or PDF
• Google Drawings: Export as PNG, JPEG, or SVG

Regular Files

• Text files (.txt, .md, .csv)
• Documents (.pdf, .docx)
• Images (.jpg, .png, .gif)
• And all other Drive-supported formats

Troubleshooting

Common Issues

1. "Invalid credentials" error:

   • Verify your OAuth credentials are correct
   • Ensure refresh token hasn't expired
   • Check that required scopes are authorized

2. "File not found" error:

   • Verify the file ID is correct
   • Check that you have permission to access the file
   • Ensure the file hasn't been deleted

3. "Quota exceeded" error:

   • Google Drive API has usage quotas
   • Implement exponential backoff for retries
   • Consider caching frequently accessed data

4. Export format errors:

   • Not all formats support all export types
   • Use appropriate MIME types for Google Workspace files
   • Default to text/plain for maximum compatibility

Debug Mode

Run Claude with debug flag to see detailed logs:

claude --mcp-debug

Best Practices

1. Pagination: Always handle pagination for large result sets
2. Query Optimization: Use specific queries to reduce API calls
3. Error Handling: Implement proper error handling for network issues
4. Rate Limiting: Respect Google's API rate limits
5. Caching: Cache frequently accessed metadata when possible

Security Considerations

• Credential Storage: Never expose OAuth credentials
• Scope Limitation: Only request necessary scopes (read-only for v1)
• Access Audit: Regularly review file permissions
• Token Refresh: Implement automatic token refresh
• Data Privacy: Be mindful of sensitive document contents

Limitations (v1.0.0)

• Read-only access (no file modifications)
• No real-time collaboration features
• Limited to files user has access to
• Export size limits for large files
• No support for comments or revisions

Future Features (Phase 2)

• File Management: Upload, create, move, and delete files
• Folder Operations: Create and manage folders
• Permission Management: Modify sharing settings
• Advanced Features: Comments, revisions, and activities
• Batch Operations: Bulk file operations
• Watch for Changes: Real-time file change notifications

Development

Building from Source

# Clone the repository
git clone https://github.com/chinchillaenterprises/ChillMCP.git
cd ChillMCP/mcp-google-drive

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Testing

# Run with test credentials
GOOGLE_CLIENT_ID=test-id \
GOOGLE_CLIENT_SECRET=test-secret \
GOOGLE_REFRESH_TOKEN=test-token \
npm run dev

License

MIT License - see the parent repository for details.

Support

For issues and feature requests, please visit the ChillMCP repository.

Built with ❤️ by Chinchilla Enterprises