arxiv-mcp-server

공개 호스팅 서버: https://arxiv.caseyjhand.com/mcp

도구

네 가지 도구로 arXiv 논문을 검색하고 읽을 수 있습니다:

arxiv_search

필드 접두사와 불리언 연산자를 사용한 자유 텍스트 쿼리로 논문을 검색합니다.

• 필드 접두사: ti:(제목), au:(저자), abs:(초록), cat:(카테고리), all:(모든 필드)

• 불리언 연산자: AND, OR, ANDNOT

• 선택적 카테고리 필터, 정렬(관련도, 제출일, 업데이트일) 및 페이지네이션

• 카테고리는 리프 코드(cs.CL) 또는 전체 아카이브(astro-ph, cs, math)를 허용합니다. 아카이브 이름만 지정하면 해당 주제 클래스와, 세분화 이전에 등록된 레거시 플랫 논문까지 포함합니다.

• submitted_from / submitted_to는 제출 날짜 범위를 지정합니다(경계 포함, UTC YYYY-MM-DD). 연속된 시간 창은 빈틈 없이 일치 항목을 모두 포함합니다. 자정 경계에 정확히 제출된 논문은 두 창에 모두 포함되므로 ID로 중복을 제거하세요. 이 방식으로 10,000건 페이지네이션 상한을 넘어선 결과에 도달할 수 있습니다.

• 실제로 검색된 쿼리를 모든 필터가 반영된 상태로 그대로 반환합니다. 이를 재실행하면 동일한 결과 집합이 재현됩니다.

• 요청당 최대 50건의 결과를 초록을 포함한 전체 메타데이터와 함께 반환합니다.

arxiv_get_metadata

알려진 arXiv ID로 하나 이상의 논문에 대한 전체 메타데이터를 가져옵니다.

• 단일 요청으로 최대 10건의 논문을 일괄 가져옵니다.

• 버전이 있는(2401.12345v2) ID와 버전이 없는(2401.12345) ID를 모두 허용합니다.

• 레거시 ID 형식(hep-th/9901001)을 지원합니다.

• 찾지 못한 ID는 찾은 논문과 별도로 보고합니다.

arxiv_read_paper

arXiv 논문의 전체 본문을 읽습니다.

• 먼저 arXiv 기본 HTML을 시도하고, 그다음 ar5iv, 마지막으로 PDF에서 추출한 텍스트를 시도합니다. source 필드가 어느 소스가 응답했는지 알려줍니다.

• HTML head/상용구를 제거하고 MathML을 달러 기호로 구분된 LaTeX($…$ 인라인, $$…$$ 블록)로 축약하여 문자 예산이 논문 콘텐츠에 집중되도록 합니다.

• 원시 HTML을 반환합니다. 파싱이나 추출 없이 LLM이 콘텐츠를 직접 해석합니다. PDF에서 추출한 본문은 일반 텍스트입니다. 산문은 신뢰할 수 있지만 수식, 표, 제목 구조는 평면화됩니다.

• max_characters의 기본값은 100,000이며, null을 전달하면 한 번의 호출로 전체 논문을 가져옵니다. 수식이 많은 논문의 원시 HTML은 500KB~3MB 이상이 될 수 있는데, 이는 대부분의 클라이언트가 단일 도구 결과로 수용하는 한도를 초과하므로 start로 페이지를 나누어 가져오세요.

arxiv_list_categories

탐색을 위해 arXiv 카테고리 코드와 이름을 나열합니다.

• 8개 최상위 그룹(cs, math, physics, q-bio, q-fin, stat, eess, econ)에 걸친 약 155개 카테고리

• 결과를 좁히는 선택적 그룹 필터

• 정적 데이터 — 항상 성공합니다.

Related MCP server: Research Server

리소스

기능

@cyanheads/mcp-ts-core 기반:

• 선언적 도구 정의 — 도구당 단일 파일, 프레임워크가 등록 및 검증 처리

• 모든 도구에 걸친 통합 오류 처리

• 플러그형 인증(none, jwt, oauth)

• 선택적 OpenTelemetry 추적을 지원하는 구조화된 로깅

• 동일한 코드베이스에서 로컬 실행(stdio/HTTP)

arXiv 관련:

• 읽기 전용, 인증 불필요 — arXiv API는 무료이며 메타데이터는 CC0입니다.

• arXiv의 3초 크롤링 지연을 적용하는 속도 제한 요청 큐

• 속도 제한 시 적응형 대기(5초 → 10초 → 20초 → 30초), Retry-After 준수

• 일시적 오류에 대한 지수 백오프 재시도

• 콘텐츠 폴백 체인: arXiv 기본 HTML → ar5iv → PDF 텍스트 추출(두 HTML 렌더링 모두 LaTeXML을 실행하므로 함께 실패하는 경향이 있습니다. PDF는 모든 논문이 갖는 산출물이며, ar5iv 장애 시 읽기를 실패로 처리하는 대신 PDF로 대체합니다.)

• 전체 arXiv 카테고리 분류 체계를 정적 데이터로 내장

• 선택적 로컬 OAI-PMH 메타데이터 미러(SQLite + FTS5) — 옵트인 방식으로, arxiv_search 및 arxiv_get_metadata의 속도 제한 노출을 제거합니다. 선택 사항: 로컬 미러 참조.

시작하기

공개 호스팅 인스턴스

공개 인스턴스는 https://arxiv.caseyjhand.com/mcp에서 사용할 수 있습니다 — 설치가 필요 없습니다. Streamable HTTP를 통해 모든 MCP 클라이언트를 이 주소로 연결하세요:

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "streamable-http",
      "url": "https://arxiv.caseyjhand.com/mcp"
    }
  }
}

자체 호스팅 / 로컬

MCP 클라이언트 구성(예: claude_desktop_config.json)에 추가하세요:

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/arxiv-mcp-server@latest"]
    }
  }
}

사전 요구 사항

• Bun v1.3.0 이상.

설치

1. 저장소를 클론합니다:

git clone https://github.com/cyanheads/arxiv-mcp-server.git

2. 디렉터리로 이동합니다:

cd arxiv-mcp-server

3. 의존성을 설치합니다:

bun install

구성

모든 구성은 선택 사항입니다 — 서버는 합리적인 기본값으로 바로 작동합니다.

서버 실행

로컬 개발

• 빌드 및 실행:

  bun run build
  bun run start:http   # or start:stdio

• 검사 및 테스트 실행:

  bun run devcheck     # Lint, format, typecheck, audit
  bun run test         # Vitest

선택 사항: 로컬 미러

단일 egress IP 뒤의 자체 호스팅 배포에서는 arXiv의 IP당 약 3초 크롤링 지연으로 인해 동시 사용자가 직렬화됩니다. 선택적 로컬 미러는 OAI-PMH를 통해 수집된 SQLite + FTS5 저장소에서 제공함으로써 arxiv_search 및 arxiv_get_metadata의 속도 제한 노출을 제거합니다. arxiv_read_paper는 계속 라이브 API를 사용합니다 — 전체 콘텐츠 수집은 arXiv의 데이터 정책에서 금지됩니다.

기본적으로 비활성화되어 있습니다. 활성화하려면:

# 1. Cold-start harvest (~4.4h sequential, resumable from checkpoint). One-time per installation.
bun run mirror:init

# 2. Enable the mirror.
export ARXIV_MIRROR_ENABLED=true

# 3. Start the server — reads switch to the mirror once the harvest completes.
bun run start:http

일일 증분 새로고침(델타가 작으며, 소요 시간은 arXiv의 OAI-PMH 페이지 페이싱에 따라 달라집니다)은 다음을 통해 수행합니다:

bun run mirror:refresh   # wire to cron / systemd timer / launchd, OR
                         # set ARXIV_MIRROR_REFRESH_CRON to schedule it in HTTP mode (spawned as a child process)
bun run mirror:verify    # schema version + PRAGMA integrity_check / quick_check

스키마 업그레이드. 미러는 스키마 버전을 기록하고, 더 새로운 서버가 처음으로 이를 열 때 제자리에서 자체 마이그레이션합니다 — 재수집도, 별도의 운영자 단계도 없습니다. 전체 텍스트 인덱스에 comment와 journal_ref를 추가한 업그레이드(#37)는 이미 저장된 행들로부터 해당 인덱스를 재구축하므로, co: 및 jr: 검색은 그 이전에 수집된 미러를 대상으로도 결과를 찾을 수 있습니다. 재구축은 시작 시, 스토어가 첫 읽기에 응답하기 전에 실행되며, 전체 과정에 걸쳐 mirror migration v2→v3 (fts rebuild) 진행 로그를 출력합니다 — 전체 말뭉치 미러에서는 업그레이드 후 첫 시작이 평소보다 눈에 띄게 오래 걸릴 수 있습니다. 중단된 재구축은 절반만 적용된 채 남지 않고 다음 열 때 다시 수행됩니다. bun run mirror:verify는 파일이 담고 있는 스키마 버전을 출력하며, 마이그레이션이 완료되지 않았으면 0이 아닌 종료 코드로 끝납니다.

동작 참고 사항. 순위 차이: FTS5 BM25는 arXiv의 내부 순위와 다르므로, 미러에 대한 sortBy=relevance 쿼리는 라이브 API와 다른 top-K를 반환합니다. ARXIV_MIRROR_RECENT_DAYS_LIVE일 이내에서 submitted 내림차순으로 정렬된 쿼리는 야간 업데이트 공백을 메우기 위해 라이브 API로 라우팅됩니다. 새로고침 복원력: 초기 콜드 수집이 완료된 후, 진행 중이거나 실패한 일일 새로고침이 발생해도 기존 데이터셋을 미러에서 계속 제공합니다 — arxiv_search와 arxiv_get_metadata는 새로고침 창 동안 라이브 API로 폴백하지 않습니다 (#21). 예약된 HTTP 모드 새로고침은 하위 프로세스에서 실행되므로, 수집의 동기 SQLite 쓰기가 요청 이벤트 루프를 차단하지 않습니다 — 검색과 메타데이터는 내내 응답성을 유지합니다 (#22). 미러는 최신 버전만 저장하며, 버전별 읽기는 계속 라이브 API를 사용합니다. 전체 설계는 #12를 참조하세요.

Docker

docker build -t arxiv-mcp-server .
docker run -p 3010:3010 arxiv-mcp-server

프로젝트 구조

개발 가이드

개발 지침과 아키텍처 규칙은 CLAUDE.md를 참조하세요. 요약은 다음과 같습니다:

• 핸들러는 예외를 던지고 프레임워크가 처리합니다 — 도구 로직에 try/catch를 사용하지 마세요

• 도메인별 로깅에는 ctx.log를 사용하세요

• 속도 제한은 ArxivService가 관리합니다 — 도구별 지연을 추가하지 마세요

• arXiv API는 모든 요청에 HTTP 200을 반환합니다 — content-type과 응답 본문을 확인하세요

기여

이슈와 풀 리퀘스트를 환영합니다. 제출 전에 검사를 실행하세요:

bun run devcheck
bun test

라이선스

Apache-2.0 — 자세한 내용은 LICENSE를 참조하세요.