Semantic Scholar MCP Server

Instructions

Implementation Reference

• src/semantic_scholar_mcp/server.py:105-105 (registration)

  The @mcp.tool() decorator registers the search_papers function with the FastMCP server.
  @mcp.tool()
• src/semantic_scholar_mcp/server.py:106-173 (handler)

  Core implementation of the search_papers tool: constructs API parameters, calls make_api_request to Semantic Scholar's paper/search endpoint, formats results with format_paper, and returns a formatted string of paper information.
  async def search_papers( query: str, limit: int = 10, offset: int = 0, fields: Optional[str] = None, publication_types: Optional[str] = None, open_access_pdf: Optional[bool] = None, min_citation_count: Optional[int] = None, year: Optional[str] = None, venue: Optional[str] = None, ) -> str: """ Search for academic papers using Semantic Scholar. Args: query: Search query string limit: Maximum number of results (default: 10, max: 100) offset: Number of results to skip (default: 0) fields: Comma-separated list of fields to return publication_types: Filter by publication types open_access_pdf: Filter for papers with open access PDFs min_citation_count: Minimum citation count year: Publication year or year range (e.g., "2020-2023") venue: Publication venue Returns: Formatted search results """ params = {"query": query, "limit": min(limit, 100), "offset": offset} if fields: params["fields"] = fields else: params["fields"] = "paperId,title,authors,year,venue,citationCount,abstract" if publication_types: params["publicationTypes"] = publication_types if open_access_pdf is not None: params["openAccessPdf"] = str(open_access_pdf).lower() if min_citation_count is not None: params["minCitationCount"] = min_citation_count if year: params["year"] = year if venue: params["venue"] = venue result = await make_api_request("paper/search", params) if result is None: return "Error: Failed to fetch results" if "error" in result: return f"Error: {result['error']}" papers = result.get("data", []) total = result.get("total", 0) if not papers: return "No papers found matching your query." formatted_papers = [] for i, paper in enumerate(papers, 1): formatted_papers.append(f"{i}. {format_paper(paper)}") result_text = f"Found {total} total papers (showing {len(papers)}):\n\n" result_text += "\n\n".join(formatted_papers) return result_text
• src/semantic_scholar_mcp/server.py:117-133 (schema)

  The docstring and function signature provide the input schema (parameters with types, defaults, descriptions) and output description for the tool, used by FastMCP for JSON schema generation.
  """ Search for academic papers using Semantic Scholar. Args: query: Search query string limit: Maximum number of results (default: 10, max: 100) offset: Number of results to skip (default: 0) fields: Comma-separated list of fields to return publication_types: Filter by publication types open_access_pdf: Filter for papers with open access PDFs min_citation_count: Minimum citation count year: Publication year or year range (e.g., "2020-2023") venue: Publication venue Returns: Formatted search results """
• src/semantic_scholar_mcp/server.py:24-70 (helper)

  Helper function used by search_papers to make HTTP requests to the Semantic Scholar API, handling authentication, errors, and rate limits.
  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)}"}
• src/semantic_scholar_mcp/server.py:72-91 (helper)

  Helper function used by search_papers to format each paper result into a readable multi-line string.
  def format_paper(paper: Dict[str, Any]) -> str: """Format a paper for display.""" title = paper.get("title", "Unknown Title") authors = paper.get("authors", []) author_names = [author.get("name", "Unknown") for author in authors[:3]] author_str = ", ".join(author_names) if len(authors) > 3: author_str += f" (and {len(authors) - 3} others)" year = paper.get("year") year_str = f" ({year})" if year else "" venue = paper.get("venue", "") venue_str = f" - {venue}" if venue else "" citation_count = paper.get("citationCount", 0) paper_id = paper.get("paperId", "") return f"Title: {title}\nAuthors: {author_str}{year_str}{venue_str}\nCitations: {citation_count}\nPaper ID: {paper_id}"