Search History MCP Server

Instructions

Implementation Reference

• mcp_server.py:465-606 (handler)

  The core handler function for the 'search_history' tool. It supports searching history across 8 browsers, handles platform differences, database encryption (DuckDuckGo macOS), custom SQL schemas per browser, timestamp conversions, and returns a formatted list of results.
  @mcp.tool def search_history(search_term: str, limit: int = 50, browser: Literal["brave", "safari", "chrome", "firefox", "edge", "arc", "opera", "duckduckgo"] = "brave") -> str: """ Search browser history for URLs and titles containing the search term. Args: search_term: The text to search for in URLs and page titles limit: Maximum number of results to return (default: 50, max: 500) browser: Which browser to search ("brave", "safari", "chrome", "firefox", "edge", "arc", "opera", or "duckduckgo") Returns: Formatted list of matching 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 ? """ # DuckDuckGo needs special handling - decrypt first, then filter all_results = query_duckduckgo_db(query, (limit * 2,)) # Get more results to account for filtering # Filter results by search term after decryption results = [ entry for entry in all_results if search_term.lower() in entry['url'].lower() or search_term.lower() in entry['title'].lower() ][:limit] else: # DuckDuckGo Windows - Chromium-based, no encryption query = """ SELECT url, title, visit_count, last_visit_time FROM urls WHERE (url LIKE ? OR title LIKE ?) AND url NOT LIKE 'https://static.ddg.local/%' ORDER BY last_visit_time DESC LIMIT ? """ search_pattern = f"%{search_term}%" results = query_history_db(query, (search_pattern, search_pattern, 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 WHERE history_items.url LIKE ? OR history_visits.title LIKE ? GROUP BY history_items.url ORDER BY last_visit_time DESC LIMIT ? """ elif browser == "firefox": # Firefox database schema (places.sqlite) query = """ SELECT moz_places.url as url, moz_places.title as title, moz_places.visit_count as visit_count, moz_places.last_visit_date as last_visit_time FROM moz_places WHERE (moz_places.url LIKE ? OR moz_places.title LIKE ?) AND moz_places.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 WHERE url LIKE ? OR title LIKE ? ORDER BY last_visit_time DESC LIMIT ? """ # Query databases (DuckDuckGo already queried above) if browser != "duckduckgo": search_pattern = f"%{search_term}%" results = query_history_db(query, (search_pattern, search_pattern, limit), browser) if not results: return f"No history entries found matching '{search_term}' in {browser.capitalize()}" output = [f"Found {len(results)} {browser.capitalize()} history entries matching '{search_term}':\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:466-476 (schema)

  Type annotations and documentation string defining the input schema (parameters with types and descriptions) and output format for the tool.
  def search_history(search_term: str, limit: int = 50, browser: Literal["brave", "safari", "chrome", "firefox", "edge", "arc", "opera", "duckduckgo"] = "brave") -> str: """ Search browser history for URLs and titles containing the search term. Args: search_term: The text to search for in URLs and page titles limit: Maximum number of results to return (default: 50, max: 500) browser: Which browser to search ("brave", "safari", "chrome", "firefox", "edge", "arc", "opera", or "duckduckgo") Returns: Formatted list of matching history entries with titles, URLs, and visit times
• mcp_server.py:465-465 (registration)

  FastMCP decorator that registers the search_history function as a tool.
  @mcp.tool
• mcp_server.py:158-272 (helper)

  Critical helper function to resolve the correct history database file path for any supported browser and operating system.
  def get_history_db_path(browser: Literal["brave", "safari", "chrome", "firefox", "edge", "arc", "opera", "duckduckgo"] = "brave") -> Path: """ Get the path to the browser history database. Handles cross-platform paths (Windows, macOS, Linux) for various browsers. Safari only supported on macOS. DuckDuckGo and Arc available on macOS and Windows. Args: browser: Which browser to get history from ("brave", "safari", "chrome", "firefox", "edge", "arc", "opera", or "duckduckgo") """ if browser == "duckduckgo": # DuckDuckGo browser paths if os.name == 'nt': # Windows # Try Windows Store version first store_path = find_windows_store_app_path("DuckDuckGo") if store_path: history_path = store_path else: # Fall back to standard installation (Chromium-based, no encryption) history_path = Path.home() / "AppData" / "Local" / "DuckDuckGo" / "User Data" / "Default" / "History" elif platform.system() == 'Darwin': # macOS # DuckDuckGo for macOS (uses encryption) history_path = Path.home() / "Library/Containers/com.duckduckgo.mobile.ios/Data/Library/Application Support/Database.sqlite" else: # Linux raise ValueError("DuckDuckGo is not available on Linux") return history_path if browser == "safari": # Safari only available on macOS if platform.system() != 'Darwin': raise ValueError("Safari is only available on macOS") return Path.home() / "Library" / "Safari" / "History.db" # Chromium-based browsers (Brave, Chrome, Edge) if browser == "chrome": if os.name == 'nt': # Windows history_path = Path.home() / "AppData" / "Local" / "Google" / "Chrome" / "User Data" / "Default" / "History" elif platform.system() == 'Darwin': # macOS history_path = Path.home() / "Library" / "Application Support" / "Google" / "Chrome" / "Default" / "History" else: # Linux history_path = Path.home() / ".config" / "google-chrome" / "Default" / "History" elif browser == "edge": # Microsoft Edge (Chromium-based) if os.name == 'nt': # Windows history_path = Path.home() / "AppData" / "Local" / "Microsoft" / "Edge" / "User Data" / "Default" / "History" elif platform.system() == 'Darwin': # macOS history_path = Path.home() / "Library" / "Application Support" / "Microsoft Edge" / "Default" / "History" else: # Linux history_path = Path.home() / ".config" / "microsoft-edge" / "Default" / "History" elif browser == "arc": # Arc Browser (Chromium-based) if os.name == 'nt': # Windows # Try Windows Store version first store_path = find_windows_store_app_path("Arc") if store_path: history_path = store_path else: # Fall back to standard installation history_path = Path.home() / "AppData" / "Local" / "Arc" / "User Data" / "Default" / "History" elif platform.system() == 'Darwin': # macOS history_path = Path.home() / "Library" / "Application Support" / "Arc" / "User Data" / "Default" / "History" else: # Linux raise ValueError("Arc browser is not available on Linux") elif browser == "opera": # Opera (Chromium-based) if os.name == 'nt': # Windows history_path = Path.home() / "AppData" / "Roaming" / "Opera Software" / "Opera Stable" / "Default" / "History" elif platform.system() == 'Darwin': # macOS history_path = Path.home() / "Library" / "Application Support" / "com.operasoftware.Opera" / "Default" / "History" else: # Linux history_path = Path.home() / ".config" / "opera" / "Default" / "History" elif browser == "firefox": # Firefox uses a different structure with profile folders if os.name == 'nt': # Windows profiles_path = Path.home() / "AppData" / "Roaming" / "Mozilla" / "Firefox" / "Profiles" elif platform.system() == 'Darwin': # macOS profiles_path = Path.home() / "Library" / "Application Support" / "Firefox" / "Profiles" else: # Linux profiles_path = Path.home() / ".mozilla" / "firefox" # Firefox stores history in places.sqlite in the profile directory # Look for the default profile (prioritize .default-release over .default) if profiles_path.exists(): # Try .default-release first (newer Firefox versions) profile_folders = list(profiles_path.glob("*.default-release")) if not profile_folders: # Fall back to .default profile_folders = list(profiles_path.glob("*.default")) if profile_folders: # Check if places.sqlite actually exists in the profile for profile in profile_folders: potential_path = profile / "places.sqlite" if potential_path.exists(): history_path = potential_path break else: raise FileNotFoundError(f"places.sqlite not found in Firefox profile folders at {profiles_path}") else: raise FileNotFoundError(f"Firefox profile folder not found in {profiles_path}") else: raise FileNotFoundError(f"Firefox profiles directory not found at {profiles_path}") else: # brave if os.name == 'nt': # Windows history_path = Path.home() / "AppData" / "Local" / "BraveSoftware" / "Brave-Browser" / "User Data" / "Default" / "History" elif platform.system() == 'Darwin': # macOS history_path = Path.home() / "Library" / "Application Support" / "BraveSoftware" / "Brave-Browser" / "Default" / "History" else: # Linux history_path = Path.home() / ".config" / "BraveSoftware" / "Brave-Browser" / "Default" / "History" return history_path
• mcp_server.py:275-328 (helper)

  Helper to safely execute SQL queries on browser history databases by using temporary copies to prevent file locking issues.
  def query_history_db(query: str, params: tuple = (), browser: Literal["brave", "safari", "chrome", "firefox", "edge", "arc", "opera"] = "brave") -> list: """ Query the browser history database safely by creating a temporary copy. The database may be locked if browser is running, so we copy it first. Args: query: SQL query to execute params: Query parameters browser: Which browser to query ("brave", "safari", "chrome", "firefox", "edge", "arc", or "opera") """ history_path = get_history_db_path(browser) if not history_path.exists(): raise FileNotFoundError(f"{browser.capitalize()} history database not found at {history_path}") # Create a temporary copy of the database to avoid locking issues with tempfile.NamedTemporaryFile(delete=False, suffix='.db') as tmp_file: tmp_path = tmp_file.name try: shutil.copy2(history_path, tmp_path) except PermissionError as e: # Clean up temp file if copy failed if os.path.exists(tmp_path): os.unlink(tmp_path) if browser == "safari": raise PermissionError( f"Permission denied to access Safari history.\n\n" f"To fix this, grant Full Disk Access:\n" f"1. Open System Settings > Privacy & Security > Full Disk Access\n" f"2. Click the '+' button\n" f"3. Add your terminal app (Terminal.app or iTerm.app) or IDE (VS Code, etc.)\n" f"4. Restart the application\n\n" f"Alternatively, you can access Brave history which doesn't require special permissions." ) from e else: raise try: # Query the temporary database conn = sqlite3.connect(tmp_path) conn.row_factory = sqlite3.Row cursor = conn.cursor() cursor.execute(query, params) results = cursor.fetchall() conn.close() return [dict(row) for row in results] finally: # Clean up temporary file if os.path.exists(tmp_path): os.unlink(tmp_path)