clinicaltrialsgov-mcp-server

Публичный хостинг сервера: https://clinicaltrials.caseyjhand.com/mcp

Обзор

Семь инструментов для поиска, обнаружения, анализа и подбора клинических исследований:

Related MCP server: Healthcare MCP Server

Инструменты

clinicaltrials_search_studies

Основной инструмент поиска с полными возможностями запросов ClinicalTrials.gov.

• Полнотекстовые и специфические для полей запросы (заболевание, вмешательство, спонсор, локация, название, исход)

• Фильтры по статусу и фазе с типизированными значениями перечислений

• Географическая фильтрация по координатам и расстоянию

• Расширенная поддержка выражений AREA[] Essie для сложных запросов

• Выбор полей для уменьшения размера полезной нагрузки (полные записи весят ~70 КБ каждая)

• Пагинация с токенами курсора, сортировка по любому полю

clinicaltrials_get_study_results

Получение опубликованных результатов для завершенных исследований.

• Показатели исходов со статистикой, нежелательными явлениями, потоком участников, исходными характеристиками

• Фильтрация на уровне разделов (запрашивайте только нужные данные)

• Опциональный режим сводки сжимает полные результаты (~200 КБ) до основных метаданных (~5 КБ на исследование)

• Пакетная обработка нескольких NCT ID за один вызов с отчетом о частичном успехе

• Отдельное отслеживание исследований без результатов и ошибок получения

clinicaltrials_find_eligible

Подбор подходящих рекрутинговых исследований для профиля пациента.

• Принимает возраст, пол, заболевания и местоположение в качестве демографических данных пациента

• Формирует оптимизированные API-запросы с демографическими фильтрами (возрастной диапазон, пол, здоровые добровольцы)

• Возвращает исследования с полями критериев включения и локаций для оценки вызывающей стороной

• Предоставляет полезные подсказки, если подходящих исследований не найдено (расширение условий, корректировка фильтров)

Функции

Построено на @cyanheads/mcp-ts-core:

• Декларативные определения инструментов/ресурсов/промптов со схемами Zod и функциями форматирования

• Унифицированная обработка ошибок — обработчики выбрасывают исключения, фреймворк перехватывает и классифицирует их

• Двойной транспорт: stdio и Streamable HTTP из одной кодовой базы

• Подключаемая аутентификация (none, jwt, oauth) для HTTP-транспорта

• Структурированное логирование с опциональной трассировкой OpenTelemetry

Специфично для ClinicalTrials.gov:

• Типизированный клиент для ClinicalTrials.gov REST API v2

• Публичный API — аутентификация или ключи API не требуются

• Повторные попытки с экспоненциальной задержкой (3 попытки) и ограничением частоты запросов (~1 запрос/сек)

• Обнаружение HTML-ошибок и фабрики структурированных ошибок

Начало работы

Публичный хостинг

Публичный экземпляр доступен по адресу https://clinicaltrials.caseyjhand.com/mcp — установка не требуется. Укажите его в любом MCP-клиенте через Streamable HTTP:

{
  "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

• Запуск в режиме разработки (с watch):

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.