Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Instructions

Implementation Reference

• core/server.py:218-250 (handler)

  The primary handler for the 'start_google_auth' tool. Decorated with @server.tool() for MCP registration. Validates inputs, checks client secrets, and delegates to start_auth_flow helper to generate OAuth URL and instructions.
  @server.tool() async def start_google_auth(service_name: str, user_google_email: str = USER_GOOGLE_EMAIL) -> str: """ Manually initiate Google OAuth authentication flow. NOTE: This tool should typically NOT be called directly. The authentication system automatically handles credential checks and prompts for authentication when needed. Only use this tool if: 1. You need to re-authenticate with different credentials 2. You want to proactively authenticate before using other tools 3. The automatic authentication flow failed and you need to retry In most cases, simply try calling the Google Workspace tool you need - it will automatically handle authentication if required. """ if not user_google_email: raise ValueError("user_google_email must be provided.") error_message = check_client_secrets() if error_message: return f"**Authentication Error:** {error_message}" try: auth_message = await start_auth_flow( user_google_email=user_google_email, service_name=service_name, redirect_uri=get_oauth_redirect_uri_for_current_mode() ) return auth_message except Exception as e: logger.error(f"Failed to start Google authentication flow: {e}", exc_info=True) return f"**Error:** An unexpected error occurred: {e}"
• auth/google_auth.py:303-411 (helper)

  Key helper function called by the tool handler. Creates OAuth Flow, generates authorization URL, stores state for callback validation, and returns formatted instructions including the clickable auth URL for the user.
  async def start_auth_flow( user_google_email: Optional[str], service_name: str, # e.g., "Google Calendar", "Gmail" for user messages redirect_uri: str, # Added redirect_uri as a required parameter ) -> str: """ Initiates the Google OAuth flow and returns an actionable message for the user. Args: user_google_email: The user's specified Google email, if provided. service_name: The name of the Google service requiring auth (for user messages). redirect_uri: The URI Google will redirect to after authorization. Returns: A formatted string containing guidance for the LLM/user. Raises: Exception: If the OAuth flow cannot be initiated. """ initial_email_provided = bool( user_google_email and user_google_email.strip() and user_google_email.lower() != "default" ) user_display_name = ( f"{service_name} for '{user_google_email}'" if initial_email_provided else service_name ) logger.info( f"[start_auth_flow] Initiating auth for {user_display_name} with scopes for enabled tools." ) # Note: Caller should ensure OAuth callback is available before calling this function try: if "OAUTHLIB_INSECURE_TRANSPORT" not in os.environ and ( "localhost" in redirect_uri or "127.0.0.1" in redirect_uri ): # Use passed redirect_uri logger.warning( "OAUTHLIB_INSECURE_TRANSPORT not set. Setting it for localhost/local development." ) os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1" oauth_state = os.urandom(16).hex() flow = create_oauth_flow( scopes=get_current_scopes(), # Use scopes for enabled tools only redirect_uri=redirect_uri, # Use passed redirect_uri state=oauth_state, ) auth_url, _ = flow.authorization_url(access_type="offline", prompt="consent") session_id = None try: session_id = get_fastmcp_session_id() except Exception as e: logger.debug(f"Could not retrieve FastMCP session ID for state binding: {e}") store = get_oauth21_session_store() store.store_oauth_state(oauth_state, session_id=session_id) logger.info( f"Auth flow started for {user_display_name}. State: {oauth_state[:8]}... Advise user to visit: {auth_url}" ) message_lines = [ f"**ACTION REQUIRED: Google Authentication Needed for {user_display_name}**\n", f"To proceed, the user must authorize this application for {service_name} access using all required permissions.", "**LLM, please present this exact authorization URL to the user as a clickable hyperlink:**", f"Authorization URL: {auth_url}", f"Markdown for hyperlink: [Click here to authorize {service_name} access]({auth_url})\n", "**LLM, after presenting the link, instruct the user as follows:**", "1. Click the link and complete the authorization in their browser.", ] session_info_for_llm = "" if not initial_email_provided: message_lines.extend( [ f"2. After successful authorization{session_info_for_llm}, the browser page will display the authenticated email address.", " **LLM: Instruct the user to provide you with this email address.**", "3. Once you have the email, **retry their original command, ensuring you include this `user_google_email`.**", ] ) else: message_lines.append( f"2. After successful authorization{session_info_for_llm}, **retry their original command**." ) message_lines.append( f"\nThe application will use the new credentials. If '{user_google_email}' was provided, it must match the authenticated account." ) return "\n".join(message_lines) except FileNotFoundError as e: error_text = f"OAuth client credentials not found: {e}. Please either:\n1. Set environment variables: GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET\n2. Ensure '{CONFIG_CLIENT_SECRETS_PATH}' file exists" logger.error(error_text, exc_info=True) raise Exception(error_text) except Exception as e: error_text = f"Could not initiate authentication for {user_display_name} due to an unexpected error: {str(e)}" logger.error( f"Failed to start the OAuth flow for {user_display_name}: {e}", exc_info=True, ) raise Exception(error_text)
• auth/google_auth.py:251-266 (helper)

  Helper function used by the tool to validate OAuth client secrets configuration before starting the auth flow.
  def check_client_secrets() -> Optional[str]: """ Checks for the presence of OAuth client secrets, either as environment variables or as a file. Returns: An error message string if secrets are not found, otherwise None. """ env_config = load_client_secrets_from_env() if not env_config and not os.path.exists(CONFIG_CLIENT_SECRETS_PATH): logger.error( f"OAuth client credentials not found. No environment variables set and no file at {CONFIG_CLIENT_SECRETS_PATH}" ) return f"OAuth client credentials not found. Please set GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET environment variables or provide a client secrets file at {CONFIG_CLIENT_SECRETS_PATH}." return None