Google Drive MCP Server
A custom Model Context Protocol (MCP) server for Google Drive, Docs, and Sheets. Built for powerful document editing and file management with Claude Code.
Author: Nick Feamster
Quick setup / update (any Mac)
This server is installed and registered for Claude Code and Claude Desktop by
setup-mcp.sh in the dotfiles repo,
along with all the other MCP servers:```bash
cd ~/dotfiles && git pull && ./setup-mcp.sh
Then restart Claude Code and Claude Desktop. (More detail, including upgrading an older Mac: the
laptop-setup README.)
The script clones or pulls every server repo into
`~/src`, builds each environment from its `uv.lock`, writes the config, and checks that each server
starts. It's safe to re-run anytime.
After that, a plain `git pull` in this repo is enough: the server launches with `uv run --frozen`,
which installs any changed dependencies on the next start. Credentials live in `~/.mcp-auth`
(synced from Box with `unison mcp_auth`).
## Features
### Drive Operations
- List files with filtering and sorting
- Search files by content or name
- Get file metadata
- List documents and spreadsheets
### Document Operations
- Get full document structure and content
- Extract plain text from documents
- Create new documents
- Insert, append, and replace text
- Delete content ranges
- Apply text formatting (bold, italic, underline, font size/family)
- Batch update documents with custom requests
### Spreadsheet Operations
- Get spreadsheet metadata and structure
- Read cell values from ranges
- Update cell values
- Create new spreadsheets
## Prerequisites
- Python 3.10+
- Box Drive sync (for credential storage)
- A Google Cloud project with OAuth credentials
- Claude Code installed
## Architecture Overview
This MCP server uses a distributed credential storage approach:
1. **Code Repository** (`~/src/google-drive-mcp/`) - Cloned from GitHub
2. **Credentials Storage** (`~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/`) - OAuth credentials in Box (synced across machines)
3. **MCP Configuration** (`~/.claude/.mcp.json`) - Can be managed via dotfiles repo
This allows:
- Code updates via git pull
- Automatic credential sync via Box
- Easy setup on new machines
## Google Cloud Setup (One-time)
### 1. Create Google Cloud Project
1. Go to Google Cloud Console
2. Create a new project (or use existing)
3. Enable the following APIs:
- Google Docs API
- Google Drive API
- Google Sheets API
### 2. Configure OAuth Consent Screen
1. Go to "APIs & Services" → "OAuth consent screen"
2. Choose "External" user type
3. Fill in required app info:
- App name: "Google Drive MCP"
- Support email: your email
4. Add scopes:
- `https://www.googleapis.com/auth/documents`
- `https://www.googleapis.com/auth/drive`
- `https://www.googleapis.com/auth/spreadsheets`
- `https://www.googleapis.com/auth/script.external_request`
5. Add your email as a **Test User** (important!)
6. Save and continue
7. Click **Publish app** on the Audience page. If you
skip this, the app stays in Testing and Google expires your token every 7 days. See
runbook/token-expired.md.
### 3. Create OAuth 2.0 Credentials
1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "OAuth 2.0 Client ID"
3. Application type: **Desktop app**
4. Name it (e.g., "Google Drive MCP Client")
5. Click "Create"
6. Save the **Client ID** and **Client Secret**
## Two Google accounts
The same server runs once per account. The default token (`tokens/token.json`) is
feamster@gmail.com. `GOOGLE_DRIVE_ACCOUNT=` selects `tokens/token-.json`
instead; `uchicago` is feamster@uchicago.edu, which owns the course documents.```bash
GOOGLE_DRIVE_ACCOUNT=uchicago uv run python -m google_drive_mcp.auth # sign in once, as feamster@uchicago.edu
claude mcp add -s user google-drive-uchicago -e GOOGLE_DRIVE_ACCOUNT=uchicago -- \
/opt/homebrew/bin/uv run --frozen -q --directory ~/src/google-drive-mcp python -m google_drive_mcp.server
Claude Code then has google-drive (gmail) and google-drive-uchicago. Course documents
owned by the UChicago account are also shared with feamster@gmail.com as editor, so either
server can edit them.
Credentials Storage in Box
All OAuth credentials are stored in Box for automatic sync across machines.
Directory Structure```
~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/
├── credentials.json # OAuth Client ID and Secret
└── tokens/
└── token.json # OAuth refresh token (auto-generated)
### Create credentials.json
Create the file in Box with your OAuth credentials:```bash
# Create directory structure
mkdir -p ~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/tokens
# Create credentials.json (replace with your actual credentials from Google Cloud Console)
cat > ~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/credentials.json <<'EOF'
{
"client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
"client_secret": "YOUR_CLIENT_SECRET"
}
EOF
Important: The credentials.json file contains the OAuth Client ID and Secret from your Google Cloud project. These are the same credentials used across all your machines.
Installation
First Machine Setup
- Clone the repository:```bash
cd ~/src
git clone https://github.com/feamster/google-drive-mcp.git
cd google-drive-mcp
2. **Install the package:**```bash
python3 -m pip install -e .
- Verify Box credentials exist:```bash
ls -la ~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/
Should show: credentials.json and tokens/ directory
4. **Run authentication:**```bash
python3 -m google_drive_mcp.auth
This will:
- Open a browser for Google authorization
- Ask you to sign in and grant permissions
- Save the refresh token to Box at ~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/tokens/token.json
- Configure Claude Code:
Add to ~/.claude/.mcp.json:```json
{
"mcpServers": {
"google-drive": {
"command": "python",
"args": ["-m", "google_drive_mcp.server"],
"cwd": "/Users/YOUR_USERNAME/src/google-drive-mcp"
}
}
}
**Note:** If you manage `.mcp.json` via a dotfiles repo, add this configuration there instead.
6. **Restart Claude Code**
### New Machine Setup
When setting up on a new machine (assuming Box is already synced):
1. **Clone the repository:**```bash
cd ~/src
git clone https://github.com/feamster/google-drive-mcp.git
cd google-drive-mcp
- Install the package:```bash
python3 -m pip install -e .
3. **Verify Box is synced with credentials:**```bash
ls -la ~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/
# Should show: credentials.json and tokens/token.json
If the token exists in Box, you're done! The server will use it automatically.
If the token is missing (first-time Box sync), run authentication:```bash
python3 -m google_drive_mcp.auth
4. **Configure Claude Code** (if not using dotfiles):
Add to `~/.claude/.mcp.json` (adjust username):```json
{
"mcpServers": {
"google-drive": {
"command": "python",
"args": ["-m", "google_drive_mcp.server"],
"cwd": "/Users/YOUR_USERNAME/src/google-drive-mcp"
}
}
}
- Restart Claude Code
Testing
Test the server before using it with Claude Code:```bash
cd ~/src/google-drive-mcp
python3 test_server.py
This will:
- Initialize the DocsClient
- List your recent Google Docs and Sheets
- Read content from your first document
- Verify all capabilities are working
Expected output:```
Testing Google Drive MCP Server
==================================================
1. Initializing DocsClient...
✓ Client initialized successfully
2. Listing recent Google Docs...
✓ Found 5 documents
...
All tests passed! ✓
Available Tools (18 total)
Drive Tools (5)
list_files(query?, maxResults?, orderBy?)- List files with optional filtering and sortinglist_documents(maxResults?)- List Google Docs documentslist_spreadsheets(maxResults?)- List Google Sheets spreadsheetssearch_files(searchTerm, maxResults?)- Search for files by name or contentget_file_metadata(fileId)- Get metadata for a specific file
Document Tools (9)
get_document(documentId)- Get full document structure and contentget_document_text(documentId)- Get plain text content from a documentcreate_document(title)- Create a new Google Docs documentinsert_text(documentId, text, index?)- Insert text at a specific indexappend_text(documentId, text)- Append text to the end of a documentreplace_all_text(documentId, findText, replaceText, matchCase?)- Replace all occurrences of textdelete_content_range(documentId, startIndex, endIndex)- Delete content in a specific rangeformat_text(documentId, startIndex, endIndex, bold?, italic?, underline?, fontSize?, fontFamily?)- Apply formatting to a text rangebatch_update_document(documentId, requests)- Execute batch updates (advanced - requires knowledge of Docs API)
Spreadsheet Tools (4)
get_spreadsheet(spreadsheetId)- Get spreadsheet metadata and structureget_sheet_values(spreadsheetId, range)- Get values from a spreadsheet range (A1 notation)update_sheet_values(spreadsheetId, range, values)- Update values in a spreadsheet rangecreate_spreadsheet(title)- Create a new Google Sheets spreadsheet
Usage Examples
List Recent Documents```
Claude: "List my 10 most recent Google Docs"
### Read a Document```
Claude: "Read the content of document ID 1Bdjo1UJSoxUMyr__zaaNU8Dgmlkmtoq3tRCdGcQLM0k"
Edit a Document```
Claude: "In document 1Bdjo1UJSoxUMyr__zaaNU8Dgmlkmtoq3tRCdGcQLM0k, replace all instances of 'old text' with 'new text'"
### Format Text```
Claude: "Make the first paragraph of document XYZ bold and increase font size to 14pt"
Create a New Document```
Claude: "Create a new Google Doc titled 'Meeting Notes' and add an agenda with 3 bullet points"
### Work with Spreadsheets```
Claude: "Read cells A1:D10 from spreadsheet 1IkXxxTBw7onokE0ZEH4RAVrFZBQQOtOEb2F9U6xZ_DE"
Claude: "Update cell A1 in that spreadsheet to say 'Total Revenue'"
Development
Project Structure```
google-drive-mcp/
├── google_drive_mcp/
│ ├── init.py # Package initialization
│ ├── auth.py # OAuth2 authentication with Box integration
│ ├── docs_client.py # Google API client (Drive, Docs, Sheets)
│ └── server.py # MCP server implementation
├── test_server.py # Testing script
├── setup.py # Package setup
├── requirements.txt # Python dependencies
├── .gitignore # Git ignore rules
└── README.md # This file
### Adding New Features
The client (`docs_client.py`) can be extended with additional Google API methods. The server (`server.py`) exposes these as MCP tools.
**Steps to add a new tool:**
1. Add method to `DocsClient` class in `google_drive_mcp/docs_client.py`:```python
def my_new_feature(self, document_id: str, param: str) -> Dict[str, Any]:
"""Description of what this does."""
# Implementation using Google API
...
- Add tool definition to
TOOLSlist ingoogle_drive_mcp/server.py:```python
Tool(
name="my_new_feature",
description="Brief description for Claude",
inputSchema={
"type": "object",
"properties": {
"documentId": {"type": "string", "description": "Document ID"},
"param": {"type": "string", "description": "Parameter description"}
},
"required": ["documentId", "param"]
}
)
3. Add handler in `call_tool()` function in `google_drive_mcp/server.py`:```python
elif name == "my_new_feature":
result = docs.my_new_feature(
document_id=arguments["documentId"],
param=arguments["param"]
)
return [TextContent(type="text", text=json.dumps(result, indent=2))]
- Test and commit:```bash
python3 test_server.py # Verify it works
git add .
git commit -m "Add my_new_feature capability"
git push
### Planned Features
Features to add (based on comparison with other MCP servers):
**Priority 1:**
- [ ] Comments system (list, create, reply, resolve, delete)
- [ ] Image insertion (from URLs or files)
- [ ] Tables and page breaks
- [ ] Advanced text formatting (colors, links, alignment, spacing)
- [ ] File management (move, copy, rename, delete, folders)
**Priority 2:**
- [ ] Markdown conversion and round-trip
- [ ] Sheets formatting (cell colors, alignment, freeze panes, dropdowns)
- [ ] Template support
- [ ] Multi-tab document support
## Troubleshooting
### Authentication Issues
**Problem:** Server stops loading with `invalid_grant: Token has been expired or revoked`
**Solution:** See runbook/token-expired.md. In short: run
`uv run python -m google_drive_mcp.auth`, then reconnect the server. If the app's consent screen is
still in **Testing**, Google expires the token every 7 days. Publishing the app stops that.
**Problem:** "No valid credentials found"
**Solution:**
1. Verify Box is synced: `ls ~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/`
2. Check credentials.json exists and is valid JSON
3. Ensure your email is listed as a Test User in OAuth consent screen
4. Verify all required APIs are enabled in Google Cloud Console
5. Re-run authentication: `python3 -m google_drive_mcp.auth`
### Token Not Found```bash
# Verify Box is synced
ls ~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/tokens/
# Check token contents (should have refresh_token)
cat ~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/tokens/token.json
# Re-authenticate if needed
python3 -m google_drive_mcp.auth
MCP Server Not Loading
- Check Claude Code logs for errors
- Verify the
cwdpath in.mcp.jsonmatches your username:bash whoami # Check your username cat ~/.claude/.mcp.json | grep google-drive - Test the server manually:
bash cd ~/src/google-drive-mcp python3 -m google_drive_mcp.server # Should start without errors (use Ctrl+C to exit) - Verify package is installed:
bash python3 -c "import google_drive_mcp; print(google_drive_mcp.__version__)" # Should print: 0.1.0
Box Sync Issues
Problem: Credentials or tokens not syncing
Solution:
1. Verify Box is running and synced
2. Check Box preferences for selective sync settings
3. Manually verify file exists on Box.com web interface
4. Force sync by touching the file: touch ~/Library/CloudStorage/Box-Box/mcp-auth/google-drive-mcp/tokens/token.json
Dotfiles Repo Integration
If you manage your Claude Code configuration via a dotfiles repo:
- Add
.mcp.jsonto your dotfiles repo - Symlink it:
ln -s ~/dotfiles/.claude/.mcp.json ~/.claude/.mcp.json - Commit and push the configuration
- On new machines, your dotfiles setup script should handle the symlink
Resources
- Google Docs API Reference
- Google Drive API Reference
- Google Sheets API Reference
- Claude Code MCP Documentation
- Google Cloud Console
- MCP Protocol Specification
License
MIT
Support
For issues or questions:
1. Check the Troubleshooting section above
2. Review Google API documentation
3. Test with test_server.py to isolate the problem
4. Check Claude Code logs for detailed error messages