gdrive-mcp-server

cnye36/gdrive-mcp-server

3.2

If you are the rightful owner of gdrive-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A comprehensive Model Context Protocol (MCP) server for Google Drive with full OAuth authentication, read/write operations, and Docker support.

Tools
5
Resources
0
Prompts
0

Google Drive MCP Server

A comprehensive Model Context Protocol (MCP) server for Google Drive with full OAuth authentication, read/write operations, and Docker support.

Features

Read Operations

  • list_files - List files and folders with optional filtering
  • get_file - Get detailed metadata for a specific file
  • download_file - Download file content (supports export for Google Docs)
  • search_files - Search files by name
  • get_permissions - View sharing permissions for a file

Write Operations

  • create_file - Create new files with content
  • update_file - Update existing file content
  • delete_file - Delete files
  • create_folder - Create new folders
  • copy_file - Create copies of files
  • move_file - Move files between folders
  • share_file - Share files with other users

Prerequisites

  1. Node.js 20+ and pnpm installed
  2. Google Cloud Project with Drive API enabled
  3. OAuth 2.0 credentials from Google Cloud Console

Google Cloud Setup

  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google Drive API:
    • Navigate to "APIs & Services" > "Library"
    • Search for "Google Drive API"
    • Click "Enable"
  4. Create OAuth 2.0 credentials:
    • Go to "APIs & Services" > "Credentials"
    • Click "Create Credentials" > "OAuth client ID"
    • Choose "Web application"
    • Add authorized redirect URI: http://localhost:3000/oauth/callback
    • Save the Client ID and Client Secret

Installation

Local Development

  1. Clone or download this repository

  2. Install dependencies:

    pnpm install

  3. Create .env file from the example:

    cp .env.example .env

  4. Edit .env with your credentials:

    PORT=3000
NODE_ENV=development
GOOGLE_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth/callback

  5. Build the TypeScript code:

    pnpm run build

  6. Start the server:

    pnpm start

Docker Deployment

  1. Create .env file with your credentials (as above)

  2. Build and run with Docker Compose:

    docker-compose up -d

  3. View logs:

    docker-compose logs -f

  4. Stop the server:

    docker-compose down

Authentication

First-Time Setup

  1. Start the server (local or Docker)
  2. Visit http://localhost:3000/oauth/url to get the authorization URL
  3. Open the URL in your browser and authorize the application
  4. You'll be redirected back to the callback URL
  5. The tokens will be saved automatically

Check Authentication Status

curl http://localhost:3000/health

Response:

{
  "status": "ok",
  "authenticated": true,
  "timestamp": "2025-10-21T12:00:00.000Z"
}

Usage

HTTP API Endpoints

Health Check
GET http://localhost:3000/health
Get OAuth URL
GET http://localhost:3000/oauth/url
List Available Tools
GET http://localhost:3000/mcp/tools
Execute a Tool
POST http://localhost:3000/mcp/execute
Content-Type: application/json

{
  "tool": "list_files",
  "arguments": {
    "pageSize": 10
  }
}

Example API Calls

List Files
curl -X POST http://localhost:3000/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_files",
    "arguments": {
      "pageSize": 20
    }
  }'
Search Files
curl -X POST http://localhost:3000/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "search_files",
    "arguments": {
      "query": "budget",
      "pageSize": 10
    }
  }'
Create a File
curl -X POST http://localhost:3000/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "create_file",
    "arguments": {
      "name": "test.txt",
      "content": "Hello, World!",
      "mimeType": "text/plain"
    }
  }'
Download a File
curl -X POST http://localhost:3000/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "download_file",
    "arguments": {
      "fileId": "1234567890abcdef"
    }
  }'
Create a Folder
curl -X POST http://localhost:3000/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "create_folder",
    "arguments": {
      "name": "My New Folder"
    }
  }'
Share a File
curl -X POST http://localhost:3000/mcp/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "share_file",
    "arguments": {
      "fileId": "1234567890abcdef",
      "email": "user@example.com",
      "role": "reader"
    }
  }'

Tool Reference

list_files

List files in Google Drive.

Arguments:

  • pageSize (number, optional): Number of files to return (default: 10)
  • query (string, optional): Google Drive query string
  • folderId (string, optional): ID of folder to list files from

get_file

Get metadata for a specific file.

Arguments:

  • fileId (string, required): The ID of the file

download_file

Download file content.

Arguments:

  • fileId (string, required): The ID of the file
  • exportMimeType (string, optional): For Google Docs, export format

search_files

Search for files by name.

Arguments:

  • query (string, required): Search query
  • pageSize (number, optional): Number of results (default: 10)

create_file

Create a new file.

Arguments:

  • name (string, required): File name
  • content (string, required): File content
  • mimeType (string, required): MIME type
  • parentId (string, optional): Parent folder ID

update_file

Update file content.

Arguments:

  • fileId (string, required): The ID of the file
  • content (string, required): New content
  • mimeType (string, optional): MIME type

delete_file

Delete a file.

Arguments:

  • fileId (string, required): The ID of the file

create_folder

Create a new folder.

Arguments:

  • name (string, required): Folder name
  • parentId (string, optional): Parent folder ID

copy_file

Copy a file.

Arguments:

  • fileId (string, required): The ID of the file
  • newName (string, required): Name for the copy
  • parentId (string, optional): Destination folder ID

move_file

Move a file to another folder.

Arguments:

  • fileId (string, required): The ID of the file
  • newParentId (string, required): Destination folder ID

share_file

Share a file with another user.

Arguments:

  • fileId (string, required): The ID of the file
  • email (string, required): Email address
  • role (string, optional): "reader", "writer", or "commenter" (default: "reader")

get_permissions

Get sharing permissions for a file.

Arguments:

  • fileId (string, required): The ID of the file

Project Structure

google-drive-mcp/
├── src/
│   ├── index.ts              # HTTP server with Express
│   ├── google-drive-client.ts # Google Drive API wrapper
│   └── mcp-server.ts          # MCP server implementation
├── Dockerfile
├── docker-compose.yml
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Development

Run in Development Mode

pnpm run dev

Build TypeScript

pnpm run build

Clean Build Files

pnpm run clean

Security Considerations

  1. Never commit .env or .tokens.json files
  2. Restrict OAuth scopes if you don't need full Drive access
  3. Use environment variables for all sensitive data
  4. Rotate credentials regularly
  5. Enable HTTPS in production environments

Troubleshooting

"Not authenticated" error

  1. Check if .tokens.json exists
  2. Visit /oauth/url to re-authenticate
  3. Verify your OAuth credentials in .env

Docker container won't start

  1. Check logs: docker-compose logs
  2. Verify .env file exists and is properly formatted
  3. Ensure port 3000 is available

API errors

  1. Check Google Cloud Console for API quota limits
  2. Verify the Drive API is enabled
  3. Check token expiration in .tokens.json

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.