├── requirements.txt ├── .gitignore ├── LICENSE ├── README.md └── semantic-scholar-plugin.py /requirements.txt: -------------------------------------------------------------------------------- 1 | mcp>=1.3.0 2 | aiohttp 3 | pydantic 4 | uvicorn -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /__pycache__ 2 | /.vscode 3 | /.notebook 4 | .python-version 5 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Benhao Tang and other contributors to this project 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Semantic Scholar API MCP server 2 | 3 | Made with [mcp-python-sdk](https://github.com/modelcontextprotocol/python-sdk) 4 | 5 | > [!IMPORTANT] 6 | > if you are still using FastMCP version of this mcp server, please consider pull this repo again and update to newer versions as FastMCP is already deprecated. 7 | 8 | ## Usage 9 | 10 | Requirements: `pip install -r requirements.txt` 11 | 12 | Run `mcp dev path/to/semantic-scholar-plugin.py` to initialize the server. 13 | 14 | Run `mcp install path/to/semantic-scholar-plugin.py` to install to claude or add following to claude/cline config: 15 | 16 | ```json 17 | "semantic-scholar": { 18 | "command": "uv", 19 | "args": [ 20 | "run", 21 | "--with", 22 | "mcp", 23 | "mcp", 24 | "run", 25 | "/path/to/semantic-scholar-plugin.py" 26 | ] 27 | } 28 | ``` 29 | 30 | > [!NOTE] 31 | > Currently using `uv` with `mcp` seems to break certain Linux/macOS version of Claude-desktop, you might need to set as: 32 | > ```json 33 | > "semantic-scholar": { 34 | > "command": "/path/to/mcp", 35 | > "args": [ 36 | > "run", 37 | > "/path/to/semantic-scholar-plugin.py" 38 | > ] 39 | > } 40 | > ``` 41 | > instead, with `/path/to/mcp` got from running `which mcp` in terminal 42 | 43 | ## API Key 44 | 45 | To use the Semantic Scholar API with higher rate limits, you can set your API key as an environment variable: 46 | 47 | ```bash 48 | export SEMANTIC_SCHOLAR_API_KEY="your_api_key" 49 | ``` 50 | 51 | or set by adding an `env` key in mcp settings by: 52 | 53 | ```json 54 | "semantic-scholar": { 55 | "command": ..., 56 | "args": ..., 57 | "env": { 58 | "SEMANTIC_SCHOLAR_API_KEY": "your_api_key" 59 | } 60 | } 61 | ``` 62 | 63 | You can get an API key by filling out the form at: https://www.semanticscholar.org/product/api 64 | 65 | ## Suggested Agent System prompt 66 | 67 | See: [benhaotang/my_agent_system_prompt](https://github.com/benhaotang/my_agent_system_prompt/blob/main/msty_ai_preresearch.md), the AI pre-research agent that can make full use of this mcp server. 68 | 69 | ## Known issues 70 | 71 | - If you see things like `INFO Processing request of type __init__.py:431 ListToolsRequest` in cline, you can ignore them as this will not affect it from working, this is because cline parse tool list together with console debug infos, and current python-sdk cannot disable console messages. This will not affect any function calling part other than seeing this warning. 72 | -------------------------------------------------------------------------------- /semantic-scholar-plugin.py: -------------------------------------------------------------------------------- 1 | from mcp.server.fastmcp import FastMCP 2 | import httpx 3 | from typing import Optional 4 | import os 5 | from pydantic import Field 6 | import logging 7 | 8 | # Setup logging 9 | logging.basicConfig(level=logging.INFO) 10 | logger = logging.getLogger("semantic-scholar-mcp") 11 | 12 | # Get API key from environment variable 13 | API_KEY = os.environ.get("SEMANTIC_SCHOLAR_API_KEY") 14 | 15 | # Create the MCP server with configuration 16 | mcp = FastMCP( 17 | "Semantic Scholar Search 📚", 18 | dependencies=["httpx", "pydantic"] 19 | ) 20 | 21 | # Constants 22 | FIELDS = ','.join(['title', 'year', 'authors', 'venue', 'citationCount', 'externalIds', 'abstract', 'url']) 23 | BASE_URL = 'https://api.semanticscholar.org/graph/v1/paper/search' 24 | 25 | @mcp.tool() 26 | async def search_papers_via_semanticscholar( 27 | keyword: str = Field(..., description="Search query for academic papers (e.g., 'quantum computing')"), 28 | limit: int = Field(10, description="Maximum number of results to return", ge=1, le=25), 29 | year_from: Optional[int] = Field(None, description="Filter papers from this year onwards"), 30 | year_to: Optional[int] = Field(None, description="Filter papers up to this year") 31 | ) -> str: 32 | """ 33 | Search for academic papers and research articles across multiple disciplines using Semantic Scholar's database. 34 | Returns formatted results with titles, authors, abstracts, and citations. 35 | """ 36 | # Build the query params 37 | params = { 38 | 'query': keyword, 39 | 'limit': str(limit), 40 | 'fields': FIELDS 41 | } 42 | 43 | if year_from or year_to: 44 | year_filter = "" 45 | if year_from and year_to: 46 | year_filter = f"{year_from}-{year_to}" 47 | elif year_from: 48 | year_filter = f"{year_from}-" 49 | elif year_to: 50 | year_filter = f"-{year_to}" 51 | params['year'] = year_filter 52 | 53 | try: 54 | # Prepare headers with API key if available 55 | headers = {} 56 | if API_KEY: 57 | headers['x-api-key'] = API_KEY 58 | logger.info("Using Semantic Scholar API key") 59 | 60 | # Make the request 61 | async with httpx.AsyncClient(timeout=30.0) as client: 62 | logger.info(f"Querying Semantic Scholar API with params: {params}") 63 | response = await client.get(BASE_URL, params=params, headers=headers) 64 | response.raise_for_status() # Raise exception for non-200 responses 65 | data = response.json() 66 | except httpx.HTTPStatusError as e: 67 | error_msg = f"HTTP error occurred: {e.response.status_code} - {e.response.text}" 68 | logger.error(error_msg) 69 | return f"Error: Failed to retrieve data from Semantic Scholar API. {error_msg}" 70 | except httpx.RequestError as e: 71 | error_msg = f"Request error occurred: {str(e)}" 72 | logger.error(error_msg) 73 | return f"Error: Failed to connect to Semantic Scholar API. {error_msg}" 74 | except Exception as e: 75 | error_msg = f"Unexpected error: {str(e)}" 76 | logger.error(error_msg) 77 | return f"Error: An unexpected error occurred. {error_msg}" 78 | 79 | if not data.get('data'): 80 | return "No papers found matching your search criteria." 81 | 82 | # Format the results 83 | markdown = f"## Academic Search Results\n" 84 | markdown += f"📚 Found {data.get('total', 0):,} papers. Showing {len(data['data'])} recent results:\n\n" 85 | 86 | for index, paper in enumerate(data['data'], 1): 87 | # Title with year 88 | markdown += f"### {index}. {paper.get('title', 'Untitled')} ({paper.get('year', 'N/A')})\n\n" 89 | 90 | # Publication and impact 91 | markdown += f"📍 **Publication:** {paper.get('venue', 'N/A')}\n" 92 | citations = paper.get('citationCount', 0) 93 | markdown += f"📊 **Impact:** {citations} citation{'s' if citations != 1 else ''}\n" 94 | 95 | # Authors 96 | if paper.get('authors'): 97 | markdown += "👥 **Research Team:** " 98 | authors = paper['authors'][:3] 99 | author_names = [] 100 | for author in authors: 101 | name_parts = author.get('name', '').split() 102 | if name_parts: 103 | last_name = name_parts[-1] 104 | initials = '.'.join(part[0] for part in name_parts[:-1]) 105 | author_names.append(f"{last_name}, {initials}." if initials else last_name) 106 | 107 | markdown += ', '.join(author_names) 108 | if len(paper['authors']) > 3: 109 | markdown += ' et al.' 110 | markdown += '\n' 111 | 112 | # DOI 113 | if paper.get('externalIds', {}).get('DOI'): 114 | doi = paper['externalIds']['DOI'] 115 | markdown += f"🔗 **DOI:** [{doi}](https://doi.org/{doi})\n" 116 | 117 | # Abstract 118 | if paper.get('abstract'): 119 | markdown += f"📝 **Abstract:** {paper['abstract']}\n" 120 | 121 | # URL 122 | if paper.get('url'): 123 | markdown += f"🌐 **URL:** [Link]({paper['url']})\n" 124 | 125 | markdown += "\n---\n\n" 126 | 127 | return markdown 128 | 129 | if __name__ == "__main__": 130 | logger.info("Starting Semantic Scholar MCP server...") 131 | mcp.run() 132 | --------------------------------------------------------------------------------