clinicaltrialsgov-mcp-server

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

개요

임상시험 검색, 발견, 분석 및 매칭을 위한 7가지 도구:

Related MCP server: Healthcare MCP Server

도구

clinicaltrials_search_studies

전체 ClinicalTrials.gov 쿼리 기능을 갖춘 기본 검색 도구입니다.

• 전체 텍스트 및 필드별 쿼리(상태, 중재, 스폰서, 위치, 제목, 결과)

• 유형이 지정된 열거형 값을 사용하는 상태 및 단계 필터

• 좌표 및 거리에 따른 지리적 근접성 필터링

• 복잡한 쿼리를 위한 고급 AREA[] Essie 표현식 지원

• 페이로드 크기를 줄이기 위한 필드 선택(전체 기록은 각각 약 70KB)

• 커서 토큰을 사용한 페이지네이션, 모든 필드별 정렬

clinicaltrials_get_study_results

완료된 연구에 대해 게시된 결과 데이터를 가져옵니다.

• 통계, 이상 반응, 참가자 흐름, 기준선 특성이 포함된 결과 측정값

• 섹션 수준 필터링(필요한 데이터만 요청)

• 선택적 요약 모드는 전체 결과(약 200KB)를 필수 메타데이터(연구당 약 5KB)로 압축

• 호출당 여러 NCT ID를 일괄 처리하고 부분 성공 보고

• 결과가 없는 연구 및 가져오기 오류에 대한 별도 추적

clinicaltrials_find_eligible

환자 프로필을 적합한 모집 중인 임상시험과 매칭합니다.

• 환자 인구 통계로 나이, 성별, 상태 및 위치를 입력받습니다.

• 인구 통계 필터(나이 범위, 성별, 건강한 지원자)를 사용하여 최적화된 API 쿼리를 생성합니다.

• 호출자가 평가할 수 있도록 자격 및 위치 필드가 포함된 연구를 반환합니다.

• 일치하는 연구가 없을 때 실행 가능한 힌트(상태 범위 확대, 필터 조정)를 제공합니다.

기능

@cyanheads/mcp-ts-core 기반으로 구축됨:

• Zod 스키마 및 형식 함수를 사용한 선언적 도구/리소스/프롬프트 정의

• 통합 오류 처리 — 핸들러가 예외를 던지면 프레임워크가 이를 포착하고 분류함

• 이중 전송: 동일한 코드베이스에서 stdio 및 Streamable HTTP 지원

• HTTP 전송을 위한 플러그인 가능한 인증(none, jwt, oauth)

• 선택적 OpenTelemetry 추적을 포함한 구조화된 로깅

ClinicalTrials.gov 관련:

• ClinicalTrials.gov REST API v2를 위한 타입 안전 클라이언트

• 공개 API — 인증 또는 API 키 불필요

• 지수 백오프(3회 시도) 및 속도 제한(초당 약 1회 요청)을 통한 재시도

• HTML 오류 감지 및 구조화된 오류 팩토리

시작하기

공개 호스팅 인스턴스

https://clinicaltrials.caseyjhand.com/mcp에서 공개 인스턴스를 사용할 수 있으며, 별도의 설치가 필요하지 않습니다. Streamable HTTP를 통해 모든 MCP 클라이언트를 연결하세요:

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

자체 호스팅 / 로컬

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

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["clinicaltrialsgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

또는 Streamable HTTP의 경우:

MCP_TRANSPORT_TYPE=http
MCP_HTTP_PORT=3010

사전 요구 사항

• Bun v1.2.0 이상 (또는 Node.js >= 22.0.0)

설치

1. 저장소 복제:

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

2. 디렉토리로 이동:

cd clinicaltrialsgov-mcp-server

3. 의존성 설치:

bun install

구성

모든 구성은 선택 사항입니다. 서버는 기본값으로 작동하며 API 키가 필요하지 않습니다.

서버 실행

로컬 개발

• 프로덕션 버전 빌드 및 실행:

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

• 개발 모드에서 실행(감시 모드):

bun run dev:http     # or dev:stdio

• 검사 및 테스트 실행:

bun run devcheck     # Lints, formats, type-checks
bun run test         # Runs test suite

Docker

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

프로젝트 구조

개발 가이드

개발 지침 및 아키텍처 규칙은 CLAUDE.md를 참조하세요. 요약하자면:

• 핸들러가 예외를 던지면 프레임워크가 포착함 — 도구 로직 내에서 try/catch 사용 금지

• 요청 범위 로깅에는 ctx.log를 사용하고 console 호출 금지

• index.ts 배럴 파일에 새로운 도구 및 리소스 등록

기여

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

bun run devcheck
bun run test

라이선스

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