Advanced Google Workspace Integration Server (MCP)

Bridge your Model Context Protocol (MCP) enabled clients, such as Claude Desktop, directly to your extensive Google Docs and Google Drive ecosystem!

🔥 Explore fifteen powerful operational tasks achievable with this enhanced server infrastructure! 📁 ENHANCEMENT: Full-spectrum Google Drive file system manipulation utilities now included!

Leveraging the MCP framework and the high-performance fastmcp library, this dedicated server provides sophisticated tools for reading, injecting content, applying rich formatting, structuring document layouts, and performing comprehensive file system management across your Google Drive. It functions as a robust gateway, allowing artificial intelligence assistants to interact with your stored documents and files programmatically with deep, granular control.

Core Functionality Modules:

Document Content I/O & Modification

• Content Retrieval: Fetch document body via readGoogleDoc (output formats include raw text, structured JSON representation, or Markdown).
• Content Appending: Append new textual data to existing documents using appendToGoogleDoc.
• Positional Insertion: Inject text precisely at specified offsets using insertText.
• Range Removal: Erase specified content blocks from a document via deleteRange.

Structural & Visual Styling Controls

• Textual Styling: Apply sophisticated visual attributes (e.g., bold, italics, font color, size) using applyTextStyle.
• Paragraph Layout: Control block formatting attributes such as justification and line spacing via applyParagraphStyle.
• Content Targeting & Styling: Format based on text pattern matching (deprecated/legacy support via formatMatchingText).

Document Architecture Manipulation

• Tabular Generation: Construct tables within documents using insertTable.
• Flow Control: Introduce forced page breaks using insertPageBreak.
• List Refinement: Experimental utilities like fixListFormatting for automated list structure correction.

🆕 Collaboration & Comment Thread Handling

• Comment Indexing: Retrieve a catalog of all active comments within a document via listComments (includes metadata: author, timestamp, and quoted snippet).
• Detail Retrieval: Fetch specific comment threads, including all nested replies, using getComment.
• Comment Authoring: Programmatically generate new annotations anchored to specific document ranges using addComment.
• Reply Management: Post responses to existing comment threads via replyToComment.
• Status Update: Mark annotations as addressed/resolved using resolveComment.
• Comment Elimination: Permanently discard specific comments from a document via deleteComment.

🆕 Comprehensive Drive File System Operations

• Discovery & Enumeration: Locate and list available documents using listGoogleDocs, targeted searches via searchGoogleDocs, and retrieval of recent activity via getRecentGoogleDocs.
• Metadata Acquisition: Obtain detailed file properties and attributes using getDocumentInfo.
• Directory Structuring: Create new organizational folders (createFolder), enumerate folder contents (listFolderContents), and query folder specifics (getFolderInfo).
• File Lifecycle Management: Perform re-location (moveFile), duplication (copyFile), renaming (renameFile), and permanent deletion (deleteFile).
• Document Instantiation: Generate fresh, blank documents (createDocument) or instantiate new ones based on existing templates (createFromTemplate).

System Integration & Protocol Compliance

• Authorization Layer: Employs secure OAuth 2.0 protocols, granting comprehensive scoped access to the user's Drive contents.
• MCP Adherence: Engineered specifically for seamless integration with Claude and other client applications adhering to the Model Context Protocol.
• Development Environment Link: Configuration guide provided for integrating with the VS Code MCP extension.

---

Initial System Requirements

To deploy this server instance, ensure you possess the following prerequisites:

1. Runtime Environment: A contemporary installation of Node.js paired with npm (Node Package Manager). Node version 18 or newer is strongly suggested. Obtain from nodejs.org.
2. Version Control: Git must be installed to facilitate repository cloning.
3. Google Identity: An active Google Account with ownership or appropriate access rights to the target documents.
4. CLI Proficiency: Basic familiarity with command-line interfaces (Terminal, PowerShell, Command Prompt).
5. Client Application (Optional): If interfacing with Claude, the Claude Desktop application must be installed.

---

Deployment Procedure

Execute the following stages sequentially to establish and activate your localized server instance.

Stage 1: Google Cloud Project Configuration & Credential Generation (Crucial Step)

This server requires specific programmatic credentials (API keys) to interface with Google's services securely on your behalf.

1. Access Console: Navigate to the Google Cloud Console.
2. Project Selection: Establish a new project (e.g., "AI Docs Bridge") or select an existing one.
3. API Activation: In the API Library search, enable both the Google Docs API and the Google Drive API.
4. OAuth Consent Setup:
   • Navigate to "APIs & Services" -> "OAuth consent screen".
   • Set User Type to "External".
   • Configure App Information (Name, Support Email, Contact Email).
   • In the Scopes section, mandate the following access levels:
   • https://www.googleapis.com/auth/documents
   • https://www.googleapis.com/auth/drive.file
   • On the final review step, designate your primary Google email address as a Test User.
5. Generate Client Credentials:
   • Navigate to "APIs & Services" -> "Credentials".
   • Select "+ CREATE CREDENTIALS" and choose "OAuth client ID".
   • Select "Desktop app" as the Application type.
   • Click "CREATE".
6. Credential Export: A dialog will appear. Click "DOWNLOAD JSON".
   • CRITICAL RENAMING: Rename this downloaded file precisely to credentials.json.
7. ⚠️ SECURITY NOTE: This credentials.json file is highly sensitive; safeguard it and ensure it is never committed to public repositories.

Stage 2: Source Code Acquisition

1. Clone Repository: Execute in your terminal: bash git clone https://github.com/a-bonus/google-docs-mcp.git mcp-googledocs-server
2. Directory Change: bash cd mcp-googledocs-server
3. Credential Placement: Place the renamed credentials.json file into this newly created mcp-googledocs-server directory.

Stage 3: Dependency Installation

Install required libraries listed in package.json:

npm install

Stage 4: Compilation Phase

Convert the TypeScript source code into executable JavaScript:

npm run build

(This creates the necessary runtime files within the dist subdirectory.)

Stage 5: Initial Runtime Execution & Authorization Grant (One-Time Procedure)

This step secures the persistent access token (token.json) necessary for background operation.

1. Start Server Manually: bash node ./dist/server.js
2. Browser Authentication: When prompted in the console with an authorization URL, copy it, paste it into a web browser, and log in using the same Google account used for testing in Stage 1.4.
3. Grant Permissions: Approve the requested permissions.
4. Code Capture: Upon successful authorization, the browser will display an error page. Locate and meticulously copy the OAuth code parameter from the resulting URL.
5. Input Code: Paste this single-use code back into the waiting terminal session and submit by pressing Enter.
6. Verification: The console will confirm successful token storage, resulting in the creation of token.json in the project root.
7. ✅ State Check: The presence of token.json confirms persistent access authorization.
8. ⚠️ SECURITY NOTE: token.json must remain private; it grants immediate access to your Drive data.

Stage 6: Claude Desktop Integration Configuration

To allow Claude Desktop to automatically invoke this server, configure its settings file.

1. Obtain Absolute Path: Determine the full, absolute directory path to your mcp-googledocs-server folder (use pwd or cd command). Example: /home/user/projects/mcp-googledocs-server.
2. Locate mcp_config.json: Access Claude's configuration directory (e.g., %APPDATA%\Claude on Windows or ~/Library/Application Support/Claude/ on macOS).

3. Modify Configuration: Edit or create mcp_config.json to include the server definition. Replace the placeholder path with your actual absolute path:

   json { "mcpServers": { "google-docs-mcp": { "command": "node", "args": [ "/YOUR/ACTUAL/PATH/mcp-googledocs-server/dist/server.js" ], "env": {} } } } 4. Restart Claude Desktop. The server will now launch automatically when a relevant tool call is detected.

---

Operational Usage with Agent Assistants

After successful configuration, prompt Claude to utilize the tools, referencing the server name (google-docs-mcp) and the necessary Document ID:

• "Utilize the google-docs-mcp service to retrieve the contents of the document identified by YOUR_GOOGLE_DOC_ID."
• "Invoke appendToGoogleDoc on document YOUR_GOOGLE_DOC_ID, adding the string 'Integration successful via AI bridge' using the google-docs-mcp tool."

Example Advanced Invocations:

• Styling Directive: "Apply bold formatting and the color hexadecimal #E0115F to all occurrences of the phrase 'Key Metric' within document YOUR_GOOGLE_DOC_ID using formatMatchingText on the google-docs-mcp server."
• Structural Command: "Execute insertTable for a 2x5 grid structure at character offset 1024 within document YOUR_GOOGLE_DOC_ID via the google-docs-mcp toolset."

Note: Substitute YOUR_GOOGLE_DOC_ID with the alphanumeric identifier found in the document's URL (between /d/ and /edit).

---

Security Posture and Persistence

• Git Exclusion: The repository's .gitignore file is configured to explicitly exclude sensitive files (credentials.json, token.json). Do not override this exclusion.
• Token Management: While token.json is stored locally for setup simplicity, production deployments should migrate this authorization token to a more hardened storage mechanism (e.g., encrypted vaults or system keyrings).

---

Common Resolution Pathways (Troubleshooting)

• Client Connection Failure: Verify that the absolute file path within mcp_config.json is precisely correct and that the dist folder is populated post-build.
• Authorization Failures: Reconfirm API enablement (Docs/Drive) and ensure your personal email remains designated as a Test User within the OAuth Consent screen.

---

Licensing Information

This software is distributed under the terms of the MIT License. Refer to the LICENSE file for comprehensive legal details.