arXiv MCP Server

Instructions

Implementation Reference

• src/arxiv_server/server.py:218-278 (handler)

  The core handler function for the 'search_arxiv' MCP tool. It constructs an arXiv API query from optional parameters (all_fields, title, author, abstract, start), fetches the Atom feed, parses it with feedparser, extracts titles, arXiv IDs, and authors, and returns a dictionary of results serialized as string (not JSON.dumps, just dict). Registered via @mcp.tool() decorator.

  @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) -> str:
      """
      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.
  
      Returns:
          A JSON-formatted string containing article titles and their associated arXiv IDs;
          otherwise, a plain error message 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": 10
      }
      await ctx.info("Calling the API")
      response = await make_api_call(f"{ARXIV_API_BASE}/query", params=params)
      if response is None:
          return "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_msg
      entries = {}
      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:94-106 (helper)

  Helper function used by search_arxiv to clean and format search query terms for arXiv API.

  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

• src/arxiv_server/server.py:17-30 (helper)

  Helper function used by search_arxiv to make HTTP requests to the arXiv API and retrieve Atom XML response.

  async def make_api_call(url: str, params: dict[str, str]) -> str | None:
      """Make a request to the arXiv API."""
      headers = {
          "User-Agent": USER_AGENT,
          "Accept": "application/atom+xml"
      }
      async with httpx.AsyncClient() as client:
          try:
              response = await client.get(url, params=params, headers=headers, timeout=30.0)
              response.raise_for_status()
              return response.text
          except Exception:
              return None

• src/arxiv_server/server.py:218-218 (registration)

  The @mcp.tool() decorator registers the search_arxiv function as an MCP tool.

  @mcp.tool()