Semantic Scholar MCP Server

Instructions

Implementation Reference

• src/semantic_scholar_mcp/server.py:289-333 (handler)

  The core handler function for the 'search_authors' tool. It is decorated with @mcp.tool(), which registers it with the MCP server and generates schema from the signature and docstring. Performs API search for authors, formats results using format_author helper, and returns a formatted string of results.
  @mcp.tool() async def search_authors( query: str, limit: int = 10, offset: int = 0, fields: Optional[str] = None ) -> str: """ Search for authors by name. Args: query: Author name or search query limit: Maximum number of results (default: 10, max: 1000) offset: Number of results to skip (default: 0) fields: Comma-separated list of fields to return Returns: Formatted author search results """ params = {"query": query, "limit": min(limit, 1000), "offset": offset} if fields: params["fields"] = fields else: params["fields"] = "authorId,name,paperCount,citationCount,hIndex" result = await make_api_request("author/search", params) if result is None: return "Error: Failed to fetch authors" if "error" in result: return f"Error: {result['error']}" authors = result.get("data", []) total = result.get("total", 0) if not authors: return "No authors found matching your query." formatted_authors = [] for i, author in enumerate(authors, 1): formatted_authors.append(f"{i}. {format_author(author)}") result_text = f"Found {total} total authors (showing {len(authors)}):\n\n" result_text += "\n\n".join(formatted_authors) return result_text
• src/semantic_scholar_mcp/server.py:94-102 (helper)

  Helper function used by search_authors to format individual author data into a readable string.
  def format_author(author: Dict[str, Any]) -> str: """Format an author for display.""" name = author.get("name", "Unknown Name") author_id = author.get("authorId", "") paper_count = author.get("paperCount", 0) citation_count = author.get("citationCount", 0) h_index = author.get("hIndex", 0) return f"Name: {name}\nAuthor ID: {author_id}\nPapers: {paper_count}\nCitations: {citation_count}\nH-Index: {h_index}"
• src/semantic_scholar_mcp/server.py:24-70 (helper)

  Shared helper function that makes HTTP requests to the Semantic Scholar API, handles errors, and is called by search_authors to fetch author search results.
  async def make_api_request( endpoint: str, params: Optional[Dict[str, Any]] = None, method: str = "GET" ) -> Optional[Dict[str, Any]]: """Make a request to the Semantic Scholar API.""" url = f"{BASE_URL}/{endpoint.lstrip('/')}" headers = { "Accept": "application/json", "User-Agent": f"semantic-scholar-mcp/{USER_AGENT_VERSION}", } if API_KEY: headers["x-api-key"] = API_KEY try: async with httpx.AsyncClient(timeout=API_TIMEOUT) as client: if method == "GET": response = await client.get(url, headers=headers, params=params) elif method == "POST": response = await client.post(url, headers=headers, json=params) else: raise ValueError(f"Unsupported HTTP method: {method}") response.raise_for_status() return response.json() except httpx.HTTPStatusError as e: if e.response.status_code == 403: if not API_KEY: return { "error": "Rate limit exceeded. The shared public rate limit (1000 req/sec) may be exceeded. Get a free API key from https://www.semanticscholar.org/product/api for dedicated limits." } else: return { "error": f"API key may be invalid or rate limit exceeded: {str(e)}" } elif e.response.status_code == 429: return { "error": "Rate limit exceeded. Please wait a moment and try again, or get an API key for dedicated higher limits." } else: return {"error": f"HTTP error: {str(e)}"} except httpx.HTTPError as e: return {"error": f"HTTP error: {str(e)}"} except Exception as e: return {"error": f"Request failed: {str(e)}"}