MCP Google Drive Server

This project implements an MCP server that provides tools for interacting with Google Drive.

Getting Started

Before running this server, you must set up a Google Cloud project and authenticate it to access your Google Drive. This involves obtaining OAuth 2.0 credentials.

Google Cloud Setup - Obtaining Your OAuth Keys

To allow the server to interact with Google Drive on your behalf, you need to create OAuth 2.0 credentials in the Google Cloud Platform console.

1. Go to the Google Cloud Platform Console.
2. Create a new Google Cloud project or select an existing one.
3. Navigate to "APIs & Services" > "Library" and enable the "Google Drive API" for your project.
4. Navigate to "APIs & Services" > "OAuth consent screen". Configure an OAuth consent screen (setting it to "Internal" is sufficient for testing within your organization).
5. Navigate to "APIs & Services" > "Credentials". Click "Create Credentials" > "OAuth client ID".
6. For "Application type", select "Desktop app".
7. Give your client a name and click "Create".
8. A dialog will appear with your Client ID and Client Secret. Click "Download JSON" to save your client's configuration file.
9. Rename the downloaded JSON file to gcp-oauth.keys.json.
10. Place this gcp-oauth.keys.json file inside the ./credentials/ directory at the root of this project repository. (e.g., your-repo-root/credentials/gcp-oauth.keys.json).

Build the Server

Before running the server or performing initial authentication, make sure the project is built:

npm run build
# or, for development
npm run watch

Authentication

When you run the server for the first time without valid credentials, it will automatically initiate the Google Drive interactive authentication flow using the gcp-oauth.keys.json file you placed in the ./credentials/ directory.

1. Ensure your gcp-oauth.keys.json file is correctly placed in the ./credentials/ directory.
2. Start the server using your preferred method (e.g., node ./dist/server.js for local running, or docker compose up for Docker).
3. The server will detect missing credentials and log that it is starting the interactive authentication flow. A browser window should open prompting you to sign in to your Google account and grant the necessary permissions (https://www.googleapis.com/auth/drive.readonly by default, check src/services/GoogleDriveService.ts for full scopes).
4. Complete the authentication process in your browser.
5. Upon successful authentication, the obtained credentials (including a refresh token) will be automatically saved by the server to .gdrive-server-credentials.json file inside the ./credentials/ directory (e.g., your-repo-root/credentials/.gdrive-server-credentials.json).
6. Once .gdrive-server-credentials.json exists, the server will load credentials from this file on subsequent runs and should not require repeated browser authentication unless the file is deleted or becomes invalid.

Running with Docker

You can run this project in a containerized environment using Docker and Docker Compose. This setup ensures consistency and isolates dependencies, making it easy to deploy or develop locally.

Requirements

• Docker and Docker Compose installed on your system.
• The project uses Node.js v22.13.1 (as specified in the Dockerfile).

Environment Variables

• The application supports environment variables via a .env file. You can copy .env.example to .env and adjust values as needed.
• By default, the Docker Compose file loads the .env file (if it exists and env_file is uncommented/present in compose.yaml).
• Important for Docker: When running with Docker, ensure your .env file (or Docker environment settings) sets GDRIVE_OAUTH_PATH to /run/secrets/gcp-oauth.keys.json and GOOGLE_CREDENTIALS_FILE_PATH to /run/secrets/.gdrive-server-credentials.json. These paths correspond to where the secrets are mounted by compose.yaml.

Build and Run

To build and start the application using Docker Compose:

# Build and start the service
docker compose up --build

This will:

• Build the Docker image using the provided Dockerfile (Node.js v22.13.1-slim)
• Start the application in a container named typescript-app
• Expose port 3000 on your host (mapped to the container's port 3000)

Service Details

• Service name: typescript-app
• Exposed port: 3000 (host) → 3000 (container)
• Network: app-net (Docker bridge network)
• User: Runs as a non-root user inside the container for security
• Credentials & Secrets:
  • Sensitive files like gcp-oauth.keys.json (OAuth Client Secrets) and .gdrive-server-credentials.json (stored user tokens) are not baked into the Docker image.
  • They are mounted into the container at runtime from your host machine's ./credentials/ directory to /run/secrets/ inside the container using Docker volume mounts (see compose.yaml). The /run/secrets/ directory is a common convention inside containers, populated by Docker from your local files.
  • Ensure these files exist in ./credentials/ on your host before running docker compose up.
  • The application will guide you through a browser-based authentication flow on the first run if tokens are missing or invalid, and will then store them in the mounted .gdrive-server-credentials.json file.

Customization

• If you need to change the exposed port, edit the ports section in docker-compose.yml.
• To use a different environment file, update the env_file path accordingly.
• No external services (databases, caches) are required by default. If you add any, update the Compose file as needed.

Available Tools

This server provides service methods that can be mapped to MCP tools for interacting with Google Drive:

• Read File: Reads the content of a specific file from Google Drive using its file ID. (Corresponds to GoogleDriveService.readFile)
• Write File: Creates a new file in Google Drive with specified content and name. (Corresponds to GoogleDriveService.writeFile)
• Search Files: Searches for files and folders within Google Drive based on a query. (Corresponds to GoogleDriveService.searchFiles)
• Create Folder: Creates a new folder in Google Drive. (Corresponds to GoogleDriveService.createFolder)
• List Folder Contents: Lists the files and folders within a specific Google Drive folder. (Corresponds to GoogleDriveService.listFolderContents)
• Get Folder ID by Name: Searches for a folder by its name (and optionally parent ID) and returns its ID. (Corresponds to GoogleDriveService.getFolderIdByName)

Each service method has corresponding parameter definitions and return types defined within GoogleDriveService.ts and the associated types in src/types/. When exposing these as MCP tools, you would define tool schemas (e.g., in src/tools/) that utilize these service methods.