# arXiv MCP Server

An MCP server that lets LLMs search and read papers from arXiv. Works with Claude, Cursor, and other MCP-compatible tools.

## Why I Built This

LLMs hallucinate academic references. They'll confidently cite papers that don't exist, with made-up authors and fabricated titles. The fix is simple: give them direct access to arXiv so they can look up real papers instead of inventing them.

This server lets your AI assistant:
- Search arXiv for actual papers
- Verify a paper exists before citing it
- Read the full paper content, not just the abstract

I added HTML retrieval so the model can actually read papers. For older papers without HTML, it falls back to PDF extraction via [markitdown](https://github.com/microsoft/markitdown) (with pypdf as a backup).

## Features

- Full arXiv API access with all filters (categories, dates, authors, sorting)
- Paper content in markdown format
- Batch fetching for multiple papers
- Category browsing

### How Content Retrieval Works

The server tries multiple sources in order:

1. **arXiv HTML** - Native HTML from arXiv (best quality, newer papers)
2. **ar5iv** - LaTeX converted to HTML (good quality, broad coverage)
3. **markitdown** - PDF to markdown conversion
4. **pypdf** - Basic PDF text extraction (last resort, includes reliability warning)

## Installation

```bash
# From source
git clone https://github.com/SreehariSankar/arxiv-mcp.git
cd arxiv-mcp
pip install -e .

# Or just run directly
pip install mcp httpx pydantic pypdf markitdown
python arxiv_mcp.py
```

## Configuration

### Claude Desktop

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "arxiv": {
      "command": "arxiv-mcp"
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "arxiv-mcp": {
      "command": "arxiv-mcp"
    }
  }
}
```

### HTTP Mode

For remote setups:

```bash
arxiv-mcp --http --port 8000
```

## Tools

### arxiv_search

Search arXiv.

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Search query (supports arXiv syntax: `ti:`, `au:`, `abs:`, `cat:`, `all:`) |
| `categories` | list | Filter by category, e.g. `["cs.LG", "stat.ML"]` |
| `date_from` | string | Start date (YYYY-MM-DD) |
| `date_to` | string | End date (YYYY-MM-DD) |
| `max_results` | int | Results to return (1-100, default 10) |
| `sort_by` | string | `relevance`, `lastUpdatedDate`, or `submittedDate` |

Examples:
```
"transformer attention"
"ti:BERT AND au:devlin"
"cat:cs.LG AND all:reinforcement learning"
```

### arxiv_get_paper

Get metadata for a paper. Accepts IDs like `2301.07041`, `2301.07041v1`, or full URLs.

### arxiv_get_content

Get the full text of a paper as markdown. Returns the content source and a warning if PDF extraction was used.

### arxiv_list_categories

List arXiv categories. Pass `parent_category` (e.g. `cs`, `math`) to filter.

### arxiv_get_paper_batch

Fetch metadata for multiple papers at once (max 20).

## Rate Limits

arXiv allows about 3 requests per second. The server returns helpful error messages if you hit the limit.

## Development

```bash
pip install -e ".[dev]"
pytest
black arxiv_mcp.py
ruff check arxiv_mcp.py
```

## Contributing

PRs welcome. If you find a bug or want to add a feature, open an issue or submit a pull request.

## License

MIT

## Links

- [arXiv API docs](https://arxiv.org/help/api/)
- [ar5iv](https://ar5iv.org/)
- [markitdown](https://github.com/microsoft/markitdown)
- [MCP spec](https://modelcontextprotocol.io/)