Google Custom Search Engine MCP Server

Instructions

Implementation Reference

• src/mcp_google_cse/server.py:54-82 (handler)

  The core implementation of the google_search tool. It builds a Google Custom Search service, executes the search query with the provided search_term and environment-configured parameters, cleans the snippets, formats results into TextContent objects with title, link, and snippet, and returns the list.

  async def google_search(search_term: str) -> List[TextContent]:
      """
      Search the custom search engine using the search term.
      :param search_term: The search term to search for, equaling the q argument in Google's search.
      :return: Search results containing the title, link and snippet of the search result.
      """
      service = build(os.getenv('SERVICE_NAME', 'customsearch'), "v1", developerKey=os.getenv('API_KEY'))
      response = service.cse().list(
          q=search_term,
          cx=os.getenv('ENGINE_ID'),
          cr=os.getenv('COUNTRY_REGION'),
          gl=os.getenv('GEOLOCATION', 'us'),
          lr=os.getenv('RESULT_LANGUAGE', 'lang_en'),
          num=os.getenv('RESULT_NUM', 10),
          fields='items(title,link,snippet)').execute()
      results = response['items']
      __clean_up_snippets(results)
  
      text_contents = []
  
      for result in results:
          text_contents.append(
              TextContent(
                  type="text",
                  text=f"Title: {result['title']}\nLink: {result['link']}\nSnippet: {result['snippet']}"
              )
          )
  
      return text_contents

• src/mcp_google_cse/server.py:16-35 (registration)

  Registers the 'google_search' tool with the MCP server via the list_tools handler, providing name, description, and input schema.

  @server.list_tools()
  async def handle_list_tools() -> list[Tool]:
      """
      List available tools.
      Each tool specifies its arguments using JSON Schema validation.
      """
      return [
          Tool(
              name="google_search",
              description="Search the custom search engine using the search term. Regular query arguments can also be used, like appending site:reddit.com or after:2024-04-30. If available and/or requested, the links of the search results should be used in a follow-up request using a different tool to get the full content. Example: \"claude.ai features site:reddit.com after:2024-04-30\"",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "search_term": {"type": "string"},
                  },
                  "required": ["search_term"],
              }
          )
      ]

• src/mcp_google_cse/server.py:26-32 (schema)

  Defines the input JSON schema for the google_search tool, requiring a 'search_term' string property.

  inputSchema={
      "type": "object",
      "properties": {
          "search_term": {"type": "string"},
      },
      "required": ["search_term"],
  }

• src/mcp_google_cse/server.py:85-93 (helper)

  Helper function called by the google_search handler to clean up snippets in search results by replacing non-breaking spaces (\xa0) with regular spaces and stripping trailing whitespace.

  def __clean_up_snippets(items: List[dict]) -> None:
      """
      Remove non-breaking space and trailing whitespace from snippets.
      :param items: The search results that contain snippets that have to be cleaned up.
      :return: Nothing, the dict is mutable and updated directly.
      """
      for item in items:
          item.update({k: v.replace('\xa0', ' ').strip() if k == 'snippet' else v for k, v in item.items()})