Google Workspace MCP Server

Instructions

Implementation Reference

• gdocs/docs_tools.py:444-487 (handler)

  The main handler function for the 'find_and_replace_doc' tool. It is registered via @server.tool(), requires Docs write access, handles the find-and-replace logic using the Google Docs batchUpdate API, and returns the number of replacements made.

  @server.tool()
  @handle_http_errors("find_and_replace_doc", service_type="docs")
  @require_google_service("docs", "docs_write")
  async def find_and_replace_doc(
      service,
      user_google_email: str,
      document_id: str,
      find_text: str,
      replace_text: str,
      match_case: bool = False,
  ) -> str:
      """
      Finds and replaces text throughout a Google Doc.
  
      Args:
          user_google_email: User's Google email address
          document_id: ID of the document to update
          find_text: Text to search for
          replace_text: Text to replace with
          match_case: Whether to match case exactly
  
      Returns:
          str: Confirmation message with replacement count
      """
      logger.info(f"[find_and_replace_doc] Doc={document_id}, find='{find_text}', replace='{replace_text}'")
  
      requests = [create_find_replace_request(find_text, replace_text, match_case)]
  
      result = await asyncio.to_thread(
          service.documents().batchUpdate(
              documentId=document_id,
              body={'requests': requests}
          ).execute
      )
  
      # Extract number of replacements from response
      replacements = 0
      if 'replies' in result and result['replies']:
          reply = result['replies'][0]
          if 'replaceAllText' in reply:
              replacements = reply['replaceAllText'].get('occurrencesChanged', 0)
  
      link = f"https://docs.google.com/document/d/{document_id}/edit"
      return f"Replaced {replacements} occurrence(s) of '{find_text}' with '{replace_text}' in document {document_id}. Link: {link}"

• gdocs/docs_helpers.py:157-181 (helper)

  Supporting helper function that constructs the exact Google Docs API request object for the replaceAllText operation used by the find_and_replace_doc handler.

  def create_find_replace_request(
      find_text: str, 
      replace_text: str, 
      match_case: bool = False
  ) -> Dict[str, Any]:
      """
      Create a replaceAllText request for Google Docs API.
      
      Args:
          find_text: Text to find
          replace_text: Text to replace with
          match_case: Whether to match case exactly
      
      Returns:
          Dictionary representing the replaceAllText request
      """
      return {
          'replaceAllText': {
              'containsText': {
                  'text': find_text,
                  'matchCase': match_case
              },
              'replaceText': replace_text
          }
      }