arXiv Research MCP

과학 문헌 연구를 위한 읽기 전용, 배포 가능한 MCP 서버입니다.

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

이 서버는 메타데이터를 검색하고 정규화합니다. 물리학 설명, 논문 비교, 방정식 풀이는 ChatGPT가 담당합니다.

도구

모든 도구는 읽기 전용으로 표시되며, arXiv ID, 정규화된 제목과 초록, 저자, 카테고리, 날짜, DOI, 저널 참조, 초록 URL, PDF URL(가능한 경우)을 포함하는 형식화된 구조적 데이터를 반환합니다.

로컬 설정

Python 3.11 이상이 필요합니다.

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

.env에서 ARXIV_USER_AGENT를 편집하고 예시 연락처를 본인의 이메일 또는 프로젝트 URL로 바꾸세요. arXiv는 API 키를 요구하지 않습니다.

stdio로 로컬 실행:

arxiv-mcp

원격 호환 전송을 로컬에서 실행:

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

엔드포인트는 다음과 같습니다:

http://127.0.0.1:8000/mcp
http://127.0.0.1:8000/health

수동 도구 테스트를 위해 HTTP 서버를 시작하고, 공식 MCP Inspector를 실행한 후 http://127.0.0.1:8000/mcp에 연결하세요:

npx @modelcontextprotocol/inspector@latest

테스트 실행

pytest
ruff check .

테스트는 모의 HTTP 응답을 사용하며 arXiv API를 소비하지 않습니다. GitHub Actions는 모든 푸시와 풀 리퀘스트에서 동일한 검사를 실행합니다.

안정성 및 보안

• 고정된 허용 목록 업스트림: https://export.arxiv.org/api/query

• 기본적으로 3초 간격의 전역 요청 간격

• 시간 초과, 네트워크 오류, HTTP 429, 일시적인 5xx 응답에 대한 제한된 재시도

• 엄격한 결과, 오프셋, 카테고리, 정렬, arXiv ID 검증

• 외부 엔터티가 비활성화된 안전한 XML 파싱

• 셸 실행, 임의 URL 가져오기, 비밀 정보, 쓰기 작업, 사용자 데이터 저장 없음

• 상태 비저장 Streamable HTTP 배포

Render에 배포

이 저장소에는 비루트 Dockerfile과 render.yaml Blueprint가 포함되어 있습니다.

1. 이 저장소를 GitHub에 푸시하세요.

2. Render에 로그인하고 New → Blueprint를 선택하세요.

3. GitHub 저장소를 연결하고 render.yaml을 적용하세요.

4. Render 서비스 환경에서 ARXIV_USER_AGENT를 실제 연락처 이메일 또는 저장소 URL을 포함하도록 변경하세요.

5. /health가 통과할 때까지 기다린 후 서비스 URL을 복사하세요.

최종 MCP URL은 다음과 같습니다:

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

Blueprint는 Render의 무료 인스턴스를 사용하므로 배포 시 자동으로 결제 약정이 발생하지 않습니다. Render는 무료 서비스가 15분간 비활성 상태 후 절전 모드로 전환되고 다시 시작하는 데 약 1분이 걸릴 수 있다고 문서화합니다. 이러한 콜드 스타트는 MCP 클라이언트의 시간 초과를 초과할 수 있습니다. 항상 사용 가능한 프로덕션 커넥터로 사용하려면 서비스를 starter 또는 다른 유료 인스턴스로 업그레이드하세요. Render 무료 티어 제한 사항 및 Blueprint 참조를 참조하세요.

ChatGPT에 연결

다음 단계는 현재 공식 OpenAI 문서를 따릅니다:

1. 서버를 배포하고 공개 HTTPS /mcp URL이 MCP Inspector에서 작동하는지 확인하세요.

2. ChatGPT에서 Settings → Security and login을 열고 Developer mode를 활성화하세요.

3. ChatGPT Plugins을 열고 더하기 버튼을 선택하세요.

4. 다음을 입력하세요:

   • 이름: arXiv Research

   • 설명: Read-only search and metadata retrieval from the official arXiv API.

   • 연결: 공개 MCP 엔드포인트

   • 서버 URL: https://<your-render-service>.onrender.com/mcp

   • 인증: 없음

5. 연결을 생성하고 정확히 5개의 도구가 발견되는지 확인하세요.

6. 새 채팅을 시작하고 도구 메뉴에서 arXiv Research를 추가하세요.

OpenAI는 현재 공개 HTTPS 엔드포인트(또는 Secure MCP Tunnel)와 Streamable HTTP(일반적으로 /mcp)를 요구합니다. 개발자 모드 사용 가능 여부는 계정 및 작업 공간 정책에 따라 다릅니다. OpenAI의 현재 페이지는 모든 명명된 ChatGPT 요금제에 대해 이를 보장하지 않으므로, 계정에 Developer mode 토글이 표시되는지가 권위 있는 확인 방법입니다. Plus 계정에 표시되지 않는 경우에도 서버는 MCP Inspector, 다른 MCP 클라이언트 또는 OpenAI API Playground를 통해 계속 사용할 수 있습니다. OpenAI의 현재 연결 가이드 및 MCP 서버 가이드를 참조하세요.

ChatGPT 프롬프트 예시

• 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.

프로젝트 구조

.
├── 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 라이선스입니다.