Search History MCP Server

Instructions

Implementation Reference

• mcp_server.py:609-734 (handler)

  Handler function for the 'get_recent_history' MCP tool. Decorated with @mcp.tool for registration. Queries browser history databases (supporting multiple browsers like Brave, Safari, Chrome, etc.) using specific SQL queries, processes timestamps appropriately for each browser, and returns a formatted string list of recent history entries with titles, URLs, visit counts, and last visit times.

  @mcp.tool
  def get_recent_history(limit: int = 50, browser: Literal["brave", "safari", "chrome", "firefox", "edge", "arc", "opera", "duckduckgo"] = "brave") -> str:
      """
      Get the most recent browsing history entries.
  
      Args:
          limit: Maximum number of results to return (default: 50, max: 500)
          browser: Which browser to query ("brave", "safari", "chrome", "firefox", "edge", "arc", "opera", or "duckduckgo")
  
      Returns:
          Formatted list of recent history entries with titles, URLs, and visit times
      """
      if limit > 500:
          limit = 500
  
      if browser == "duckduckgo":
          if is_duckduckgo_encrypted():
              # DuckDuckGo macOS - encrypted database schema
              query = """
                  SELECT
                      ZURLENCRYPTED,
                      ZTITLEENCRYPTED,
                      ZNUMBEROFTOTALVISITS,
                      ZNUMBEROFTRACKERSBLOCKED,
                      ZLASTVISIT
                  FROM ZHISTORYENTRYMANAGEDOBJECT
                  WHERE ZURLENCRYPTED IS NOT NULL
                  ORDER BY ZLASTVISIT DESC
                  LIMIT ?
              """
              results = query_duckduckgo_db(query, (limit,))
          else:
              # DuckDuckGo Windows - Chromium-based
              query = """
              SELECT url, title, visit_count, last_visit_time
              FROM urls
              WHERE url NOT LIKE 'https://static.ddg.local/%'
              ORDER BY last_visit_time DESC
              LIMIT ?
              """
              results = query_history_db(query, (limit,), browser)
  
      elif browser == "safari":
          # Safari database schema
          query = """
          SELECT
              history_items.url as url,
              history_visits.title as title,
              COUNT(history_visits.id) as visit_count,
              MAX(history_visits.visit_time) as last_visit_time
          FROM history_items
          JOIN history_visits ON history_items.id = history_visits.history_item
          GROUP BY history_items.url
          ORDER BY last_visit_time DESC
          LIMIT ?
          """
      elif browser == "firefox":
          # Firefox database schema (places.sqlite)
          query = """
          SELECT
              url, title, visit_count,
              last_visit_date as last_visit_time
          FROM moz_places
          WHERE hidden = 0
          ORDER BY last_visit_time DESC
          LIMIT ?
          """
      else:
          # Chromium-based browsers (Brave/Chrome/Edge/Arc/Opera) database schema
          query = """
          SELECT url, title, visit_count, last_visit_time
          FROM urls
          ORDER BY last_visit_time DESC
          LIMIT ?
          """
  
      # Query databases (DuckDuckGo already queried above)
      if browser != "duckduckgo":
          results = query_history_db(query, (limit,), browser)
  
      if not results:
          return f"No history entries found in {browser.capitalize()}"
  
      output = [f"Most recent {len(results)} {browser.capitalize()} browsing history entries:\n"]
  
      for i, entry in enumerate(results, 1):
          title = entry['title'] or "No title"
          url = entry['url']
          visit_count = entry['visit_count']
  
          if browser == "duckduckgo":
              if is_duckduckgo_encrypted():
                  # macOS encrypted version has trackers blocked
                  last_visit = cocoa_timestamp_to_datetime(entry['last_visit_time'])
                  trackers_blocked = entry.get('trackers_blocked', 0)
                  output.append(f"{i}. {title}")
                  output.append(f"   URL: {url}")
                  output.append(f"   Visits: {visit_count} | Trackers blocked: {trackers_blocked} | Last visited: {last_visit}")
                  output.append("")
              else:
                  # Windows Chromium version
                  last_visit = chrome_timestamp_to_datetime(entry['last_visit_time'])
                  output.append(f"{i}. {title}")
                  output.append(f"   URL: {url}")
                  output.append(f"   Visits: {visit_count} | Last visited: {last_visit}")
                  output.append("")
          elif browser == "safari":
              last_visit = safari_timestamp_to_datetime(entry['last_visit_time'])
              output.append(f"{i}. {title}")
              output.append(f"   URL: {url}")
              output.append(f"   Visits: {visit_count} | Last visited: {last_visit}")
              output.append("")
          elif browser == "firefox":
              last_visit = firefox_timestamp_to_datetime(entry['last_visit_time'])
              output.append(f"{i}. {title}")
              output.append(f"   URL: {url}")
              output.append(f"   Visits: {visit_count} | Last visited: {last_visit}")
              output.append("")
          else:
              last_visit = chrome_timestamp_to_datetime(entry['last_visit_time'])
              output.append(f"{i}. {title}")
              output.append(f"   URL: {url}")
              output.append(f"   Visits: {visit_count} | Last visited: {last_visit}")
              output.append("")
  
      return "\n".join(output)

• mcp_server.py:609-609 (registration)

  The @mcp.tool decorator registers the get_recent_history function as an MCP tool.

  @mcp.tool

• mcp_server.py:610-620 (schema)

  Type hints and docstring define the input schema (limit: int, browser: Literal[...]), output str, and description for the tool.

  def get_recent_history(limit: int = 50, browser: Literal["brave", "safari", "chrome", "firefox", "edge", "arc", "opera", "duckduckgo"] = "brave") -> str:
      """
      Get the most recent browsing history entries.
  
      Args:
          limit: Maximum number of results to return (default: 50, max: 500)
          browser: Which browser to query ("brave", "safari", "chrome", "firefox", "edge", "arc", "opera", or "duckduckgo")
  
      Returns:
          Formatted list of recent history entries with titles, URLs, and visit times
      """