# arXiv Research MCP

A read-only, deployable MCP server for scientific literature research.

```text
ChatGPT
   ↓  Streamable HTTP
arXiv Research MCP
   ↓  official Atom API
arXiv scientific papers
```

The server retrieves and normalizes metadata. ChatGPT remains responsible for
explaining physics, comparing papers, and working through equations.

## Tools

| Tool | Use |
| --- | --- |
| `search_arxiv` | General keyword or advanced arXiv search with paging and sorting |
| `get_arxiv_paper` | Complete metadata for one modern or legacy arXiv ID |
| `search_arxiv_by_author` | Papers by a named author |
| `search_arxiv_by_category` | Category search with optional keywords |
| `get_recent_arxiv_papers` | Newest submissions in a category |

Every tool is marked read-only and returns typed structured data containing the
arXiv ID, normalized title and abstract, authors, categories, dates, DOI,
journal reference, abstract URL, and PDF URL when available.

## Local setup

Requires Python 3.11 or newer.

```powershell
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
```

Edit `ARXIV_USER_AGENT` in `.env` and replace the example contact with your
email or project URL. arXiv does not require an API key.

Run locally over stdio:

```powershell
arxiv-mcp
```

Run the remote-compatible transport locally:

```powershell
arxiv-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

The endpoints are:

```text
http://127.0.0.1:8000/mcp
http://127.0.0.1:8000/health
```

For a manual tool test, start the HTTP server, run the official MCP Inspector,
and connect it to `http://127.0.0.1:8000/mcp`:

```powershell
npx @modelcontextprotocol/inspector@latest
```

## Run tests

```powershell
pytest
ruff check .
```

Tests use mocked HTTP responses and do not consume the arXiv API. GitHub Actions
runs the same checks on every push and pull request.

## Reliability and security

- Fixed allowlisted upstream: `https://export.arxiv.org/api/query`
- Three-second global request spacing by default
- Bounded retries for timeouts, network failures, HTTP 429, and temporary 5xx responses
- Strict result, offset, category, sort, and arXiv-ID validation
- Safe XML parsing with external entities disabled
- No shell execution, arbitrary URL fetching, secrets, write operations, or user-data storage
- Stateless Streamable HTTP deployment

## Deploy on Render

The repository includes a non-root `Dockerfile` and `render.yaml` Blueprint.

1. Push this repository to GitHub.
2. Sign in to Render and select **New → Blueprint**.
3. Connect the GitHub repository and apply `render.yaml`.
4. In the Render service environment, change `ARXIV_USER_AGENT` to include your
   real contact email or repository URL.
5. Wait for `/health` to pass, then copy the service URL.

The final MCP URL is:

```text
https://<your-render-service>.onrender.com/mcp
```

The Blueprint uses Render's free instance so deployment does not silently create
a billing commitment. Render documents that free services sleep after 15 minutes
of inactivity and can take about a minute to restart. That cold start can exceed
an MCP client's timeout; upgrade the service to `starter` or another paid instance
before relying on it as an always-available production connector. See the
[Render free-tier limitations](https://render.com/docs/free) and
[Blueprint reference](https://render.com/docs/blueprint-spec).

## Connect to ChatGPT

These steps follow the current official OpenAI documentation:

1. Deploy the server and confirm the public HTTPS `/mcp` URL works in MCP Inspector.
2. In ChatGPT, open **Settings → Security and login** and enable **Developer mode**.
3. Open [ChatGPT Plugins](https://chatgpt.com/plugins) and select the **plus** button.
4. Enter:
   - Name: `arXiv Research`
   - Description: `Read-only search and metadata retrieval from the official arXiv API.`
   - Connection: public MCP endpoint
   - Server URL: `https://<your-render-service>.onrender.com/mcp`
   - Authentication: none
5. Create the connection and confirm that exactly five tools are discovered.
6. Start a new chat and add **arXiv Research** from the tools menu.

OpenAI currently requires a public HTTPS endpoint (or its Secure MCP Tunnel) and
Streamable HTTP, typically at `/mcp`. Developer-mode availability depends on the
account and workspace policy. OpenAI's current page does not promise it for every
named ChatGPT plan, so the presence of the Developer mode toggle on your account is
the authoritative check. If a Plus account does not show it, the server remains
usable through MCP Inspector, another MCP client, or the OpenAI API Playground.
See [OpenAI's current connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt)
and [MCP server guide](https://developers.openai.com/plugins/build/mcp-server).

## Example ChatGPT prompts

- `Search arXiv for recent quantum gravity papers.`
- `Find papers about the Bondi-Sachs formalism.`
- `Search hep-th for path integral approaches to gravity.`
- `Find papers by Roger Penrose related to general relativity.`
- `Get the metadata and PDF link for arXiv:2401.12345.`

## Project structure

```text
.
├── src/arxiv_mcp/
│   ├── arxiv_client.py
│   ├── config.py
│   ├── models.py
│   └── server.py
├── tests/
├── .github/workflows/ci.yml
├── .env.example
├── Dockerfile
├── render.yaml
├── pyproject.toml
└── README.md
```

MIT licensed.