Drive & Docs Management
Relevant source files
The following files were used as context for generating this wiki page:
- packages/google-workspace-mcp/src/google_workspace_mcp/services/drive.py
- packages/google-workspace-mcp/src/google_workspace_mcp/tools/drive.py
- packages/google-workspace-mcp/src/google_workspace_mcp/resources/drive.py
- packages/google-workspace-mcp/README.md
- tests/google-workspace-mcp/integration/test_docs_api.py
- tests/google-workspace-mcp/unit/services/drive/test_read_file.py
Drive & Docs Management is a core capability of the google-workspace-mcp package, enabling AI models to interact with Google Drive and Google Docs through the Model Context Protocol (MCP). This system provides a standardized interface for file operations, including searching, reading, creating, and deleting files and folders, as well as specialized document content manipulation.
The management system acts as a bridge between the AI assistant and the Google Workspace APIs, handling authentication, complex API request construction, and data format conversion (such as converting Google Docs to Markdown). It supports both personal drives and Shared Drives, ensuring comprehensive access control and visibility for enterprise environments.
Sources: packages/google-workspace-mcp/README.md:65-71, packages/google-workspace-mcp/src/google_workspace_mcp/services/drive.py:19-25
Service Architecture
The system is built on a layered architecture where MCP-exposed tools and resources call underlying service classes. The DriveService class, inheriting from BaseGoogleService, encapsulates the logic for interacting with the Google Drive v3 API.
Component Interaction Flow
The following diagram illustrates how a request flows from an MCP tool to the Google Drive API:
Google Drive Operations
The system provides several tools for managing the lifecycle of files and folders within Google Drive.
File Searching and Discovery
Discovery is handled via drive_search_files and specialized resources like drive://recent and drive://shared.
| Feature | Scope | Key Parameters |
|---|---|---|
| Search | Global or Shared Drive | query, page_size, shared_drive_id |
| Recent | User's last 7 days | Hardcoded query: modifiedTime > 'now-7d' |
| Shared | Files shared with user | Hardcoded query: sharedWithMe=true |
| Metadata | Specific File ID | Detailed fields like capabilities, owners, size |
Sources: packages/google-workspace-mcp/src/google_workspace_mcp/services/drive.py:32-75, packages/google-workspace-mcp/src/google_workspace_mcp/resources/drive.py:18-45
Content Retrieval Logic
Retrieval differs based on the file type. Google Workspace applications (Docs, Sheets, Slides) are exported to readable formats, while binary or text files are downloaded directly.
- Google Docs: Exported as
text/markdown. - Google Spreadsheets: Exported as
text/csv. - Google Presentations: Exported as
text/plain. - Regular Files: Downloaded as UTF-8 text if possible, otherwise encoded as Base64.
Sources: packages/google-workspace-mcp/src/google_workspace_mcp/services/drive.py:177-195, tests/google-workspace-mcp/unit/services/drive/test_read_file.py:100-115
Google Docs Management
Google Docs management allows for the creation and manipulation of document content. While the Drive API handles the file-level operations, specific document operations utilize the Google Docs API (as seen in integration tests).
Document Workflow
A typical workflow involves creating a document, appending/prepending text, and retrieving the final state as Markdown.
Content Insertion Methods
The system supports multiple ways to modify a document's content:
- Append: Adds text to the end of the document.
- Prepend: Inserts text at the very beginning (index 1).
- Insert: Places text at a specific 0-based index.
- Batch Update: Executes multiple raw API requests (e.g.,
insertText) in a single call.
Sources: tests/google-workspace-mcp/integration/test_docs_api.py:130-170, packages/google-workspace-mcp/README.md:175-185
Shared Drive Support
The management system is designed for enterprise use, fully supporting Google Shared Drives.
- Listing Drives: The
drive_list_shared_drivestool usesdrives().list()to retrieve accessible shared drives. - Creation Context: When creating folders or uploading files, a
shared_drive_idcan be provided to target a specific drive. - Searching: Search operations use
supportsAllDrives=TrueandincludeItemsFromAllDrives=Trueto ensure visibility across all accessible storage locations.
Sources: packages/google-workspace-mcp/src/google_workspace_mcp/services/drive.py:48-65, packages/google-workspace-mcp/src/google_workspace_mcp/tools/drive.py:149-165
Error Handling and Validation
The service implements robust error translation through handle_api_error.
- HTTP Errors: 404 (Not Found) and 403 (Permission Denied) are captured and returned as structured error dictionaries.
- Input Validation: Tools validate that IDs and names are not empty or whitespace-only before proceeding with API calls.
- Base64 Safety: Uploads include validation of the base64 content to prevent malformed data from reaching the API.
Sources: packages/google-workspace-mcp/src/google_workspace_mcp/services/drive.py:270-285, packages/google-workspace-mcp/src/google_workspace_mcp/tools/drive.py:100-110
Conclusion
Drive & Docs Management provides a comprehensive toolkit for AI models to manage the full lifecycle of digital assets in Google Workspace. By abstracting the complexities of export formats, Shared Drive permissions, and batch updates, it enables precise and automated document and file management within a secure MCP framework.