Content
# chictr-mcp
An MCP server that gives Claude access to the Chinese Clinical Trial Registry (ChiCTR) — the world's largest non-English clinical trial database with 100,000+ registered trials.
Search trials, extract 34+ structured fields, cross-reference with ClinicalTrials.gov, and translate Chinese fields to English — all from Claude Desktop or any MCP client.
## Quick Start
```bash
git clone https://github.com/JAGAN666/chictr-mcp.git
cd chictr-mcp
npm install
npm run build
```
That's it. The server works out of the box using WHO ICTRP (no API keys needed for basic use).
### Test it
```bash
npm run test:scrape
```
You should see **34+ fields** extracted for a pancreatic cancer trial.
## Add to Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"chictr": {
"command": "node",
"args": ["/full/path/to/chictr-mcp/dist/index.js"]
}
}
}
```
Restart Claude Desktop. You can now ask Claude things like:
- "Search ChiCTR for pancreatic cancer trials"
- "Get details for trial ChiCTR2500102611"
- "Find all lung cancer trials registered in 2024"
## Two Operating Modes
### Basic Mode (default, zero config)
Uses **WHO ICTRP** — the WHO mirror of ChiCTR data. Works with plain HTTP, no browser automation needed. Returns 30+ fields per trial.
### Full Mode (with FlareSolverr)
Connects directly to **chictr.org.cn** via FlareSolverr for the most complete data (34+ fields, Chinese titles, newest trials not yet synced to WHO). Falls back to WHO ICTRP automatically if FlareSolverr is unavailable.
```bash
# One-time setup: start FlareSolverr
docker run -d --name flaresolverr -p 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest
```
The MCP server auto-detects FlareSolverr at `http://localhost:8191/v1` — no config changes needed.
## Optional: Translation
To translate Chinese trial fields to English, get a free NVIDIA API key from [build.nvidia.com](https://build.nvidia.com/) and add it to your Claude Desktop config:
```json
{
"mcpServers": {
"chictr": {
"command": "node",
"args": ["/full/path/to/chictr-mcp/dist/index.js"],
"env": {
"NVIDIA_API_KEY": "nvapi-your-key-here"
}
}
}
}
```
## MCP Tools
### search_chictr_trials
Search for Chinese clinical trials by keyword.
```json
{ "keyword": "gastric cancer", "max_results": 10, "year": 2024 }
```
Returns: trial IDs, titles, study type, registration dates, institutions, source URLs.
### get_trial_detail
Get full structured data for a single trial.
```json
{ "registration_number": "ChiCTR2500102611", "translate": true, "verify": true }
```
Returns 34+ fields: title, phase, status, condition, intervention, sponsor, PI contact, enrollment, outcomes, inclusion/exclusion criteria, ethics approval, blinding, trial sites, and more. Every field includes a `source_url` for citation.
### bulk_ingest_chictr
Fetch multiple trials in parallel with quality scoring. Returns Qdrant-ready documents for RAG pipelines.
```json
{ "keyword": "lung cancer", "max_results": 20, "translate": true }
```
Trials are scored HIGH/MEDIUM/LOW based on field completeness. Only HIGH and MEDIUM quality trials are returned; LOW quality trials are listed separately in a `skipped` array.
### verify_chictr_trial
Cross-reference a ChiCTR trial with ClinicalTrials.gov.
```json
{ "registration_number": "ChiCTR2400093415" }
```
Returns: matched NCT ID, confidence level (HIGH/MEDIUM/LOW/UNVERIFIED), and any discrepancies.
### get_cache_stats / clear_cache
View or clear the in-memory cache.
## Architecture
```
Claude Desktop
│ JSON-RPC over stdio
▼
MCP Server (index.ts)
├── scraper.ts ──→ FlareSolverr → chictr.org.cn (primary)
│ ──→ WHO ICTRP (fallback, plain HTTP)
├── verifier.ts ──→ ClinicalTrials.gov v2 API
├── translator.ts ──→ NVIDIA API (Nemotron 70B)
├── cache.ts ──→ In-memory (node-cache)
└── types.ts ──→ ChiCTRTrial interface (34+ fields)
```
## Environment Variables
All optional. Set in Claude Desktop config `env` block or in a `.env` file for development.
| Variable | Default | Description |
|----------|---------|-------------|
| `NVIDIA_API_KEY` | — | Enables Chinese→English translation |
| `FLARESOLVERR_URL` | `http://localhost:8191/v1` | FlareSolverr endpoint for direct ChiCTR access |
| `CHICTR_SEARCH_CACHE_TTL` | `300` | Search cache TTL (seconds) |
| `CHICTR_DETAIL_CACHE_TTL` | `600` | Detail cache TTL (seconds) |
| `BULK_CONCURRENCY` | `3` | Max parallel fetches for bulk ingest |
| `REQUEST_DELAY_MS` | `1500` | Delay between requests (milliseconds) |
## Development
```bash
npm run dev # Run with hot reload (tsx)
npm run build # Compile TypeScript
npm run test:scrape # Test scraper against a real trial
npm run ingest # Run oncology ingest pipeline (6 keywords)
npx tsc --noEmit # Type check only
```
## License
MIT
