MCP Headless Gmail Server

Instructions

Implementation Reference

• src/mcp_server_headless_gmail/server.py:78-124 (handler)

  Core handler function in GmailClient class that performs the OAuth2 token refresh using google.oauth2.credentials.Credentials.refresh() with client credentials.

  def refresh_token(self, client_id: str, client_secret: str) -> str:
      """Refresh the access token using the refresh token
      
      Args:
          client_id: Google OAuth2 client ID
          client_secret: Google OAuth2 client secret
      """
      if not self.credentials.refresh_token:
          return json.dumps({
              "error": "No refresh token provided",
              "status": "error"
          })
          
      try:
          # Set client_id and client_secret for refresh
          self.credentials._client_id = client_id
          self.credentials._client_secret = client_secret
          
          # Force refresh
          request = Request()
          self.credentials.refresh(request)
          
          # Get token expiration time
          expiry = self.credentials.expiry
          
          # Return the new access token and its expiration
          return json.dumps({
              "access_token": self.credentials.token,
              "expires_at": expiry.isoformat() if expiry else None,
              "expires_in": int((expiry - datetime.now(expiry.tzinfo)).total_seconds()) if expiry else None,
              "status": "success"
          })
          
      except google.auth.exceptions.RefreshError as e:
          logger.error(f"Token refresh error: {str(e)}")
          return json.dumps({
              "error": "Token refresh failed. Please provide valid client ID and client secret.",
              "details": str(e),
              "status": "error"
          })
      except Exception as e:
          logger.error(f"Exception: {str(e)}")
          return json.dumps({
              "error": str(e),
              "status": "error"
          })

• src/mcp_server_headless_gmail/server.py:543-565 (handler)

  MCP server @server.call_tool() dispatch logic that extracts input arguments, initializes GmailClient, and invokes the refresh_token handler.

  if name == "gmail_refresh_token":
      # For refresh token, we need refresh token, client ID and secret
      refresh_token = arguments.get("google_refresh_token")
      client_id = arguments.get("google_client_id")
      client_secret = arguments.get("google_client_secret")
      access_token = arguments.get("google_access_token")  # Optional for refresh
      
      if not refresh_token:
          raise ValueError("google_refresh_token is required for token refresh")
      
      if not client_id or not client_secret:
          raise ValueError("Both google_client_id and google_client_secret are required for token refresh")
      
      # Initialize Gmail client for token refresh
      gmail = GmailClient(
          access_token=access_token, 
          refresh_token=refresh_token
      )
      
      # Call the refresh_token method
      results = gmail.refresh_token(client_id=client_id, client_secret=client_secret)
      return [types.TextContent(type="text", text=results)]

• src/mcp_server_headless_gmail/server.py:477-489 (registration)

  Tool registration in @server.list_tools() including name, description, and input schema definition.

      name="gmail_refresh_token",
      description="Refresh the access token using the refresh token and client credentials",
      inputSchema={
          "type": "object",
          "properties": {
              "google_access_token": {"type": "string", "description": "Google OAuth2 access token (optional if expired)"},
              "google_refresh_token": {"type": "string", "description": "Google OAuth2 refresh token"},
              "google_client_id": {"type": "string", "description": "Google OAuth2 client ID for token refresh"},
              "google_client_secret": {"type": "string", "description": "Google OAuth2 client secret for token refresh"}
          },
          "required": ["google_refresh_token", "google_client_id", "google_client_secret"]
      },
  ),

• src/mcp_server_headless_gmail/server.py:479-489 (schema)

  Pydantic-style input schema defining parameters for the gmail_refresh_token tool.

      inputSchema={
          "type": "object",
          "properties": {
              "google_access_token": {"type": "string", "description": "Google OAuth2 access token (optional if expired)"},
              "google_refresh_token": {"type": "string", "description": "Google OAuth2 refresh token"},
              "google_client_id": {"type": "string", "description": "Google OAuth2 client ID for token refresh"},
              "google_client_secret": {"type": "string", "description": "Google OAuth2 client secret for token refresh"}
          },
          "required": ["google_refresh_token", "google_client_id", "google_client_secret"]
      },
  ),