🚀 ArxivSearcher MCP Server

An MCP server for intelligent searching of Software Engineering papers on arXiv, with advanced filtering and sorting.

Updated to v2.0! — This repository has been updated to v2.0: new remote entrypoint, prompt templates, remote-accessible PDF resources, and an upgrade to fastmcp==2.9.2.

📝 Getting Started

Clone the repository

git clone https://github.com/emi-dm/Arxiv-MCP.git
cd Arxiv-MCP

Choose your setup method:

🖱️ Using with Cursor

If you use Cursor, you can integrate this MCP server as follows:

Open Settings in Cursor.
Go to Tools & Integrations.
In the MCP section, add a new server configuration.
Use the same configuration as described for VS Code:
- For Docker, use the Docker configuration block from the VS Code section.
- For local development, use the uv configuration block from the VS Code section.

The process is analogous to the VS Code setup—just copy the relevant configuration and paste it into Cursor's MCP server settings.

📋 Prerequisites

Before you begin, make sure you have installed:

Python (3.11 or higher)
uv (a fast Python package installer and resolver)
Node.js and npm (for debugging with MCP Inspector)

Or alternatively:

Docker (for containerized deployment)

⚡️ Quickstart in VS Code

You can run the server in VS Code using Docker (recommended, you don't need the code locally), locally with uv, or consume it directly from the cloud.

Option 3: Consume the MCP server in the cloud (Recommended for quick testing!)

You don't need to install anything or clone the repository. You can consume the MCP server directly using the following configuration in .vscode/mcp.json or in your compatible MCP client:

{
  "servers": {
    "arxiv-mcp": {
      "url": "https://arxiv-mcp-sq0a.onrender.com/mcp/"
    }
  }
}

This works in both VS Code and Cursor and other compatible MCP clients.

Option 1: Using Docker (Recommended)

Note: If you use Docker, you do not need to have the code in your local directory. The container will run everything needed.

Build the Docker image (only needed once or when you update the code):
```
docker build -t arxiv-searcher-mcp .
```
Create .vscode/mcp.json: In your project root, create the .vscode folder if it doesn't exist. Inside, create a file named mcp.json.

Add the Docker server configuration: Copy and paste the following configuration into .vscode/mcp.json:

{
  "mcpServers": {
    "arxiv-search": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "arxiv-searcher-mcp"
      ]
    }
  }
}

Start the server from VS Code

Option 2: Local configuration with uv (requires code locally)

Create .vscode/mcp.json: In your project root, create the .vscode folder if it doesn't exist. Inside, create un archivo llamado mcp.json.

Agrega la configuración local del servidor: Copia y pega la siguiente configuración en .vscode/mcp.json:

{
  "servers": {
    "arxiv-search": {
      "command": "uv",
      "args": [
        "run",
        "${workspaceFolder}/arxiv_searcher/arxiv_mcp.py"
      ]
    }
  }
}

Inicia el servidor desde VS Code

✨ Features

🛠️ Available Tools

This MCP server exposes several useful tools for searching, analyzing, and exporting arXiv papers in the field of software engineering:

search_papers: Searches arXiv papers filtered by the Software Engineering category (cs.SE).
- Parameters: query, max_results, start_date, end_date, sort_by_relevance, category
- Returns: Dictionary with the query used and the results.
get_paper_details: Gets detailed information about a paper by its arXiv ID.
- Parameters: arxiv_id
- Returns: Title, authors, abstract, dates, categories, DOI, etc.
search_by_author: Searches for papers by author, with optional category and date filters.
- Parameters: author_name, max_results, category, start_date, end_date
- Returns: List of found papers.
analyze_paper_trends: Analyzes trends in a collection of papers (authors, keywords, timeline, categories).
- Parameters: papers, analysis_type
- Returns: Statistics and analysis according to the requested type.
find_related_papers: Finds related papers based on the title of a reference paper, using keyword similarity.
- Parameters: paper_title, max_results, similarity_threshold, category
- Returns: List of similar papers.
download_paper_pdf: Downloads the PDF of an arXiv paper.
- Parameters: pdf_url, save_path, filename
- Returns: Path and status of the download.
export_search_results: Exports search results to various formats (bibtex, csv, json, markdown).
- Parameters: results, format, filename, save_path
- Returns: Path to the exported file and a preview of the content.
get_arxiv_categories: Returns the list of arXiv categories and their descriptions.
- Parameters: None
- Returns: Dictionary of categories and usage notes.

🧑‍💻 Example Usage

Here's how you can call the tool from a compatible MCP client:

@arxiv-search.search_papers(query="secure software development lifecycle from 2022", max_results=5)

This will search for the 5 most relevant papers since 2022 in the software engineering category.

🛠️ Development

📦 Install dependencies

Set up your virtual environment and install the required packages:

uv sync

Or using Docker:

docker build -t arxiv-searcher-mcp .

▶️ Run for development

Start the server directly from your terminal:

uv run --directory arxiv_searcher/ arxiv_mcp.py

🐞 Debugging

For an interactive debugging experience, use MCP Inspector:

# Option 1: Using MCP Inspector
npx @modelcontextprotocol/inspector uv run --directory arxiv_searcher/arxiv_mcp.py

# Option 2: Using fastmcp CLI
fastmcp dev arxiv_searcher/arxiv_mcp.py

When launched, the Inspector will provide a URL to view and debug server communications in your browser. Don't forget to copy the session token!

👤 Author

Developed by emi-dm.

💡 Contributions and improvements are welcome! Feel free to open a Pull Request (PR) if you have suggestions or enhancements.

Version 2.0

Remote-accessible resources: Added MCP resources that allow the server to expose downloaded PDF files and their extracted text (accessible via the data://downloaded_papers resource). This enables remote agents/clients to query the MCP about articles that have been downloaded to the server.
Prompt templates: Included a set of @mcp.prompt templates in the codebase to improve prompt quality and make it easier to craft searches (e.g., search_by_author, search_by_recent_topic, get_paper_by_id, etc.). These templates are available to clients and the Inspector to generate clearer and more consistent requests.
fastmcp update: The project has been updated to use fastmcp==2.9.2 (see requirements.txt / uv.lock). If you manage environments manually, please sync your environment to pick up the new fastmcp release.

Upgrade notes

To query downloaded papers remotely, call the data://downloaded_papers resource from your MCP client or use the provided read helpers in the MCP tools.
Use the prompt templates via the MCP client to get consistent, high-quality queries (the template function names are exported as prompts in the server code).
Run uv sync (or your preferred environment sync command) to install the pinned dependency versions after pulling this release.

📚 License

This project is licensed under the MIT License.