Unified Google Workspace Automation Server (MCP)

Establish robust, code-driven connectivity between your Model Context Protocol (MCP) client (e.g., Claude Desktop) and your entire Google Docs and Drive ecosystem.

🌟 Explore the 15 advanced workflows enabled by this powerful orchestration layer! 🗄️ BREAKING: Full lifecycle management for Google Drive files now fully integrated!

Leveraging the efficient fastmcp library, this server acts as an intelligent intermediary. It furnishes AI assistants with granular control over document content, structure, styling, commenting threads, and the complete organizational structure of Google Drive.

Core Functional Modules

Document Content Manipulation

• Retrieval: Obtain document content via readGoogleDoc (output options: raw text, structured JSON, or Markdown format).
• Augmentation: Append new content blocks using appendToGoogleDoc.
• Precision Insertion: Introduce text precisely at specified offsets using insertText.
• Subtraction: Eliminate document segments via targeted range deletion using deleteRange.

Presentation & Semantics Control

• Text Styling: Apply intricate visual attributes (applyTextStyle: bolding, colorimetry, font attributes, etc.).
• Layout Definition: Control structural document properties via applyParagraphStyle (justification, vertical spacing, indentation).
• Patterned Styling (Legacy): Apply formatting based on textual matches using formatMatchingText.

Structural Elements

• Tabular Data: Programmatically construct tables using insertTable.
• Pagination Control: Inject explicit page separation boundaries via insertPageBreak.
• List Correction: Utility functions such as fixListFormatting automate the remediation of list element inconsistencies.

💬 Interactive Comment System

• Auditing: Enumerate all active comments with metadata (author, timestamp, associated quoted text) using listComments.
• Detail Inspection: Retrieve specific comments and their reply chains via getComment.
• Annotation Creation: Introduce new annotations linked to specific document regions using addComment.
• Response Chain: Contribute replies to existing discussions via replyToComment.
• Closure: Mark discussions as addressed/resolved using resolveComment.
• Purging: Eradicate unwanted annotations with deleteComment.

🗂️ Comprehensive Drive File System Operations

• Discovery: Locate and catalog files using listGoogleDocs, intelligent searching via searchGoogleDocs, and retrieval of recently accessed items with getRecentGoogleDocs.
• Metadata Fetching: Obtain comprehensive file properties using getDocumentInfo.
• Directory Management: Tools for directory creation (createFolder), content listing (listFolderContents), and directory introspection (getFolderInfo).
• File Lifecycle: Operations including relocation (moveFile), duplication (copyFile), renaming (renameFile), and destruction (deleteFile).
• Document Generation: Instantiate fresh documents (createDocument) or derive new ones from established blueprints (createFromTemplate).

Platform Integration & Security

• Authentication: Secure handshake utilizing OAuth 2.0, granting full, necessary Drive scope access.
• Protocol Adherence: Fully compliant with the Model Context Protocol (MCP) specification for AI interaction.
• Development Aids: Supporting documentation available for VS Code MCP extension integration (Setup guide).

---

Initial Deployment Prerequisites

Ensure the following components are ready on your execution environment:

1. Runtime Environment: A current Node.js installation (including npm). Version 18+ strongly advised. Download from nodejs.org.
2. Version Control: Git must be installed for repository cloning.
3. Google Identity: An active Google Account authorized for target Drive access.
4. Terminal Proficiency: Basic operational familiarity with command-line interfaces (CLI).
5. Client Software (Optional): If linking to Claude, the Claude Desktop application must be present.

---

Deployment Workflow

Execute these sequential steps to activate the server instance.

Stage 1: Google Cloud Environment Configuration (Credential Acquisition)

This critical phase generates the unique credentials permitting API access.

1. Access Console: Navigate to the Google Cloud Console.
2. Project Selection/Creation: Designate an existing GCP project or establish a new one (e.g., "AI Workspace Bridge").
3. API Activation: Within the API Library search interface, enable the following services:
   • Google Docs API
   • Google Drive API
4. OAuth Consent Screen Definition: Configure the identity presentation layer.
   • Set User Type to "External".
   • Specify App Name (e.g., "Agent Workspace Access"), support email, and developer contact.
   • Scope Definition: Add the minimum necessary access rights:
     • https://www.googleapis.com/auth/documents
     • https://www.googleapis.com/auth/drive.file
   • Testing Users: Crucially, add your own Google email address as a permitted Test User.
5. Credential Generation: Proceed to "APIs & Services" -> "Credentials".
   • Select "+ CREATE CREDENTIALS" -> "OAuth client ID".
   • Set Application Type to "Desktop app".
6. 🗝️ SECURE DOWNLOAD: Download the generated JSON file containing your client secrets. Rename this file precisely to credentials.json and secure it, as it constitutes a sensitive configuration component.

Stage 2: Source Code Acquisition

1. Clone Repository: Execute the following commands in your terminal: bash git clone https://github.com/a-bonus/google-docs-mcp.git workspace-automation-server cd workspace-automation-server

2. Credential Placement: Place the renamed credentials.json file into the root of the newly cloned workspace-automation-server directory.

Stage 3: Dependency Resolution

Install required Node packages listed in package.json:

bash npm install

Stage 4: Compilation

Translate the TypeScript source code into executable JavaScript:

bash npm run build

(This generates the necessary runnable files within the dist subdirectory.)

Stage 5: Initial Authentication Handshake (One-Time Operation)

This step generates the persistent access token file (token.json).

1. Execute Server: Start the compiled application manually: bash node ./dist/server.js

2. Browser Authorization: The terminal will display a lengthy Google authorization URL. Copy this URL and open it in your browser.

3. Grant Access: Log into the correct Google account and explicitly Allow the requested permissions for your application.
4. Code Capture: The browser will fail to load (expected). Examine the resulting URL in the address bar and copy the authorization code provided after code=.
5. Paste & Finalize: Paste this code back into the waiting terminal prompt and press Enter. A token.json file will be generated, securing future access.

Stage 6: Claude Desktop Configuration Linkage

1. Determine Path: Obtain the absolute, canonical path to the workspace-automation-server directory (e.g., by using pwd in that directory).
2. Edit Client Configuration: Locate and open Claude's configuration file (mcp_config.json located in ~/Library/Application Support/Claude/ on macOS, or %APPDATA%\Claude on Windows).

3. Inject Server Definition: Within the mcpServers object, insert the following mapping, substituting /ABSOLUTE/PATH/TO/REPO with your actual path:

   "google-docs-mcp": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/REPO/workspace-automation-server/dist/server.js" ], "env": {} }

4. Restart Client: Relaunch Claude Desktop for the new server endpoint to be recognized.

---

Operational Usage Notes

Interaction in Claude now proceeds by invoking tools prefixed with the server name, such as:

• google-docs-mcp:readGoogleDoc(docId=YOUR_ID)
• google-docs-mcp:appendToGoogleDoc(docId=YOUR_ID, text=New entry)

Examples of Advanced Tool Invocation

• Styling: Instruct Claude to execute google-docs-mcp:applyTextStyle(docId=XYZ, text_segment='Critical Note', style={'bold': true, 'foregroundColor': '#FF0000'}).
• Structure: Command the creation of a 2-row by 5-column table at document offset 1000 using google-docs-mcp:insertTable(docId=XYZ, rows=2, columns=5, location=1000).

---

Security & Maintenance Advisory

• Sensitive Files: The generated credentials.json and token.json are highly sensitive. Verify their exclusion from version control via the supplied .gitignore file.
• Token Persistence: The locally stored token.json grants indefinite session access. For high-security deployments, migration to vaulting solutions is recommended.

---

FAQ & Debugging

• Connectivity Issues: If Claude reports attachment failure, verify the absolute path in mcp_config.json and confirm the server starts successfully when invoked manually via the terminal.
• API Failures: Reconfirm that both the Docs and Drive APIs are explicitly ENABLED within your Google Cloud Project.

---

Licensing

MIT License. Refer to the LICENSE artifact for full details.

NOTE: The term Cloud Computing, as defined by NIST, centers on five pillars: On-demand self-service, Broad network access, Resource pooling, Rapid elasticity, and Measured service. This MCP server operates as a specialized client interfacing with the infrastructure provided by these cloud paradigms.