Backlinks MCP

Instructions

Implementation Reference

• src/seo_mcp/server.py:67-97 (handler)

  Main handler function for the 'get_backlinks_list' tool. Decorated with @mcp.tool() for registration. Orchestrates captcha solving, signature retrieval/caching, and backlinks fetching from Ahrefs.
  @mcp.tool() def get_backlinks_list(domain: str) -> Optional[Dict[str, Any]]: """ Get backlinks list for the specified domain Args: domain (str): The domain to query Returns: List of backlinks for the domain, containing title, URL, domain rating, etc. """ # Try to get signature from cache signature, valid_until, overview_data = load_signature_from_cache(domain) # If no valid signature in cache, get a new one if not signature or not valid_until: # Step 1: Get token site_url = f"https://ahrefs.com/backlink-checker/?input={domain}&mode=subdomains" token = get_capsolver_token(site_url) if not token: raise Exception(f"Failed to get verification token for domain: {domain}") # Step 2: Get signature and validUntil signature, valid_until, overview_data = get_signature_and_overview(token, domain) if not signature or not valid_until: raise Exception(f"Failed to get signature for domain: {domain}") # Step 3: Get backlinks list backlinks = get_backlinks(signature, valid_until, domain) return { "overview": overview_data, "backlinks": backlinks }
• src/seo_mcp/backlinks.py:62-101 (helper)

  Helper function to load cached signature and overview data for a domain, checking validity.
  def load_signature_from_cache(domain: str) -> Tuple[Optional[str], Optional[str], Optional[Dict[str, Any]]]: """ Load signature information for a specific domain from local cache file Returns the signature and valid_until if cache is valid, otherwise None Args: domain: Domain to query Returns: (signature, valid_until) tuple, or (None, None) if no valid cache """ if not os.path.exists(SIGNATURE_CACHE_FILE): return None, None, None try: with open(SIGNATURE_CACHE_FILE, 'r') as f: cache_data = json.load(f) # Check if cache exists for current domain if domain not in cache_data: return None, None, None domain_cache = cache_data[domain] # Check if signature is expired valid_until = domain_cache.get("valid_until") if valid_until: # Convert ISO date string to timestamp for comparison valid_until_timestamp = iso_to_timestamp(valid_until) current_time = time.time() if current_time < valid_until_timestamp: return domain_cache.get("signature"), valid_until, domain_cache.get("overview_data") else: return None, None, None else: return None, None, None except Exception: return None, None, None
• src/seo_mcp/backlinks.py:105-149 (helper)

  Helper to fetch signature and overview from Ahrefs using captcha token, and cache it.
  def get_signature_and_overview(token: str, domain: str) -> Tuple[Optional[str], Optional[str], Optional[Dict[str, Any]]]: """ Get signature and validUntil parameters using the token Args: token: Verification token domain: Domain to query Returns: (signature, valid_until, overview_data) tuple, or (None, None, None) if failed """ url = "https://ahrefs.com/v4/stGetFreeBacklinksOverview" payload = { "captcha": token, "mode": "subdomains", "url": domain } headers = { "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) if response.status_code != 200: return None, None, None data = response.json() try: # Assuming data format is always ['Ok', {signature object}] if isinstance(data, list) and len(cast(List[Any], data)) > 1: second_element: Dict[str, Any] = cast(Dict[str, Any], data[1]) signature: str = cast(str, second_element['signedInput']['signature']) valid_until: str = cast(str, second_element['signedInput']['input']['validUntil']) overview_data: Dict[str, Any] = cast(Dict[str, Any], second_element['data']) # Save the new signature to cache save_signature_to_cache(signature, valid_until, overview_data, domain) return signature, valid_until, overview_data else: return None, None, None except Exception: return None, None, None
• src/seo_mcp/backlinks.py:175-203 (helper)

  Core helper to retrieve the list of backlinks from Ahrefs API using the provided signature and formats the results.
  def get_backlinks(signature: str, valid_until: str, domain: str) -> Optional[List[Any]]: if not signature or not valid_until: return None url = "https://ahrefs.com/v4/stGetFreeBacklinksList" payload = { "reportType": "TopBacklinks", "signedInput": { "signature": signature, "input": { "validUntil": valid_until, "mode": "subdomains", "url": f"{domain}/" } } } headers = { "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) if response.status_code != 200: return None data = response.json() return format_backlinks(data, domain)