README - ClinicalTrials MCP Server by jackkuo666

ClinicalTrials MCP Server

🔍 Enable AI assistants to search and access ClinicalTrials.gov data through a simple MCP interface.

The ClinicalTrials MCP Server provides a bridge between AI assistants and ClinicalTrials.gov's clinical trial repository through the Model Context Protocol (MCP). It allows AI models to search for clinical trials and access their content in a programmatic way.

🤝 Contribute • 📝 Report Bug

✨ Core Features

🔎 Trial Search: Query clinical trials with custom search strings or advanced search parameters ✅
🚀 Efficient Retrieval: Fast access to trial metadata ✅
📊 Metadata Access: Retrieve detailed metadata for specific trials using NCT ID ✅
📊 Research Support: Facilitate health sciences research and analysis ✅
📋 CSV Management: Save, load, and list CSV files with trial data ✅
🗃️ Local Storage: Trials are saved locally for faster access ✅
📊 Statistics: Get statistics about clinical trials ✅

🚀 Quick Start

Installing via Smithery

To install ClinicalTrials Server for Claude Desktop automatically via Smithery:

Claude

npx -y @smithery/cli@latest install ClinicalTrials-mcp-server --client claude --config "{}"

Cursor

Paste the following into Settings → Cursor Settings → MCP → Add new server:

Mac/Linux

npx -y @smithery/cli@latest run ClinicalTrials-mcp-server --client cursor --config "{}"

Windsurf

npx -y @smithery/cli@latest install ClinicalTrials-mcp-server --client windsurf --config "{}"

CLine

npx -y @smithery/cli@latest install ClinicalTrials-mcp-server --client cline --config "{}"

Installing Manually

Install using uv:

uv tool install ClinicalTrials-mcp-server

For development:

# Clone and set up development environment
git clone https://github.com/JackKuo666/ClinicalTrials-MCP-Server.git
cd ClinicalTrials-MCP-Server

# Create and activate virtual environment
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

📊 Usage

Start the MCP server:

python clinical_trials_server.py

Once the server is running, you can use the provided MCP tools in your AI assistant or application. Here are some examples of how to use the tools:

Example 1: Search for clinical trials using a search expression and save to CSV

result = await mcp.use_tool("search_clinical_trials_and_save_studies_to_csv", {
    "search_expr": "COVID-19 vaccine efficacy",
    "max_studies": 5
})
print(result)

Example 2: Get studies by keyword

result = await mcp.use_tool("get_studies_by_keyword", {
    "keyword": "diabetes",
    "max_studies": 10
})
print(result)

Example 3: Get full study details for a specific trial

result = await mcp.use_tool("get_full_study_details", {
    "nct_id": "NCT04280705"
})
print(result)

Example 4: Search and save studies with custom fields

result = await mcp.use_tool("search_clinical_trials_and_save_studies_to_csv", {
    "search_expr": "alzheimer",
    "max_studies": 20,
    "filename": "alzheimer_studies.csv",
    "fields": ["NCT Number", "Study Title", "Brief Summary", "Conditions"]
})
print(result)

These examples demonstrate how to use the main tools provided by the ClinicalTrials MCP Server. Adjust the parameters as needed for your specific use case.

🛠 MCP Tools

The ClinicalTrials MCP Server provides the following tools:

search_clinical_trials_and_save_studies_to_csv

Search for clinical trials using a search expression and save the results to a CSV file.

Parameters:

search_expr (str): Search expression (e.g., "Coronavirus+COVID")
max_studies (int, optional): Maximum number of studies to return (default: 10)
save_csv (bool, optional): Whether to save the results as a CSV file (default: True)
filename (str, optional): Name of the CSV file to save (default: corona_fields.csv)
fields (list, optional): List of fields to include (default: NCT Number, Conditions, Study Title, Brief Summary)

Returns: String representation of the search results

get_full_study_details

Get detailed information about a specific clinical trial.

Parameters:

nct_id (str): The NCT ID of the clinical trial

Returns: String representation of the study details

get_studies_by_keyword

Get studies related to a specific keyword.

Parameters:

keyword (str): Keyword to search for
max_studies (int, optional): Maximum number of studies to return (default: 20)
save_csv (bool, optional): Whether to save the results as a CSV file (default: True)
filename (str, optional): Name of the CSV file to save (default: keyword_results_{keyword}.csv)

Returns: String representation of the studies

get_study_statistics

Get statistics about clinical trials.

Parameters:

condition (str, optional): Optional condition to filter by

Returns: String representation of the statistics

get_full_studies_and_save

Get full studies data and save to CSV.

Parameters:

search_expr (str): Search expression (e.g., "Coronavirus+COVID")
max_studies (int, optional): Maximum number of studies to return (default: 20)
filename (str, optional): Name of the CSV file to save (default: full_studies.csv)

Returns: Message indicating the results were saved

load_csv_data

Load and display data from a CSV file.

Parameters:

filename (str): Name of the CSV file to load

Returns: String representation of the CSV data

list_saved_csv_files

List all available CSV files in the current directory.

Returns: String representation of the available CSV files

🔍 MCP Resources

The ClinicalTrials MCP Server also provides the following resources:

clinicaltrials://corona_fields

Get the corona fields data as a resource.

clinicaltrials://full_studies

Get the full studies data as a resource.

clinicaltrials://csv/{filename}

Get data from a specific CSV file.

Parameters:

filename (str): Name of the CSV file

clinicaltrials://available_files

Get a list of all available CSV files.

clinicaltrials://study/{nct_id}

Get a specific study by NCT ID.

Parameters:

nct_id (str): The NCT ID of the clinical trial

clinicaltrials://condition/{condition}

Get studies related to a specific condition.

Parameters:

condition (str): The condition to search for

Usage with Claude Desktop

Add this configuration to your claude_desktop_config.json:

(Mac OS)

{
  "mcpServers": {
    "ClinicalTrials": {
      "command": "python",
      "args": ["-m", "ClinicalTrials-mcp-server"]
      }
  }
}

(Windows version):

{
  "mcpServers": {
    "ClinicalTrials": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
      "args": [
        "-m",
        "ClinicalTrials-mcp-server"
      ]
    }
  }
}

Using with Cline

{
  "mcpServers": {
    "ClinicalTrials": {
      "command": "bash",
      "args": [
        "-c",
        "source /home/YOUR/PATH/ClinicalTrials-MCP-Server/.venv/bin/activate && python /home/YOUR/PATH/ClinicalTrials-MCP-Server/clinical_trials_server.py"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

After restarting Claude Desktop, the following capabilities will be available:

Searching Clinical Trials

You can ask Claude to search for clinical trials using queries like:

Can you search for recent clinical trials about diabetes?

The search will return basic information about matching trials including:

• Trial title

• NCT Number

• Conditions

• Brief Summary

Getting Trial Details

Once you have an NCT ID, you can ask for more details:

Can you show me the details for trial NCT04280705?

This will return:

• Full trial title

• Conditions

• Brief Summary

• Other available details

📁 Project Structure

clinical_trials_server.py: The main MCP server implementation using FastMCP
clinical_trials.py: Contains helper functions for interacting with the ClinicalTrials.gov API

🔧 Dependencies

Python 3.10+
FastMCP
pytrials
pandas

You can install the required dependencies using:

pip install FastMCP pytrials pandas

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

⚠️ Disclaimer

This tool is for research purposes only. Please respect ClinicalTrials.gov's terms of service and use this tool responsibly.