Semantic Scholar MCP Server

Instructions

Implementation Reference

• src/semantic_scholar_mcp/server.py:371-394 (handler)

  Handler function implementing the semantic_scholar_recommendations tool. Calls Semantic Scholar's recommendations API using the provided paper_id as seed, retrieves recommended papers, and formats output in Markdown or JSON.
  @mcp.tool(name="semantic_scholar_recommendations") async def get_recommendations(params: PaperRecommendationsInput) -> str: """Get paper recommendations based on a seed paper.""" logger.info(f"Recommendations for: {params.paper_id}") async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client: resp = await client.post( f"https://api.semanticscholar.org/recommendations/v1/papers/forpaper/{params.paper_id}", params={"fields": ",".join(PAPER_FIELDS), "limit": params.limit}, json={"positivePaperIds": [params.paper_id]}, headers=_get_headers() ) resp.raise_for_status() data = resp.json() papers = data.get("recommendedPapers", []) if params.response_format == ResponseFormat.JSON: return json.dumps({"seed": params.paper_id, "recommendations": papers}, indent=2) lines = [f"## Recommendations", f"**Seed:** {params.paper_id}", f"**Found:** {len(papers)}", ""] for paper in papers: lines.append(_format_paper_markdown(paper)) return "\n".join(lines)
• src/semantic_scholar_mcp/server.py:139-144 (schema)

  Pydantic input schema defining parameters for the semantic_scholar_recommendations tool: seed paper_id, number of recommendations, and output format.
  class PaperRecommendationsInput(BaseModel): model_config = ConfigDict(str_strip_whitespace=True, extra="forbid") paper_id: str = Field(..., description="Seed paper ID for recommendations", min_length=1) limit: int = Field(default=10, description="Max recommendations", ge=1, le=100) response_format: ResponseFormat = Field(default=ResponseFormat.MARKDOWN, description="Output format")
• src/semantic_scholar_mcp/server.py:199-248 (helper)

  Helper function to format individual paper data into Markdown, used in the tool's output rendering.
  def _format_paper_markdown(paper: Dict[str, Any]) -> str: lines = [] title = paper.get("title", "Unknown Title") year = paper.get("year", "N/A") lines.append(f"### {title} ({year})") authors = paper.get("authors", []) if authors: names = [a.get("name", "?") for a in authors[:5]] if len(authors) > 5: names.append(f"... +{len(authors)-5} more") lines.append(f"**Authors:** {', '.join(names)}") venue = paper.get("venue") or (paper.get("publicationVenue") or {}).get("name") if venue: lines.append(f"**Venue:** {venue}") citations = paper.get("citationCount", 0) influential = paper.get("influentialCitationCount", 0) lines.append(f"**Citations:** {citations} ({influential} influential)") pdf_info = paper.get("openAccessPdf") or {} if pdf_info.get("url"): lines.append(f"**Open Access:** [PDF]({pdf_info['url']})") fields = paper.get("fieldsOfStudy") or [] if fields: lines.append(f"**Fields:** {', '.join(fields[:5])}") tldr = paper.get("tldr") or {} if tldr.get("text"): lines.append(f"**TL;DR:** {tldr['text']}") abstract = paper.get("abstract") if abstract: lines.append(f"**Abstract:** {abstract[:500]}..." if len(abstract) > 500 else f"**Abstract:** {abstract}") ext_ids = paper.get("externalIds") or {} ids = [] if ext_ids.get("DOI"): ids.append(f"DOI: {ext_ids['DOI']}") if ext_ids.get("ArXiv"): ids.append(f"ArXiv: {ext_ids['ArXiv']}") if ext_ids.get("PubMed"): ids.append(f"PMID: {ext_ids['PubMed']}") if ids: lines.append(f"**IDs:** {', '.join(ids)}") if paper.get("url"): lines.append(f"**Link:** [{paper.get('paperId')}]({paper['url']})") lines.append("") return "\n".join(lines)
• src/semantic_scholar_mcp/server.py:156-160 (helper)

  Helper function providing HTTP headers including optional API key for Semantic Scholar requests.
  def _get_headers() -> Dict[str, str]: headers = {"Accept": "application/json", "Content-Type": "application/json"} if SEMANTIC_SCHOLAR_API_KEY: headers["x-api-key"] = SEMANTIC_SCHOLAR_API_KEY return headers