clinicaltrialsgov-mcp-server

---

概要

米国国立医学図書館の試験登録サイトである ClinicalTrials.gov に登録された 60 万件以上の試験を検索します。試験の完全な記録と公開済みの結果を取得し、フィールドや有効な値を調べ、患者のプロフィールに適した募集中の試験を見つけられます。API キーは不要です。

ツール

ツール	説明
clinicaltrials_search_studies	全文検索やフィールド指定検索、ステータス／フェーズ／地域フィルター、ページネーション、並べ替え、フィールド選択を使って試験を検索します
clinicaltrials_get_study_record	NCT ID を指定して単一の試験を取得します。任意で施設、アウトカム、参照情報の上限を指定できる、完全なプロトコル記録です
clinicaltrials_get_study_count	データを取得せず、クエリに一致する試験の総数をすばやく取得します
clinicaltrials_get_field_values	API フィールドの有効な値と、値ごとの試験数を調べます
clinicaltrials_get_field_definitions	キーワード検索、パスの詳細表示、またはトップレベルの概要によって、有効なフィールド名を特定します
clinicaltrials_get_study_results	完了した試験の公開済み結果（アウトカム、有害事象、参加者の推移、ベースライン）を取得します
clinicaltrials_find_eligible	患者の人口統計情報と疾患を照合し、候補となる募集中の試験を見つけます。組み入れ／除外基準は確認しません

リソース

リソース	説明
clinicaltrials://{nctId}	NCT ID を指定して単一の臨床試験を JSON で取得します。リストには上限を設定し、結果は件数に置き換えます

プロンプト

プロンプト	説明
analyze_trial_landscape	件数取得ツールと検索ツールを使用し、データに基づく臨床試験の概況分析を行います

機能リファレンス

clinicaltrials_search_studies _ツール

• フリーテキストの query に加え、フィールド固有の conditionQuery / interventionQuery / locationQuery / sponsorQuery / titleQuery / outcomeQuery、statusFilter / phaseFilter 列挙型（大文字・小文字やスペースの違いを許容）、advancedFilter（AREA[FieldName]value / RANGE[min, max]）、geoFilter（mi / km 接尾辞付きの distance(lat,lon,radius)）を指定できます。pageSize は 1～1000（デフォルトは 10。サーバーのページあたりの上限（デフォルトは 200）を超える場合、上限に合わせてページが返され、truncated / shown / cap が設定されます）、pageToken はカーソル、sort は最大 2 フィールドでのソートです。
• デフォルトでは、試験ごとの簡潔なインデックス（nctId、briefTitle、overallStatus、phases、enrollmentCount、hasResults、…）を返します。fields（PascalCase のリーフ）を指定すると、完全な忠実度の投影を選択できます。完全なレコードは約 70KB になります。
• 型付きエラー：blank_value、ids_not_found、field_invalid、enum_invalid、query_parse_error、geo_invalid、sort_invalid、page_token_invalid、rate_limited

---

clinicaltrials_get_study_record _ツール

• nctId でプロトコルの完全なレコードを取得します。任意で locationLimit、outcomeLimit / referenceLimit、および所在地の範囲指定と並べ替えに使う nearLocation（lat、lon、radiusMi）を指定できます。いずれにも上限はなく、リストの件数を超える値を指定するとリスト全体が返されます。
• 上限によってリストが切り詰められた場合、filtersApplied に上流の合計件数が示されます。resultsSection は件数を示す resultsSummary に置き換えられます。型付きエラー：study_not_found、rate_limited

---

clinicaltrials_get_study_count _ツール

• clinicaltrials_search_studies と同じクエリおよびフィルターを指定でき、totalCount のみを返します。試験データは取得されません。
• 型付きエラー：blank_value、field_invalid、enum_invalid、query_parse_error、rate_limited

---

clinicaltrials_get_field_values _ツール

• 1 つ以上の PascalCase の fields（例：OverallStatus、Phase）を指定します。各フィールドの型と、試験件数付きの上位値（API により 250 件を上限とする）、または数値・日付フィールドの min / max / avg、真偽値フィールドの trueCount / falseCount を返します。
• STRING フィールドには longest 値が追加されます。2,000 文字を超える場合は、truncated フラグ付きのプレビューとなり、完全な length と、テキスト全体を返す clinicaltrials_search_studies 呼び出しを示す通知が含まれます。API が個別の値の件数を数えないフリーテキストフィールドには uniqueValuesCounted: false が設定され、uniqueValuesCount の 0 は件数を数えていないことを示します。
• multiValued は、値ごとの件数の合計が試験総数を上回る場合があるフィールドを示します。型付きエラー：blank_value、field_invalid、rate_limited

---

clinicaltrials_get_field_definitions _ツール

• mode：search（キーワード query、デフォルトの limit は 20、上限なし）、drill（ドット記法の path）、または overview を指定します。fields、advancedFilter、sort、clinicaltrials_get_field_values で使用できる PascalCase の名前を解決します。
• 型付きエラー：blank_value、mode_mismatch、mode_requires、path_not_found、rate_limited

---

clinicaltrials_get_study_results _ツール

• 1 回の呼び出しで取得できる個別の nctIds は最大 20 件です。さらに多くの ID（最大 500 件）は deferredNctIds として返されます。sections（outcomes、adverseEvents、participantFlow、baseline、moreInfo）、1 試験あたり 500KB を超える場合がある結果セットを簡潔にまとめる summary、および再開可能な outcomeOffset / seriousEventOffset / otherEventOffset と組み合わせて使う outcomeLimit / adverseEventLimit を指定できます。
• バッチ全体の失敗ではなく、試験ごとの fetchErrors / studiesWithoutResults が返されます。また、別名 ID が別の試験に解決された場合は canonicalNctId が返されます。型付きエラー：blank_value、offset_not_applicable、rate_limited

---

clinicaltrials_find_eligible _ツール

• age（整数、0～120）。乳児や幼児の場合は、任意で ageUnit（デフォルトは years、months、weeks、days）を指定できます。sex（FEMALE ／ MALE ／ ALL）、conditions[]、location（country は必須、state ／ city は任意）、healthyVolunteer、recruitingOnly（デフォルトは true）、maxResults（最大 1000。各呼び出しで返されるのは最大 50 件で、残りは truncated ／ shown ／ cap と、再実行可能な searchCriteria で示されます）、locationLimit（上限なし。一致した施設数を超える値を指定すると、すべて返されます）
• 年齢、性別、場所、募集状況、あいまい検索による疾患条件で一致を判定します。funnel はフィルターの各段階での一致件数を示し、notice は組み入れ基準／除外基準が確認されていないことを伝えます（確認するには clinicaltrials_get_study_record を使用してください）
• 型付きエラー：blank_value、rate_limited

---

clinicaltrials://{nctId} _リソース

• application/json 形式の完全なプロトコル記録です。所在地、副次評価項目／その他の評価項目、参考文献はそれぞれ最大 50 件に制限されます。サーバー側で固定されており、引数はありません
• 結果データは resultsSummary の件数に置き換えられます。truncated と filtersApplied で制限された内容が示され、完全なデータを取得するツールは retrieval に記載されます
• 型付きエラー：study_not_found、rate_limited

---

analyze_trial_landscape _{プロンプト}

• 引数：topic は必須、focusAreas（カンマ区切り）は任意
• データに基づく状況分析のために、件数取得、検索、フィールド検出、結果取得の各ツールをエージェントに案内するユーザーメッセージを 1 件返します

特徴

@cyanheads/mcp-ts-core を基盤としています。stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none ／ jwt ／ oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、OpenTelemetry トレースに対応した構造化ロギングを備えています。

ClinicalTrials.gov 固有の機能：

• ClinicalTrials.gov REST API v2 用の型安全なクライアント — 一般公開されており、認証や API キーは不要です
• ClinicalTrials.gov の約 1 リクエスト／秒のレート制限を適用するシリアライズ済みリクエストキュー。429／5xx 応答や HTML エラーページに対する再試行と指数バックオフを備えています
• fields ／ sort に渡されたフィールド名を自動修正します（大文字小文字、空白、RecruitmentStatus → OverallStatus などの旧エイリアス）。修正内容はその都度ログに記録されます
• ジオコーディングへの依存なしで、地理的な近接検索と最寄り施設の再ランキングに対応します
• デフォルトでは、検索と件数取得から登録数の「不明」を表すセンチネル値（99999999）を除外します。includeUnknownEnrollment を指定すると含められます

エージェントに適した出力：

• 出典情報 — 検索、件数取得、適格性判定の各ツールは searchCriteria を返します。clinicaltrials_get_study_results では、エイリアス ID が別の試験に解決される場合に canonicalNctId を示します
• 部分的な失敗への対応 — clinicaltrials_get_study_results は、バッチ全体を失敗させる代わりに、試験ごとの fetchErrors ／ studiesWithoutResults を返します
• 型付きエラー — 各ツールは reason コード（study_not_found、blank_value など）を返し、件数に上限のあるリストでは、残りがある場合に限り next*Offset を含めます
• 応答の整形 — 検索と適格性判定では、約 70KB の完全な記録ではなく、デフォルトで簡潔なインデックスを返します

はじめに

公開ホストインスタンス

公開インスタンスを https://clinicaltrials.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントから接続してください。

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

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。

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

または npx を使用します（Bun は不要です）。

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

または Docker を使用します。

{
  "mcpServers": {
    "clinicaltrialsgov-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/clinicaltrialsgov-mcp-server:latest"]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動してください。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以上）。

インストール

1. リポジトリをクローンします。

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

2. ディレクトリに移動します。

cd clinicaltrialsgov-mcp-server

3. 依存関係をインストールします。

bun install

設定

すべての設定は任意です。サーバーはデフォルト設定で動作し、API キーも不要です。

変数	説明	デフォルト
CT_API_BASE_URL	ClinicalTrials.gov API のベース URL です。	https://clinicaltrials.gov/api/v2
CT_REQUEST_TIMEOUT_MS	リクエストごとのタイムアウト（ミリ秒）です。正の整数を指定します。	30000
CT_MAX_PAGE_SIZE	clinicaltrials_search_studies の 1 ページで返す試験数です。1 以上の整数を指定します。1000 を超える値は 1000 に制限されます。	200
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモードです。stateless、stateful、または auto を指定します。	stateless
MCP_AUTH_MODE	認証モードです。none、jwt、または oauth を指定します。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOGS_DIR	ログファイルの保存ディレクトリです（Node.js のみ）。	<project-root>/logs
OTEL_ENABLED	OpenTelemetry トレーシングを有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースとメトリクス用の OTLP ベース URL です。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	ログエクスポート用の OTLP エンドポイントです。	—
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しの引数と結果を、キー名で機密情報をマスキングし、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で指定したサイズを上限として記録します。自由形式の値に含まれる秘密情報はマスキングされません。	false

任意のオーバーライド設定の一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• チェックとテストを実行する：

  bun run devcheck   # Lint, format, typecheck, and security audit
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

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

Dockerfile は、デフォルトで HTTP トランスポート、ステートレスセッションモードを使用し、/var/log/clinicaltrialsgov-mcp-server にログを記録します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツール、リソース、プロンプトを登録し、ClinicalTrials.gov サービスを初期化します。
src/config	サーバー固有の環境変数を解析し、Zod で検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）です。
src/mcp-server/resources	リソース定義（*.resource.ts）です。
src/mcp-server/prompts	プロンプト定義（*.prompt.ts）です。
src/services/clinical-trials	ClinicalTrials.gov REST API v2 クライアントです。リトライ、レート制限、フィールド検索、型を扱います。
tests/	単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch は使用しません。
• リクエストスコープのログ記録には ctx.log を使い、console は呼び出しません。
• 新しいツールとリソースは、src/mcp-server/*/definitions/index.ts のバレル経由で登録します。
• 生の API レスポンスを検証し、ドメイン型に正規化します。不足しているフィールドを捏造してはいけません。

コントリビューション

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。