piotr-agier/google-drive-mcp
If you are the rightful owner of google-drive-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A Model Context Protocol (MCP) server that provides secure integration with Google Drive, Docs, Sheets, and Slides.
Google Drive MCP Server
A Model Context Protocol (MCP) server that provides secure integration with Google Drive, Docs, Sheets, and Slides. It allows Claude Desktop and other MCP clients to manage files in Google Drive through a standardized interface.
Features
- Multi-format Support: Work with Google Docs, Sheets, Slides, and regular files
- File Management: Create, update, delete, rename, and move files and folders
- Advanced Search: Search across your entire Google Drive
- Folder Navigation: List and navigate through folder hierarchies with path support (e.g.,
/Work/Projects
) - MCP Resource Protocol: Files accessible as MCP resources for reading content
- Secure Authentication: OAuth 2.0 with automatic token refresh
Example Usage
This MCP server enables powerful file management workflows through natural language:
1. Document Creation and Organization
Create a new Google Doc called "Project Plan" in the folder /Work/Projects
with an outline for our Q1 initiatives including milestones and deliverables.
2. File Search and Organization
Search for files containing "budget" and organize them by moving each one
to the appropriate folder in your Drive hierarchy.
3. Spreadsheet Creation
Create a Google Sheet called "Sales Analysis 2024" with columns for Date, Product,
Quantity, and Revenue to track your sales data.
4. Presentation Creation
Create a presentation called "Product Roadmap" with slides outlining
our Q1 milestones, key features, and timeline.
5. Spreadsheet Updates
Update the "Team Contacts" spreadsheet with new employee information
by modifying specific cells or ranges with the provided data.
6. Document Search
Search for documents in the /Reports folder and create a summary
document listing the files you found.
7. Folder and Document Creation
Create a Templates folder and add standard documents like
a Meeting Notes template, Project Proposal template,
and Budget Spreadsheet template.
Requirements
- Node.js: Version 18 or higher (LTS recommended)
- Google Cloud Project: With the following APIs enabled:
- Google Drive API
- Google Docs API
- Google Sheets API
- Google Slides API
- OAuth 2.0 Credentials: Desktop application type (Client ID only - no client secret required)
Google Cloud Setup
1. Create a Google Cloud Project
- Go to the Google Cloud Console
- Click "Select a project" > "New Project"
- Name your project (e.g., "Google Drive MCP")
- Note the Project ID for later
2. Enable Required APIs
- In your project, go to "APIs & Services" > "Library"
- Search for and enable each of these APIs:
- Google Drive API
- Google Docs API
- Google Sheets API
- Google Slides API
- Wait for each API to be enabled before proceeding
3. Configure OAuth Consent Screen
- Go to "APIs & Services" > "OAuth consent screen"
- Under 'Branding' fill in the required fields:
- App name: "My Personal Google Drive MCP"
- User support email: Your email
- Developer contact: Your email
- Under 'Audience':
- Choose "External" (default choice) or "Internal" for Google Workspace accounts
- Add your email as a test user
- Under 'Data Access' add scopes. The recommended set of scopes for best user experience is the following:
./auth/drive.file
.../auth/documents
.../auth/spreadsheets
.../auth/presentations
.../auth/drive
.../auth/drive.readonly
4. Create OAuth 2.0 Credentials
- Go to "APIs & Services" > "Credentials"
- Click "+ CREATE CREDENTIALS" > "OAuth client ID"
- Application type: Desktop app (Important!)
- Name: "Google Drive MCP Client"
- Click "Create"
- Download the JSON file
- Rename it to
gcp-oauth.keys.json
Installation
Option 1: Use with npx (Recommended)
You can run the server directly without installation:
# Run the server (authentication happens automatically on first run)
npx @piotr-agier/google-drive-mcp
# Optional: Run authentication manually if needed
npx @piotr-agier/google-drive-mcp auth
Option 2: Local Installation
-
Clone and install:
git clone https://github.com/piotr-agier/google-drive-mcp.git cd google-drive-mcp npm install
-
Set up credentials:
# Copy the example file cp gcp-oauth.keys.example.json gcp-oauth.keys.json # Edit gcp-oauth.keys.json with your OAuth client ID
-
Authenticate (optional):
npm run auth
Note: Authentication happens automatically on first run of an MCP client if you skip this step.
Docker Usage
Prerequisites
-
Authenticate locally first - Docker containers cannot open browsers for OAuth:
# Using npx npx @piotr-agier/google-drive-mcp auth # Or using local installation npm run auth
-
Verify token location:
ls -la ~/.config/google-drive-mcp/tokens.json
Building the Docker Image
-
Build the project (required before Docker build):
npm install npm run build
-
Build the Docker image:
docker build -t google-drive-mcp .
Running the Docker Container
Run the container with your credentials and tokens mounted:
docker run -it \
-v /path/to/gcp-oauth.keys.json:/config/gcp-oauth.keys.json:ro \
-v ~/.config/google-drive-mcp/tokens.json:/config/tokens.json \
google-drive-mcp
Important Notes:
- Replace
/path/to/gcp-oauth.keys.json
with the actual path to your OAuth credentials - The
:ro
flag mounts the credentials as read-only for security - Tokens are mounted read-write to allow automatic refresh
- The container runs as non-root user for security
Docker Configuration for Claude Desktop
Add this configuration to use the Docker container with Claude Desktop:
{
"mcpServers": {
"google-drive": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"/path/to/gcp-oauth.keys.json:/config/gcp-oauth.keys.json:ro",
"-v",
"/Users/yourname/.config/google-drive-mcp/tokens.json:/config/tokens.json",
"google-drive-mcp"
]
}
}
}
Docker-specific notes:
- Uses
-i
for interactive mode (required for MCP stdio communication) - Uses
--rm
to automatically remove the container after exit - No port mapping needed (MCP uses stdio, not HTTP)
- Environment variables are set in the Dockerfile
Configuration
OAuth Credentials Configuration
The server supports multiple methods for providing OAuth credentials (in order of priority):
1. Environment Variable (Recommended)
export GOOGLE_DRIVE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"
2. Default File Location
Place gcp-oauth.keys.json
in the project root directory
Token Storage
Authentication tokens are stored securely following the XDG Base Directory specification:
Priority | Location | Configuration |
---|---|---|
1 | Custom path | Set GOOGLE_DRIVE_MCP_TOKEN_PATH environment variable |
2 | XDG Config | $XDG_CONFIG_HOME/google-drive-mcp/tokens.json |
3 | Default | ~/.config/google-drive-mcp/tokens.json |
Security Notes:
- Tokens are created with secure permissions (0600)
- Never commit tokens to version control
- Tokens auto-refresh before expiration
- Google OAuth apps in "Testing" status have refresh tokens that expire after 7 days (Google's policy)
Usage with Claude Desktop
Add the server to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Using npx (Recommended):
{
"mcpServers": {
"google-drive": {
"command": "npx",
"args": ["@piotr-agier/google-drive-mcp"],
"env": {
"GOOGLE_DRIVE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
}
}
}
}
Using Local Installation:
{
"mcpServers": {
"google-drive": {
"command": "node",
"args": ["/absolute/path/to/google-drive-mcp/dist/index.js"],
"env": {
"GOOGLE_DRIVE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
}
}
}
}
Note: Replace /path/to/your/gcp-oauth.keys.json
with the actual path to your OAuth credentials file.
Available Tools
Search and Navigation
-
search - Search for files across Google Drive
query
: Search terms
-
listFolder - List contents of a folder
folderId
: Folder ID (optional, defaults to root)pageSize
: Number of results (optional, max 100)pageToken
: Pagination token (optional)
File Management
-
createTextFile - Create a text or markdown file
name
: File name (must end with .txt or .md)content
: File contentparentFolderId
: Parent folder ID (optional)
-
updateTextFile - Update existing text file
fileId
: File ID to updatecontent
: New contentname
: New name (optional)
-
deleteItem - Move a file or folder to trash (not a permanent deletion - items can be restored from Google Drive trash)
itemId
: Item ID to move to trash
-
renameItem - Rename a file or folder
itemId
: Item ID to renamenewName
: New name
-
moveItem - Move a file or folder
itemId
: Item ID to movedestinationFolderId
: Destination folder ID
Folder Operations
- createFolder - Create a new folder
name
: Folder nameparent
: Parent folder ID or path (optional)
Google Workspace
-
createGoogleDoc - Create a Google Doc
name
: Document namecontent
: Document contentparentFolderId
: Parent folder ID (optional)
-
updateGoogleDoc - Update a Google Doc
documentId
: Document IDcontent
: New content
-
getGoogleDocContent - Get document content with text indices
documentId
: Document ID- Returns text with character positions for formatting
-
formatGoogleDocText - Apply text formatting to a range
documentId
: Document IDstartIndex
: Start position (1-based)endIndex
: End position (1-based)bold
: Make text bold (optional)italic
: Make text italic (optional)underline
: Underline text (optional)strikethrough
: Strikethrough text (optional)fontSize
: Font size in points (optional)foregroundColor
: Text color as RGB (0-1) (optional)
-
formatGoogleDocParagraph - Apply paragraph formatting to a range
documentId
: Document IDstartIndex
: Start position (1-based)endIndex
: End position (1-based)namedStyleType
: Style like HEADING_1, HEADING_2, etc. (optional)alignment
: START, CENTER, END, or JUSTIFIED (optional)lineSpacing
: Line spacing multiplier (optional)spaceAbove
: Space above paragraph in points (optional)spaceBelow
: Space below paragraph in points (optional)
-
createGoogleSheet - Create a Google Sheet
name
: Spreadsheet namedata
: 2D array of cell valuesparentFolderId
: Parent folder ID (optional)
-
updateGoogleSheet - Update a Google Sheet
spreadsheetId
: Spreadsheet IDrange
: Range to update (e.g., "A1:C10")data
: 2D array of new values
-
createGoogleSlides - Create a presentation
name
: Presentation nameslides
: Array of slides with title and contentparentFolderId
: Parent folder ID (optional)
-
updateGoogleSlides - Update an existing presentation
presentationId
: Presentation IDslides
: Array of slides with title and content (replaces all existing slides)
Google Sheets Formatting Tools
-
getGoogleSheetContent - Get spreadsheet content with cell information
spreadsheetId
: Spreadsheet IDrange
: Range to get (e.g., 'Sheet1!A1:C10')- Returns cell values for the specified range
-
formatGoogleSheetCells - Format cell properties
spreadsheetId
: Spreadsheet IDrange
: Range to format (e.g., 'A1:C10')backgroundColor
: Cell background color (RGB 0-1) (optional)horizontalAlignment
: LEFT, CENTER, or RIGHT (optional)verticalAlignment
: TOP, MIDDLE, or BOTTOM (optional)wrapStrategy
: OVERFLOW_CELL, CLIP, or WRAP (optional)
-
formatGoogleSheetText - Apply text formatting to cells
spreadsheetId
: Spreadsheet IDrange
: Range to format (e.g., 'A1:C10')bold
: Make text bold (optional)italic
: Make text italic (optional)strikethrough
: Strikethrough text (optional)underline
: Underline text (optional)fontSize
: Font size in points (optional)fontFamily
: Font name (optional)foregroundColor
: Text color (RGB 0-1) (optional)
-
formatGoogleSheetNumbers - Apply number/date formatting
spreadsheetId
: Spreadsheet IDrange
: Range to format (e.g., 'A1:C10')pattern
: Format pattern (e.g., '#,##0.00', 'yyyy-mm-dd', '$#,##0.00', '0.00%')type
: NUMBER, CURRENCY, PERCENT, DATE, TIME, DATE_TIME, or SCIENTIFIC (optional)
-
setGoogleSheetBorders - Configure cell borders
spreadsheetId
: Spreadsheet IDrange
: Range to format (e.g., 'A1:C10')style
: SOLID, DASHED, DOTTED, or DOUBLEwidth
: Border thickness 1-3 (optional)color
: Border color (RGB 0-1) (optional)top
,bottom
,left
,right
: Apply to specific borders (optional)innerHorizontal
,innerVertical
: Apply to inner borders (optional)
-
mergeGoogleSheetCells - Merge cells in a range
spreadsheetId
: Spreadsheet IDrange
: Range to merge (e.g., 'A1:C3')mergeType
: MERGE_ALL, MERGE_COLUMNS, or MERGE_ROWS
-
addGoogleSheetConditionalFormat - Add conditional formatting rules
spreadsheetId
: Spreadsheet IDrange
: Range to apply formatting (e.g., 'A1:C10')condition
: Condition configurationtype
: NUMBER_GREATER, NUMBER_LESS, TEXT_CONTAINS, TEXT_STARTS_WITH, TEXT_ENDS_WITH, or CUSTOM_FORMULAvalue
: Value to compare or formula
format
: Format to apply when condition is truebackgroundColor
: Cell color (RGB 0-1) (optional)textFormat
: Text formatting with bold and foregroundColor (optional)
Google Slides Formatting Tools
-
getGoogleSlidesContent - Get presentation content with element IDs
presentationId
: Presentation IDslideIndex
: Specific slide index (optional)- Returns element IDs for formatting
-
formatGoogleSlidesText - Apply text formatting to slide elements
presentationId
: Presentation IDobjectId
: Element IDstartIndex
/endIndex
: Text range (optional)bold
,italic
,underline
,strikethrough
: Text stylingfontSize
: Font size in pointsfontFamily
: Font nameforegroundColor
: Text color (RGB 0-1)
-
formatGoogleSlidesParagraph - Apply paragraph formatting
presentationId
: Presentation IDobjectId
: Element IDalignment
: START, CENTER, END, or JUSTIFIEDlineSpacing
: Line spacing multiplierbulletStyle
: NONE, DISC, ARROW, SQUARE, DIAMOND, STAR, or NUMBERED
-
styleGoogleSlidesShape - Style shapes and elements
presentationId
: Presentation IDobjectId
: Shape IDbackgroundColor
: Fill color (RGBA 0-1)outlineColor
: Border color (RGB 0-1)outlineWeight
: Border thickness in pointsoutlineDashStyle
: SOLID, DOT, DASH, etc.
-
setGoogleSlidesBackground - Set slide background color
presentationId
: Presentation IDpageObjectIds
: Array of slide IDsbackgroundColor
: Background color (RGBA 0-1)
-
createGoogleSlidesTextBox - Create formatted text box
presentationId
: Presentation IDpageObjectId
: Slide IDtext
: Text contentx
,y
,width
,height
: Position/size in EMU (1/360000 cm)fontSize
,bold
,italic
: Text formatting (optional)
-
createGoogleSlidesShape - Create styled shape
presentationId
: Presentation IDpageObjectId
: Slide IDshapeType
: RECTANGLE, ELLIPSE, DIAMOND, TRIANGLE, STAR, ROUND_RECTANGLE, or ARROWx
,y
,width
,height
: Position/size in EMUbackgroundColor
: Fill color (RGBA 0-1) (optional)
Authentication Flow
The server uses OAuth 2.0 for secure authentication:
Automatic Authentication (First Run)
- Server detects missing tokens and starts local auth server
- Your browser opens to Google's consent page
- Grant the requested permissions
- Tokens are saved securely to
~/.config/google-drive-mcp/tokens.json
- Server continues startup
Token Management
- Automatic Refresh: Tokens refresh automatically before expiration
- Secure Storage: Tokens stored with 0600 permissions
- Migration: Legacy tokens are automatically migrated to secure location
Manual Re-authentication
Run the auth command when you need to:
- Switch Google accounts
- Refresh expired tokens (Google expires refresh tokens after 7 days for apps in "Testing" status)
- Recover from revoked access
# Using npx
npx @piotr-agier/google-drive-mcp auth
# Using local installation
npm run auth
Security
Security Features
- No Client Secrets: Desktop OAuth flow works with client ID only
- Secure Token Storage: Tokens stored with 0600 permissions in XDG-compliant location
- Scoped Access: Minimal permissions requested (drive.file, documents, spreadsheets, presentations)
- Local Execution: All processing happens on your machine
- Automatic Token Refresh: Reduces need for re-authentication
- Token Migration: Legacy tokens automatically moved to secure location
Best Practices
-
Never commit credentials: Add to
.gitignore
:gcp-oauth.keys.json client_secret*.json .config/
-
Use environment variables for production:
export GOOGLE_DRIVE_OAUTH_CREDENTIALS="/secure/path/credentials.json" export GOOGLE_DRIVE_MCP_TOKEN_PATH="/secure/path/tokens.json"
-
Monitor access:
- Check recent activity in Google Drive
- Review OAuth app permissions regularly
Revoking OAuth Access
If you need to revoke the Google Drive MCP's access to your Google account:
- Visit Google Account Permissions
- Find "Google Drive MCP" or your custom app name in the list
- Click on it and select "Remove Access"
- Clear local tokens to complete the revocation:
rm ~/.config/google-drive-mcp/tokens.json
After revoking access, you'll need to re-authenticate the next time you use the server.
Troubleshooting
Common Issues and Solutions
"OAuth credentials not found"
OAuth credentials not found. Please provide credentials using one of these methods:
1. Environment variable:
export GOOGLE_DRIVE_OAUTH_CREDENTIALS="/path/to/gcp-oauth.keys.json"
2. Default file path:
Place your gcp-oauth.keys.json file in the package root directory.
Solution:
- Download credentials from Google Cloud Console
- Either set the environment variable or place the file in the project root
- Ensure the file has proper read permissions
"Authentication failed" or Browser doesn't open
Possible causes:
- Wrong credential type: Must be "Desktop app", not "Web application"
- Port blocked: Ports 3000-3004 must be available
- Test user not added: Add your email in OAuth consent screen
Solution:
# Check if ports are in use
lsof -i :3000-3004
# Kill processes if needed
kill -9 <PID>
# Re-run authentication
npx @piotr-agier/google-drive-mcp auth
"Tokens expired" or "Invalid grant"
For Google OAuth apps in "Testing" status:
- Google automatically expires refresh tokens after 7 days
- You'll need to re-authenticate weekly until you publish your app
Solution:
# Clear old tokens and re-authenticate
rm ~/.config/google-drive-mcp/tokens.json
npx @piotr-agier/google-drive-mcp auth
For production:
- Move app to "Published" status in Google Cloud Console
- Complete OAuth verification process
"Login Required" error even with valid tokens
If you updated the OAuth scopes but still get errors:
- Google caches app authorizations even after removing local tokens
- The app might be using old/limited scopes
Solution:
- Go to Google Account Permissions
- Find and remove access for "Google Drive MCP"
- Clear local tokens:
rm ~/.config/google-drive-mcp/tokens.json
- Re-authenticate to grant all required scopes
- Verify the consent screen shows ALL scopes including full Drive access
"API not enabled" errors
Error: Google Sheets API has not been used in project...
Solution:
- Go to Google Cloud Console
- Select your project
- Navigate to "APIs & Services" > "Library"
- Search and enable the missing API
- Wait 1-2 minutes for propagation
"Insufficient permissions"
Check scopes in your credentials:
- Need drive.file or drive scope
- Need docs, sheets, slides scopes for respective services
Solution:
- Re-create OAuth credentials with correct scopes
- Re-authenticate after updating credentials
Rate Limiting (429 errors)
Google API Quotas:
- Drive API: 12,000 requests per minute
- Docs/Sheets/Slides: 300 requests per minute
Solution:
- Implement exponential backoff
- Batch operations where possible
- Check quota usage in Google Cloud Console
Docker-Specific Issues
"Authentication required" in Docker
Problem: The MCP server in Docker shows authentication errors even though you have valid tokens.
Cause: OAuth flow requires browser access, which isn't available in Docker containers.
Solution:
# 1. Authenticate outside Docker first
npx @piotr-agier/google-drive-mcp auth
# 2. Verify tokens exist
ls -la ~/.config/google-drive-mcp/tokens.json
# 3. Run Docker with tokens mounted
docker run -it \
-v $(pwd)/gcp-oauth.keys.json:/config/gcp-oauth.keys.json:ro \
-v ~/.config/google-drive-mcp/tokens.json:/config/tokens.json \
google-drive-mcp
"npm ci failed" during Docker build
Problem: Docker build fails with tsc: not found
or similar errors.
Solution:
# Build the project locally first
npm install
npm run build
# Then build Docker image
docker build -t google-drive-mcp .
The Dockerfile expects the dist/
directory to exist from your local build.
"Token refresh failed" in Docker
Problem: Tokens can't refresh inside the container.
Solution: Ensure the token file is mounted with write permissions:
# Correct: tokens can be updated
-v ~/.config/google-drive-mcp/tokens.json:/config/tokens.json
# Wrong: read-only mount prevents token refresh
-v ~/.config/google-drive-mcp/tokens.json:/config/tokens.json:ro
Debug Mode
Enable detailed logging:
# Set debug environment variable
export DEBUG=google-drive-mcp:*
npx @piotr-agier/google-drive-mcp
Getting Help
- Check logs: Server logs errors to stderr
- Verify setup: Run
npx @piotr-agier/google-drive-mcp help
- Test auth: Run
npx @piotr-agier/google-drive-mcp auth
- Report issues: GitHub Issues
Development
Project Structure
google-drive-mcp/
āāā src/ # Source code
ā āāā index.ts # Main server implementation
ā āāā auth.ts # Main authentication module
ā āāā auth/ # Authentication components
ā āāā client.ts # OAuth2 client setup
ā āāā server.ts # Local auth server
ā āāā tokenManager.ts # Token storage and validation
ā āāā utils.ts # Auth utilities
āāā dist/ # Compiled JavaScript (generated)
āāā scripts/ # Build scripts
ā āāā build.js # Custom build script
āāā gcp-oauth.keys.json # OAuth credentials (create from example)
āāā gcp-oauth.keys.example.json # Example credentials file
āāā package.json # NPM package configuration
āāā tsconfig.json # TypeScript configuration
āāā LICENSE # MIT license
āāā README.md # This file
Building
npm run build # Compile TypeScript
npm run watch # Compile and watch for changes
npm run typecheck # Type checking without compilation
Scripts
npm start
- Start the compiled servernpm run auth
- Run authentication flownpm run build
- Build the project (runs typecheck + custom build script)npm run watch
- Build and watch for changesnpm run typecheck
- Run TypeScript type checking onlynpm run lint
- Run TypeScript type checking (alias for typecheck)npm run prepare
- Auto-runs build before npm publishnpm test
- Run tests (placeholder - no tests implemented yet)
Advanced Configuration
Environment Variables
User-Configured Variables
Credentials (required - use one of these methods):
Variable | Description | Example |
---|---|---|
GOOGLE_DRIVE_OAUTH_CREDENTIALS | Path to your OAuth credentials JSON file | /home/user/secrets/oauth.json |
(or place file at) | Default location: gcp-oauth.keys.json in project root | ./gcp-oauth.keys.json |
Optional (for customization):
Variable | Description | Default | Example |
---|---|---|---|
GOOGLE_DRIVE_MCP_TOKEN_PATH | Override token storage location | ~/.config/google-drive-mcp/tokens.json | /custom/path/tokens.json |
DEBUG | Enable debug logging | (disabled) | google-drive-mcp:* |
System Variables (used by the codebase if present)
These are standard system environment variables that the application reads but you typically don't need to set:
Variable | Description | Used For |
---|---|---|
XDG_CONFIG_HOME | Linux/Unix config directory standard | Determining default token storage location |
NODE_ENV | Node.js environment mode | May affect error handling and logging |
Deprecated Variables (do not use)
Variable | Description |
---|---|
GOOGLE_TOKEN_PATH | Legacy token path - use GOOGLE_DRIVE_MCP_TOKEN_PATH instead |
GOOGLE_CLIENT_SECRET_PATH | Legacy credentials path - use GOOGLE_DRIVE_OAUTH_CREDENTIALS instead |
License
MIT - See LICENSE file for details
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
Support
- š Documentation
- š Issue Tracker
Acknowledgments
- Built on Model Context Protocol
- Uses Google APIs Node.js Client
- Inspired by the MCP community