<div align="center">
<h1> arXiv MCP Server </h1>

</div>

> Access the world's largest repository of academic papers through the Model Context Protocol

A streamlined Model Context Protocol server that connects AI assistants to arXiv's vast collection of academic papers. Search, analyze, and download research papers directly from your AI workflow.

🚀 Quick Start

Prerequisites

- Python 3.12+ - uv package manager

Installation

Option 1: Docker (Recommended)

# Pull and run the Docker image
docker run --rm -it ghcr.io/tejas242/arxiv-mcp:latest
Or using docker-compose
git clone https://github.com/tejas242/arxiv-mcp.git
cd arxiv-mcp
docker compose up

Option 2: Local Development

# Clone and setup
git clone https://github.com/tejas242/arxiv-mcp.git
cd arxiv-mcp
uv sync
Test the server
uv run main.py

🛠️ Available Functions

<div align="center">

| Function | Status | Description | Parameters |
|----------|--------|-------------|------------|
| search_papers | ✅ Working | Search arXiv papers with flexible query syntax | query, max_results, sort_by, sort_order |
| get_paper_details | ✅ Working | Retrieve complete metadata for any arXiv paper | arxiv_id |
| build_advanced_query | ✅ Working | Construct complex search queries with multiple fields | title_keywords, author_name, category, abstract_keywords |
| get_arxiv_categories | ✅ Working | List all available arXiv subject categories | None |
| search_by_author | ⚠️ Limited | Find papers by specific author (use search_papers instead) | author_name, max_results |
| search_by_category | ⚠️ Limited | Browse papers by category (use search_papers instead) | category, max_results |
| download_paper_pdf | 🔧 Needs Fix | Download paper PDFs (redirect handling issue) | arxiv_id, save_path |

</div>

Function Details

✅ Fully Working Functions

search_papers - The primary search function
- Supports full arXiv query syntax
- Handles keywords, authors, categories, titles
- Configurable sorting and pagination
- Returns formatted results with abstracts and links

get_paper_details - Detailed paper information
- Complete metadata extraction
- Author information with affiliations
- Category classifications and links
- Publication dates and updates

build_advanced_query - Query construction helper
- Combines multiple search criteria
- Supports title, author, category, and abstract searches
- Returns properly formatted query strings

get_arxiv_categories - Category reference
- Complete list of arXiv subject categories
- Descriptions for each category
- Helpful for constructing targeted searches

⚠️ Limited Functions (Workarounds Available)

search_by_author - Use search_papers('au:"Author Name"') instead
search_by_category - Use search_papers('cat:category_code') instead

🔧 Functions Needing Fixes

download_paper_pdf - HTTP redirect handling needs improvement
- Currently fails due to HTTPS/HTTP redirect issues
- PDFs can be accessed directly via the links provided in search results

⚙️ Configuration

Claude Desktop Setup

<details>
<summary><strong>Configuration Instructions</strong></summary>

For Local Installation:

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "arxiv-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/arxiv-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

For Docker Installation:

{
  "mcpServers": {
    "arxiv-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/tejas242/arxiv-mcp:latest"
      ]
    }
  }
}

</details>

VS Code MCP Extension

<details>
<summary><strong>VS Code Configuration</strong></summary>

{
  "mcp": {
    "servers": {
      "arxiv-mcp": {
        "command": "uv",
        "args": ["--directory", "/path/to/arxiv-mcp", "run", "main.py"]
      }
    }
  }
}

</details>

💡 Usage Examples

Core Search Operations

# Search for papers about transformers
search_papers("transformer architecture")
Advanced query with specific fields
search_papers('ti:"attention mechanism" AND cat:cs.LG')
Author-specific search (recommended approach)
search_papers('au:"Geoffrey Hinton"')
Category browsing (recommended approach)
search_papers('cat:cs.AI')

Research Workflow

# 1. Find the famous "Attention" paper
search_papers('ti:"Attention Is All You Need"')
get_paper_details("1706.03762")
2. Explore related work
search_papers("transformer neural networks")
3. Build complex queries
query = build_advanced_query(
    title_keywords="few-shot learning",
    author_name="Tom Brown",
    category="cs.LG"
)
search_papers(query)

📊 arXiv Categories Reference

<details>
<summary><strong>Popular Categories</strong></summary>

| Code | Description | Example Topics |
|------|-------------|----------------|
| cs.AI | Artificial Intelligence | Machine learning, neural networks, AI theory |
| cs.LG | Machine Learning | Deep learning, reinforcement learning, statistical learning |
| cs.CV | Computer Vision | Image processing, object detection, visual recognition |
| cs.CL | Computation and Language | NLP, language models, text processing |
| cs.CR | Cryptography and Security | Security protocols, encryption, privacy |
| stat.ML | Machine Learning (Statistics) | Statistical learning theory, Bayesian methods |
| physics.gen-ph | General Physics | Theoretical physics, quantum mechanics |
| math.NA | Numerical Analysis | Computational mathematics, algorithms |
| q-bio.NC | Quantitative Biology | Neuroscience, computational biology |

</details>

Use get_arxiv_categories() for the complete list of available categories.

🧪 Testing Results

Based on comprehensive testing of all functions:

<div align="center">

</div>

✅ Reliable Functions

- Paper search with keywords, authors, categories: 100% success rate - Paper detail retrieval: Complete metadata extraction working - Query construction: All syntax combinations supported - Category listing: All arXiv categories accessible

⚠️ Alternative Approaches Recommended

- Author search: Use search_papers('au:"Author Name"') instead of search_by_author() - Category browsing: Use search_papers('cat:category') instead of search_by_category()

🔧 Known Issues

- PDF downloads: Redirect handling needs improvement (PDFs accessible via direct links)

🔧 Development

Project Structure

arxiv-mcp/
├── src/arxiv_mcp/          # Main package
│   ├── server.py           # MCP server implementation
│   ├── arxiv_client.py     # arXiv API wrapper
│   ├── models.py           # Pydantic data models
│   └── utils.py            # Helper functions
├── tests/                  # Test suite
├── main.py                 # Entry point
└── pyproject.toml         # Project config

Running Tests

uv run pytest tests/ -v

Debug Mode

# Enable detailed logging
PYTHONPATH=src uv run python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from arxiv_mcp.server import main
main()
"

⚠️ Troubleshooting

<details>
<summary><strong>Common Issues & Solutions</strong></summary>

Server Not Detected

- ✅ Verify absolute paths in MCP config - ✅ Test server runs: uv run main.py - ✅ Restart Claude Desktop after config changes

Search Issues

- ✅ Use arXiv query syntax (see examples above) - ✅ Check category names: get_arxiv_categories() - ✅ Try broader search terms - ✅ Use search_papers() instead of specific search functions

PDF Download Failures

- ✅ Access PDFs via links in search results - ✅ Check internet connection - ✅ Verify arXiv ID format (e.g., "1706.03762")

</details>

🙏 Acknowledgments

- arXiv
- Model Context Protocol

---

<div align="center">

<br><br>

Made with ⚡ by screenager

</div>