jayeshchowdary/gdrive-mcp

Google Drive MCP Server

A Model Context Protocol (MCP) server for Google Drive integration using FastMCP.

Quick Start

This project uses uv for dependency management and virtual environment handling.

Prerequisites

• Python 3.13 or higher
• uv package manager
• Google Cloud Console credentials

Installation

1. Clone or download this repository
2. Install dependencies using uv:

   uv sync
   

Configuration

1. Download your Google Cloud Console credentials JSON file
2. Place it as credentials.json in the project root
3. The server will automatically create a .token.json file for OAuth tokens

Running the Server

Use the provided run script:

./run_server.sh

Or run directly with uv:

uv run server.py

The run script automatically sets the required environment variables:

• GDRIVE_CREDENTIALS_PATH: Path to your credentials.json file
• GDRIVE_TOKEN_PATH: Path to the token.json file (auto-created)

Environment Variables

The server expects these environment variables:

• GDRIVE_CREDENTIALS_PATH: Path to Google Cloud credentials JSON file
• GDRIVE_TOKEN_PATH: Path to OAuth token JSON file

These are automatically set by the run script, but you can override them if needed.

Features

The server provides MCP tools for:

• File operations (list, read, create, update, delete)
• Folder management
• Permission checking
• Search functionality
• File sharing and permissions

Dependencies

• fastmcp: FastMCP framework
• google-api-python-client: Google API client
• google-auth-oauthlib: OAuth authentication
• python-dotenv: Environment variable management

Complete Setup Guide for New Users

This section provides detailed step-by-step instructions for setting up the Google Drive MCP Server on a new machine from scratch.

Step 1: Prerequisites Installation

Install Python 3.13+

• macOS: Install via Homebrew: brew install python@3.13
• Windows: Download from python.org
• Linux: Use your package manager (e.g., sudo apt install python3.13)

Install uv Package Manager

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: via pip
pip install uv

Step 2: Clone the Repository

# Clone the repository
git clone <repository-url>
cd gdrive-mcp

# Or download and extract the ZIP file
# Then navigate to the extracted directory

Step 3: Google Cloud Console Setup

3.1 Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click "Select a project" → "New Project"
3. Enter project name (e.g., "gdrive-mcp-server")
4. Click "Create"

3.2 Enable Google Drive API

1. In the Google Cloud Console, go to "APIs & Services" → "Library"
2. Search for "Google Drive API"
3. Click on "Google Drive API" and click "Enable"

3.3 Create OAuth 2.0 Credentials

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth client ID"
3. If prompted, configure the OAuth consent screen:
   • Choose "External" user type
   • Fill in required fields (App name, User support email, Developer contact)
   • Add your email to test users
4. For Application type, choose "Desktop application"
5. Give it a name (e.g., "Google Drive MCP Server")
6. Click "Create"

3.4 Download Credentials

1. After creating the OAuth client, click the download button (⬇️)
2. Save the JSON file as credentials.json in your project root directory
3. Important: Never commit this file to version control!

Step 4: Project Setup

4.1 Install Dependencies

# Navigate to the project directory
cd gdrive-mcp

# Install dependencies using uv
uv sync

4.2 Update Run Script (Important!)

The run_server.sh script contains hardcoded paths. Update it for your system:

# Edit the run_server.sh file
nano run_server.sh  # or use your preferred editor

Update the paths to match your system:

#!/bin/bash

# Set Google Drive credentials environment variables
export GDRIVE_CREDENTIALS_PATH="/path/to/your/gdrive-mcp/credentials.json"
export GDRIVE_TOKEN_PATH="/path/to/your/gdrive-mcp/.token.json"

# Run the server using uv
uv run server.py

Replace /path/to/your/gdrive-mcp/ with your actual project path.

4.3 Make Script Executable

chmod +x run_server.sh

Step 5: Authentication Setup

5.1 First Run (OAuth Flow)

When you first run the server, it will need to authenticate with Google:

./run_server.sh

Note: The server will start but may show authentication errors initially. This is normal for the first run.

5.2 Manual Authentication (If Needed)

If the automatic OAuth flow doesn't work, you can manually authenticate:

1. Create a simple auth script (temporary):

# Create auth_setup.py
from google_auth_oauthlib.flow import Flow
import json
import webbrowser
from pathlib import Path

# Load credentials
with open('credentials.json', 'r') as f:
    client_config = json.load(f)

# Set up the flow
flow = Flow.from_client_config(
    client_config,
    scopes=[
        "https://www.googleapis.com/auth/drive",
        "https://www.googleapis.com/auth/drive.file",
        "https://www.googleapis.com/auth/drive.metadata.readonly",
    ],
    redirect_uri='urn:ietf:wg:oauth:2.0:oob'
)

# Get authorization URL
auth_url, _ = flow.authorization_url(prompt='consent')
print(f"Please visit this URL to authorize the application: {auth_url}")

# Get authorization code from user
auth_code = input('Enter the authorization code: ')

# Exchange code for token
flow.fetch_token(code=auth_code)

# Save credentials
with open('.token.json', 'w') as f:
    json.dump(flow.credentials.to_json(), f, indent=2)

print("Authentication successful! Token saved to .token.json")

2. Run the auth script:

uv run auth_setup.py

3. Follow the prompts:

   • Visit the provided URL in your browser
   • Sign in to your Google account
   • Grant permissions to the application
   • Copy the authorization code
   • Paste it back into the terminal

4. Delete the auth script (for security):

rm auth_setup.py

Step 6: Test the Server

6.1 Start the Server

./run_server.sh

You should see output like:

╭────────────────────────────────────────────────────────────────────────────╮
│                                                                            │
│        _ __ ___  _____           __  __  _____________    ____    ____     │
│       _ __ ___ .'____/___ ______/ /_/  |/  / ____/ __ \  |___ \  / __ \    │
│      _ __ ___ / /_  / __ `/ ___/ __/ /|_/ / /   / /_/ /  ___/ / / / / /    │
│     _ __ ___ / __/ / /_/ (__  ) /_/ /  / / /___/ ____/  /  __/_/ /_/ /     │
│    _ __ ___ /_/    \____/____/\__/_/  /_/\____/_/      /_____(*)____/      │
│                                                                            │
│                                                                            │
│                                FastMCP  2.0                                │
│                                                                            │
│                                                                            │
│                 🖥️  Server name:     google-drive-mcp                       │
│                 📦 Transport:       STDIO                                  │
│                                                                            │
│                 🏎️  FastMCP version: 2.12.2                                 │
│                 🤝 MCP SDK version: 1.13.1                                 │
│                                                                            │
│                 📚 Docs:            https://gofastmcp.com                  │
│                 🚀 Deploy:          https://fastmcp.cloud                  │
│                                                                            │
╰────────────────────────────────────────────────────────────────────────────╯

6.2 Test with MCP Client

Connect your MCP client to test the server. The server provides tools like:

• check_file_permissions
• list_files
• create_folder
• download_file
• And many more Google Drive operations

Step 7: Troubleshooting

Common Issues:

1. "Credentials not found" error:

   • Ensure credentials.json is in the project root
   • Check that the file path in run_server.sh is correct

2. "Token expired" error:

   • Delete .token.json and re-authenticate
   • Run the manual authentication process again

3. "Permission denied" error:

   • Check that the OAuth consent screen is properly configured
   • Ensure your email is added to test users

4. "Module not found" errors:

   • Run uv sync to ensure all dependencies are installed
   • Check that you're using the correct Python version (3.13+)

5. Server won't start:

   • Check that uv is properly installed
   • Verify the run_server.sh script is executable
   • Check file paths in the script

Getting Help:

• Check the server logs for detailed error messages
• Verify your Google Cloud Console setup
• Ensure all file permissions are correct
• Test with a simple MCP client first

Step 8: Security Best Practices

1. Never commit credentials:

   • Add credentials.json and .token.json to .gitignore
   • Use environment variables for production deployments

2. Limit OAuth scopes:

   • Only request the minimum required permissions
   • Regularly review and audit your OAuth consent screen

3. Secure token storage:

   • Keep .token.json secure and private
   • Consider using encrypted storage for production

4. Regular token refresh:

   • Tokens expire periodically
   • The server handles refresh automatically, but monitor for issues

Step 9: Production Deployment

For production use:

1. Use environment variables instead of hardcoded paths
2. Implement proper logging and monitoring
3. Use HTTPS for all communications
4. Set up proper backup and recovery procedures
5. Monitor API quotas and usage limits

File Structure

gdrive-mcp/
├── server.py              # Main MCP server implementation
├── pyproject.toml         # uv project configuration
├── uv.lock               # Dependency lock file
├── run_server.sh         # Server startup script
├── README.md             # This file
├── .gitignore            # Git ignore rules
├── credentials.json      # Google Cloud credentials (you create this)
└── .token.json          # OAuth token (auto-generated)

API Scopes

The server requests these Google Drive API scopes:

• https://www.googleapis.com/auth/drive - Full access to Google Drive
• https://www.googleapis.com/auth/drive.file - Access to files created by the app
• https://www.googleapis.com/auth/drive.metadata.readonly - Read-only access to metadata

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

[Add your license information here]