Metadata-Version: 2.4
Name: arxiv-mcp-search
Version: 0.1.0
Summary: MCP server for arXiv paper search with semantic search, citation enrichment, and PDF extraction
Project-URL: Homepage, https://github.com/Hjh-12138/arxiv-mcp-server
Project-URL: Repository, https://github.com/Hjh-12138/arxiv-mcp-server
Project-URL: Issues, https://github.com/Hjh-12138/arxiv-mcp-server/issues
Author: arxiv-mcp-server contributors
License: MIT
License-File: LICENSE
Keywords: arxiv,mcp,model-context-protocol,papers,pdf-extraction,research,semantic-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pymupdf>=1.24.0
Provides-Extra: dev
Requires-Dist: freezegun; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: responses; extra == 'dev'
Description-Content-Type: text/markdown

# arXiv MCP Server

MCP (Model Context Protocol) server for searching, downloading, and analyzing arXiv papers. Supports keyword search, Semantic Scholar-backed semantic search, PDF text extraction, and SQLite caching.

## Features

- **Keyword Search** — full arXiv API query syntax (`ti:`, `au:`, `cat:`, `all:`)
- **Semantic Search** — server-side semantic search via the Semantic Scholar API
- **Hybrid Search** — arXiv keyword results enriched with Semantic Scholar citation counts
- **PDF Download** — download and extract full text via PyMuPDF
- **Smart Caching** — SQLite cache with configurable TTL (24h metadata, 30-day PDFs)
- **Categories** — built-in taxonomy of ~150 arXiv categories
- **Graceful Degradation** — semantic/hybrid fall back to keyword when Semantic Scholar is unavailable
- **Lightweight** — no local ML model; depends only on `mcp` and `pymupdf`

## Install

```bash
pip install arxiv-mcp-server
```

No model download — the server starts instantly.

## Claude Code Integration

Add to `~/.claude/settings.json` or `.claude/settings.local.json`:

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

Or from a virtual environment:

```json
{
  "mcpServers": {
    "arxiv": {
      "command": "python",
      "args": ["-m", "arxiv_mcp_server.server"]
    }
  }
}
```

## Configuration

All via environment variables:

| Variable | Default | Description |
|---|---|---|
| `ARXIV_CACHE_DIR` | `~/.arxiv-mcp-server` | Cache root (DB + PDFs) |
| `ARXIV_CACHE_TTL_HOURS` | `24` | Metadata cache lifetime |
| `ARXIV_PDF_TTL_DAYS` | `30` | PDF retention period |
| `ARXIV_RATE_LIMIT_SEC` | `1.0` | Min seconds between API calls |
| `ARXIV_REQUEST_TIMEOUT` | `30` | API request timeout (seconds) |
| `ARXIV_MAX_RESULTS` | `50` | Max results per search |
| `ARXIV_LOG_LEVEL` | `INFO` | Python log level |

## Tools

### `search_papers`

Search arXiv papers.

```
query: string (required) — search query
max_results: int (default 10, max 50)
start: int (default 0) — pagination offset
search_mode: "keyword" | "semantic" | "hybrid" (default "hybrid")
```

### `get_paper`

Get a single paper by arXiv ID.

```
arxiv_id: string (required) — e.g. "1706.03762" or "1706.03762v7"
```

### `get_recent`

Get recent papers in a category.

```
category: string (default "cs.AI")
max_results: int (default 20)
```

### `list_categories`

List arXiv categories.

```
parent: string (optional) — filter by parent, e.g. "cs"
```

### `download_pdf`

Download a paper PDF and extract text.

```
arxiv_id: string (required)
output_dir: string (optional) — defaults to ARXIV_CACHE_DIR/pdfs
```

### `get_cached_papers`

List cached papers (diagnostic). No arguments.

## Development

```bash
git clone <repo-url>
cd arxiv-mcp-server
pip install -e ".[dev]"
pytest
```

## License

MIT
