arxiv-mcp
by Tejas242
README.md
<div align="center">
<h1> arXiv MCP Server </h1>
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](https://info.arxiv.org/help/api/)
[](LICENSE)
[](https://github.com/psf/black)
[](https://github.com/tejas242/arxiv-mcp/actions)
[](https://hub.docker.com/r/screenager/arxiv-mcp)
</div>
> *Access the world's largest repository of academic papers through the Model Context Protocol*
A streamlined [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://docs.astral.sh/uv/) package manager
### Installation
#### Option 1: Docker (Recommended)
```bash
# 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
```bash
# 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`
```json
{
"mcpServers": {
"arxiv-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/arxiv-mcp",
"run",
"main.py"
]
}
}
}
```
**For Docker Installation:**
```json
{
"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>
```json
{
"mcp": {
"servers": {
"arxiv-mcp": {
"command": "uv",
"args": ["--directory", "/path/to/arxiv-mcp", "run", "main.py"]
}
}
}
}
```
</details>
## 💡 Usage Examples
### Core Search Operations
```python
# 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
```python
# 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
```bash
uv run pytest tests/ -v
```
### Debug Mode
```bash
# 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](https://arxiv.org/)**
- **[Model Context Protocol](https://modelcontextprotocol.io/)**
---
<div align="center">
[](https://github.com/tejas242/arxiv-mcp)
[](https://github.com/tejas242/arxiv-mcp/issues)
[](https://github.com/tejas242/arxiv-mcp/pulls)
<br><br>
**Made with ⚡ by screenager**
</div>
TDQS
A3.9/5.0
Scored across 7 tools
Disambiguation4/5
Most tools have distinct purposes, but search_by_author and search_by_category are subsets of search_papers, which could cause ambiguity. However, they serve as convenient shortcuts and are clearly named.
Naming Consistency3/5
Naming conventions vary: some use 'search_by_*' while others use 'get_*' or 'download_*'. This mix of verb_noun and verb_preposition_noun patterns is mostly readable but lacks full consistency.
Tool Count5/5
Seven tools is appropriate for an arXiv client, covering search, details, download, and category browsing without being excessive or insufficient.
Completeness4/5
The tool set covers core arXiv operations: searching, retrieving details, downloading papers, and listing categories. Minor gaps exist, like merging multiple search results, but agents can work around them using the general search tool.
Maintenance
ActivityInactive
ResponsivenessNo issues