AI导哈

临床试验数据搜索与分析服务

一款通过MCP协议搜索和分析ClinicalTrials.gov临床试验数据的产品，支持条件检索、迭代筛选、智能缓存、本地数据库存储以及CSV/JSON/JSONL导出，适用于医学研究、药物研发和临床试验数据分析场景。

  • by akshay3001
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 akshay3001/clinical-trials-mcp

使用说明

Clinical Trials MCP Server

Search and analyze clinical trial data from ClinicalTrials.gov through an MCP server.

The stdio server supports MCP 2026-07-28 and legacy clients.

Prerequisites

  • Node.js 24, 25, or 26

Installation

npm ci
npm run build
npm test

Automated tests use loopback HTTP stubs and temporary storage. npm test builds the server and finds tests under test/unit, test/integration, and test/mcp. Also run npm run typecheck:test and npm run format:check.

Usage

MCP Server

Add to your mcp.json:

{
  "mcpServers": {
    "clinical-trials": {
      "command": "node",
      "args": ["/path/to/clinical-trials/dist/mcp/server.js"],
      "env": {
        "CLINICAL_TRIALS_MCP_DATA_DIR": "/absolute/path/to/clinical-trials-storage"
      }
    }
  }
}

Set CLINICAL_TRIALS_API_BASE_URL to use a compatible API endpoint, such as http://127.0.0.1:8080/api/v2 for a local stub. The default is https://clinicaltrials.gov/api/v2. Include the API path and omit the trailing slash. Set CLINICAL_TRIALS_MCP_DATA_DIR to a temporary directory for tests.

Storage setup

Without an override, the server stores SQLite data in <package root>/data, cache entries in <package root>/cache, and exports in <package root>/exports. The package root is the directory with package.json. These defaults work from any client working directory, including /.

Set CLINICAL_TRIALS_MCP_DATA_DIR to a writable base directory, as shown above. The server creates data/, cache/, and exports/ below it. An absolute path is recommended; a relative base resolves from the package root. Existing files are not moved or deleted. If you previously used another working directory, set the base to that directory to keep using its data.

CLINICAL_TRIALS_EXPORTS_DIR still takes precedence for exports only. Use an absolute path for that setting too; relative export overrides resolve from the client working directory.

Features

  • 🔍 Advanced Search: Search by condition, intervention, sponsor, location, phase, status, or general terms
  • 🎯 Iterative Refinement: Filter results without re-querying the API
  • 🤖 MCP Integration: Connect AI assistants through MCP
  • 💾 Smart Caching: In-memory and disk caching to minimize API calls
  • 📊 Flexible Export: CSV, JSON, JSONL formats
  • 🗄️ Local Database: SQLite storage for studies and sessions
  • 🔌 Current MCP Protocol: Modern 2026-07-28 with legacy compatibility

Iterative Refinement

The tool creates sessions that allow you to refine searches without hitting the API again:

  1. Initial search hits API and stores results
  2. Search and filter operations return compact counts plus a session ID
  3. Filter operations work on cached results
  4. Call summarize_session for study summaries, or export_results for the complete result set
  5. Session persists in the local database with a sliding seven-day lifetime

search_trials and refine_results do not include a study list in their responses. For example:

Filtered from 1,000 to 174 studies.
**Session ID:** 550e8400-e29b-41d4-a716-446655440000

Smart Caching

  • Memory cache: 1 minute TTL for instant repeated queries
  • Disk cache: 24 hour TTL for persistence
  • Raw JSONL: Off by default. Set CLINICAL_TRIALS_MCP_LOG_RAW_RESPONSES=true to append search responses for debugging. Logs can be large and have no automatic retention limit.

get_trial_details refreshes studies whose last successful API write is older than 24 hours. If the refresh fails, it returns the stored study with a warning and its UTC storage date. A failed request with no stored study returns an error. Session summaries and exports use stored data; they do not refresh studies.

Data Export

Export in multiple formats:

  • CSV: Ready for Excel/Google Sheets with key columns; absent values use BLANK
  • JSON: Stored upstream study shape, with missing fields, empty arrays, null, 0, and false preserved
  • JSONL: The same upstream shape, one study per line for streaming/processing

JSON and JSONL do not replace values with "BLANK". Consumers that check for that placeholder must update. For studies stored by older versions, run search_trials again before a JSON or JSONL export. Old stored defaults cannot be distinguished from values sent by upstream.

Exports are confined to the configured export root and never overwrite an existing file. Set CLINICAL_TRIALS_EXPORTS_DIR to choose a different allowed export root. Relative paths must remain beneath that root; absolute paths are accepted only when they already point inside it.

Large paginated searches are bounded to 10,000 studies and 100 API pages. Set fetchLimit to a smaller total when using fetchAll; it cannot exceed pageSize × 100. A capped fetchAll reports the number stored and the upstream total, for example 2 of 50 studies (stopped at fetchLimit 2). Cache hits keep this warning. Narrow the search or raise fetchLimit within the 10,000-study maximum to retrieve more results. The warning describes the search response; sessions and exports contain only the studies retrieved.

Architecture

  • Core API Client: Handles ClinicalTrials.gov API v2 communication
  • Database Layer: SQLite with normalized schema and search sessions
  • Caching: Two-tier caching (memory + disk) for performance
  • MCP Server: Model Context Protocol interface for AI assistants

License

MIT

相关 MCP