arXiv MCP Server

Instructions

Implementation Reference

• src/arxiv_server/server.py:345-412 (handler)

  The core handler for the 'search_arxiv' tool. Decorated with @mcp.tool() for registration in FastMCP. Handles search queries across arXiv fields, calls API, parses results, and returns title-mapped metadata.
  @mcp.tool() async def search_arxiv( ctx: Context, all_fields: Optional[str] = None, title: Optional[str] = None, author: Optional[str] = None, abstract: Optional[str] = None, start: int = 0, max_results: int = 10, ) -> Any: """ Performs a search query on the arXiv API based on specified parameters and returns matching article metadata. This function allows for flexible querying of the arXiv database. Only parameters that are explicitly provided will be included in the final search query. Results are returned in a JSON-formatted string with article titles as keys and their corresponding arXiv IDs as values. Args: all_fields: General keyword search across all metadata fields including title, abstract, authors, comments, and categories. title: Keyword(s) to search for within the titles of articles. author: Author name(s) to filter results by. abstract: Keyword(s) to search for within article abstracts. start: Index of the first result to return; used for paginating through search results. Defaults to 0. max_results: Maximum number of results to return (1-50). Returns: A JSON-formatted string containing article titles and their associated arXiv IDs; otherwise, a structured error JSON string. """ prefixed_params = [] if author: author = format_text(author) prefixed_params.append(f"au:{author}") if all_fields: all_fields = format_text(all_fields) prefixed_params.append(f"all:{all_fields}") if title: title = format_text(title) prefixed_params.append(f"ti:{title}") if abstract: abstract = format_text(abstract) prefixed_params.append(f"abs:{abstract}") # Construct search query search_query = " AND ".join(prefixed_params) params = { "search_query": search_query, "start": start, "max_results": max(1, min(max_results, 50)), } await ctx.info("Calling the API") response = await make_api_call(f"{ARXIV_API_BASE}/query", params=params) if response is None: return _error("API_ERROR", "Unable to retrieve data from arXiv.org.") feed = feedparser.parse(response) error_msg = ( "Unable to extract information for your query. " "This issue may stem from an incorrect search query." ) if not feed.entries: return _error("NOT_FOUND", error_msg) entries: Dict[str, Dict[str, Any]] = {} await ctx.info("Extracting information") for entry in feed.entries: id = entry.id article_title = entry.title arxiv_id = id.split("/abs/")[-1] authors = [author['name'] for author in entry.authors] entries[article_title] = {"arXiv ID": arxiv_id, "Authors": authors} return entries
• src/arxiv_server/server.py:53-67 (helper)

  Helper function used by search_arxiv to make HTTP requests to arXiv API with retry logic.
  async def make_api_call(url: str, params: Dict[str, str]) -> Optional[str]: """Make a request to the arXiv API with retries.""" headers = {"User-Agent": USER_AGENT, "Accept": "application/atom+xml"} async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT, limits=HTTP_LIMITS) as client: for attempt in range(RETRY_ATTEMPTS): try: resp = await client.get(url, params=params, headers=headers) resp.raise_for_status() return resp.text except Exception: if attempt < RETRY_ATTEMPTS - 1: await _retry_sleep(attempt) continue return None
• src/arxiv_server/server.py:143-155 (helper)

  Utility function to format/clean search terms used in search_arxiv queries.
  def format_text(text: str) -> str: """Clean a given text string by removing escape sequences and leading and trailing whitespaces.""" # Remove common escape sequences text_without_escapes = re.sub(r"\\[ntr]", " ", text) # Replace colon with space text_without_colon = text_without_escapes.replace(":", " ") # Remove both single quotes and double quotes text_without_quotes = re.sub(r"['\"]", "", text_without_colon) # Collapse multiple spaces into one text_single_spaced = re.sub(r"\s+", " ", text_without_quotes) # Trim leading and trailing spaces cleaned_text = text_single_spaced.strip() return cleaned_text