Backlinks MCP

Instructions

Implementation Reference

• src/seo_mcp/server.py:100-110 (handler)

  The main handler function for the 'keyword_generator' tool. It is registered via @mcp.tool() decorator, handles input parameters, obtains a CapSolver token, and delegates to get_keyword_ideas for the core logic.
  @mcp.tool() def keyword_generator(keyword: str, country: str = "us", search_engine: str = "Google") -> Optional[List[str]]: """ Get keyword ideas for the specified keyword """ site_url = f"https://ahrefs.com/keyword-generator/?country={country}&input={urllib.parse.quote(keyword)}" token = get_capsolver_token(site_url) if not token: raise Exception(f"Failed to get verification token for keyword: {keyword}") return get_keyword_ideas(token, keyword, country, search_engine)
• src/seo_mcp/keywords.py:54-78 (helper)

  Core helper function that makes API request to Ahrefs keyword generator endpoint using the captcha token and formats the response using format_keyword_ideas.
  def get_keyword_ideas(token: str, keyword: str, country: str = "us", search_engine: str = "Google") -> Optional[List[str]]: if not token: return None url = "https://ahrefs.com/v4/stGetFreeKeywordIdeas" payload = { "withQuestionIdeas": True, "captcha": token, "searchEngine": search_engine, "country": country, "keyword": ["Some", keyword] } 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_keyword_ideas(data)
• src/seo_mcp/server.py:24-65 (helper)

  Helper function to obtain the verification token from CapSolver service, required for bypassing Ahrefs captcha in tool calls.
  def get_capsolver_token(site_url: str) -> Optional[str]: """ Use CapSolver to solve the captcha and get a token Args: site_url: Site URL to query Returns: Verification token or None if failed """ if not api_key: return None payload = { "clientKey": api_key, "task": { "type": 'AntiTurnstileTaskProxyLess', "websiteKey": "0x4AAAAAAAAzi9ITzSN9xKMi", # site key of your target site: ahrefs.com, "websiteURL": site_url, "metadata": { "action": "" # optional } } } res = requests.post("https://api.capsolver.com/createTask", json=payload) resp = res.json() task_id = resp.get("taskId") if not task_id: return None while True: time.sleep(1) # delay payload = {"clientKey": api_key, "taskId": task_id} res = requests.post("https://api.capsolver.com/getTaskResult", json=payload) resp = res.json() status = resp.get("status") if status == "ready": token = resp.get("solution", {}).get('token') return token if status == "failed" or resp.get("errorId"): return None
• src/seo_mcp/keywords.py:6-51 (helper)

  Helper function that parses and formats the raw JSON response from Ahrefs keyword API into a structured list of keyword ideas (regular and questions).
  def format_keyword_ideas(keyword_data: Optional[List[Any]]) -> List[str]: if not keyword_data or len(keyword_data) < 2: return ["\n❌ No valid keyword ideas retrieved"] data = keyword_data[1] result = [] # 处理常规关键词推荐 if "allIdeas" in data and "results" in data["allIdeas"]: all_ideas = data["allIdeas"]["results"] # total = data["allIdeas"].get("total", 0) for idea in all_ideas: simplified_idea = { "keyword": idea.get('keyword', 'No keyword'), "country": idea.get('country', '-'), "difficulty": idea.get('difficultyLabel', 'Unknown'), "volume": idea.get('volumeLabel', 'Unknown'), "updatedAt": idea.get('updatedAt', '-') } result.append({ "label": "keyword ideas", "value": simplified_idea }) # 处理问题类关键词推荐 if "questionIdeas" in data and "results" in data["questionIdeas"]: question_ideas = data["questionIdeas"]["results"] # total = data["questionIdeas"].get("total", 0) for idea in question_ideas: simplified_idea = { "keyword": idea.get('keyword', 'No keyword'), "country": idea.get('country', '-'), "difficulty": idea.get('difficultyLabel', 'Unknown'), "volume": idea.get('volumeLabel', 'Unknown'), "updatedAt": idea.get('updatedAt', '-') } result.append({ "label": "question ideas", "value": simplified_idea }) if not result: return ["\n❌ No valid keyword ideas retrieved"] return result