Search History MCP Server

Instructions

Implementation Reference

• mcp_server.py:737-865 (handler)

  The @mcp.tool decorator registers the tool, and the function implements the logic to retrieve the most frequently visited sites from the browser's history database. It handles different browsers (Brave, Safari, Chrome, Firefox, Edge, Arc, Opera, DuckDuckGo) with specific SQL queries, decryption for DuckDuckGo on macOS, timestamp conversions, and formats the output.
  @mcp.tool def get_most_visited(limit: int = 20, browser: Literal["brave", "safari", "chrome", "firefox", "edge", "arc", "opera", "duckduckgo"] = "brave") -> str: """ Get the most frequently visited sites from browser history. Args: limit: Maximum number of results to return (default: 20, max: 100) browser: Which browser to query ("brave", "safari", "chrome", "firefox", "edge", "arc", "opera", or "duckduckgo") Returns: Formatted list of most visited sites with visit counts """ if limit > 100: limit = 100 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 AND ZNUMBEROFTOTALVISITS > 1 ORDER BY ZNUMBEROFTOTALVISITS 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 visit_count > 1 AND url NOT LIKE 'https://static.ddg.local/%' ORDER BY visit_count 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 HAVING visit_count > 1 ORDER BY visit_count 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 AND visit_count > 1 ORDER BY visit_count DESC LIMIT ? """ else: # Chromium-based browsers (Brave/Chrome/Edge) database schema query = """ SELECT url, title, visit_count, last_visit_time FROM urls WHERE visit_count > 1 ORDER BY visit_count DESC LIMIT ? """ # Query databases (DuckDuckGo already queried above) if browser != "duckduckgo": results = query_history_db(query, (limit,), browser) if not results: return f"No frequently visited sites found in {browser.capitalize()}" output = [f"Top {len(results)} most visited {browser.capitalize()} sites:\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)