Metadata-Version: 2.4
Name: mcp-arxiv
Version: 0.1.0
Summary: MCP server that connects Cursor to the arXiv public API
Author: Mawen Salignat-Moandal
Author-email: Mawen Salignat-Moandal <mwnslgt@gmail.com>
License-Expression: MIT
Requires-Dist: fastmcp>=4.0.2
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.5
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/easimawen/mcp-arxiv
Project-URL: Repository, https://github.com/easimawen/mcp-arxiv
Description-Content-Type: text/markdown

# arXiv MCP for Cursor

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/mcp-arxiv.svg)](https://pypi.org/project/mcp-arxiv/)

Small **MCP server in Python** that connects Cursor (or any MCP client) to the public [arXiv](https://arxiv.org) API — **no API key required**.

```text
Cursor → MCP → arXiv MCP Server → arXiv API
```

- GitHub: https://github.com/easimawen/mcp-arxiv
- PyPI: https://pypi.org/project/mcp-arxiv/ *(after the first publish)*

> The PyPI name `arxiv-mcp` is already taken by another project. This package is published as **`mcp-arxiv`**.

## Tools

| Tool | Purpose |
|------|---------|
| `search_papers` | Search arXiv; return structured metadata |
| `get_paper` | Fetch one paper by arXiv ID |
| `get_recent_papers` | Recent papers in a category (`cs.AI`, `cs.LG`, …) |

Design docs: [RFC-0001](docs/rfc/RFC-0001-arxiv-mcp-mvp.md) · [architecture](docs/architecture.md)

## Requirements

- Python 3.14+
- [uv](https://docs.astral.sh/uv/) (recommended)

## Quick usage (after PyPI publish)

```json
{
  "mcpServers": {
    "arxiv": {
      "command": "uvx",
      "args": ["mcp-arxiv"]
    }
  }
}
```

## Install from the repository

```bash
git clone https://github.com/easimawen/mcp-arxiv.git
cd mcp-arxiv
uv sync
```

Cursor MCP config (use the absolute path to your clone):

```json
{
  "mcpServers": {
    "arxiv": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/mcp-arxiv", "run", "mcp-arxiv"]
    }
  }
}
```

## CLI smoke test

```bash
uv run python -c "
import asyncio
from arxiv_mcp.arxiv_client import ArxivClient

async def main():
    async with ArxivClient() as c:
        p = await c.get_paper('2510.16079')
        print(p.title, p.url)

asyncio.run(main())
"
```

## Development

```bash
uv sync --group dev
uv run pytest
uv run mcp-arxiv
```

## Publish (maintainers)

1. Create a [PyPI](https://pypi.org) account if needed.
2. Add a pending trusted publisher: [PyPI → Publishing](https://pypi.org/manage/account/publishing/)
   - Owner: `easimawen`
   - Repository: `mcp-arxiv`
   - Workflow: `publish.yml`
   - Environment: `pypi`
   - Project name: `mcp-arxiv`
3. On GitHub: Settings → Environments → create `pypi` (optional: require reviewers).
4. Commit + push, then create a GitHub Release `v0.1.0` (tag `v0.1.0`).
5. The workflow `.github/workflows/publish.yml` publishes via OIDC (no long-lived token).

Local build check:

```bash
uv build
# manual publish (fallback):
# export UV_PUBLISH_TOKEN=pypi-...
# uv publish
```

See also [docs/publishing.md](docs/publishing.md).

## License

MIT — see [LICENSE](LICENSE).
