Content
# Clinical Trials MCP Server
A Model Context Protocol (MCP) server that provides access to clinical trials data from ClinicalTrials.gov. This server allows Claude Desktop to search for and retrieve detailed information about clinical trials using the official ClinicalTrials.gov API v2.
## Features
- 🔍 **Comprehensive Search**: Search clinical trials by condition, intervention, location, age group, study type, and recruitment status
- 📋 **Detailed Trial Information**: Get complete details for specific trials by NCT ID
- 🌐 **ClinicalTrials.gov API v2**: Uses the official API with proper parameter mapping and error handling
- 📄 **Pagination Support**: Handle large result sets efficiently with configurable page sizes
- 🛡️ **Robust Error Handling**: Comprehensive error handling and data validation
- 📊 **Structured Data**: Clean, structured output optimized for Claude Desktop integration
## Installation
1. **Clone or download** this repository to your local machine
2. **Create a virtual environment** (recommended):
```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
```
3. **Install dependencies**:
```powershell
pip install -r requirements.txt
```
## Configuration for Claude Desktop
Add this server to your Claude Desktop configuration file:
### Windows
Edit `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"clinical-trials": {
"command": "python",
"args": ["c:\\Users\\%username%\\Dev Code\\Clinical Trial Gov - MCP\\mcp_server.py"],
"env": {}
}
}
}
```
### macOS
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"clinical-trials": {
"command": "python",
"args": ["/path/to/your/mcp_server.py"],
"env": {}
}
}
}
```
### Linux
Edit `~/.config/claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"clinical-trials": {
"command": "python",
"args": ["/path/to/your/mcp_server.py"],
"env": {}
}
}
}
```
**After configuration**: Restart Claude Desktop to load the new server.
## Available Tools
### 1. `search_clinical_trials`
Search for clinical trials with comprehensive filtering options.
**Parameters (all optional):**
- `condition`: Medical condition or disease (e.g., "diabetes", "cancer", "heart disease")
- `intervention`: Treatment or intervention (e.g., "insulin", "chemotherapy", "surgery")
- `location`: Geographic location (e.g., "New York", "California", "United States")
- `age_group`: Age group (e.g., "child", "adult", "older_adult")
- `study_type`: Type of study ("interventional" or "observational")
- `status`: Study recruitment status:
- `"recruiting"` - Currently recruiting participants
- `"not_yet_recruiting"` - Will recruit in the future
- `"active"` - Active but not recruiting
- `"completed"` - Study completed
- `"suspended"` - Temporarily suspended
- `"terminated"` - Terminated early
- `"withdrawn"` - Withdrawn before enrollment
- `"enrolling"` - Enrolling by invitation only
- `page_size`: Results per page (1-100, default: 10)
- `max_pages`: Maximum pages to retrieve (1-10, default: 2)
### 2. `get_trial_details`
Get comprehensive details for a specific clinical trial.
**Parameters:**
- `nct_id` (required): NCT ID of the clinical trial (format: "NCT" + 8 digits, e.g., "NCT05123456")
## Usage Examples
After configuring the server in Claude Desktop, you can ask Claude questions like:
- **Basic searches**: "Find clinical trials for diabetes"
- **Location-specific**: "Find recruiting cancer trials in California"
- **Intervention-focused**: "Search for immunotherapy trials for melanoma"
- **Status filtering**: "Show me completed trials for heart disease"
- **Age-specific**: "Find pediatric studies for asthma"
- **Detailed lookup**: "Get details for trial NCT05123456"
- **Complex queries**: "Find recruiting interventional diabetes trials in New York for adults"
## Development & Testing
### Direct Testing
Test the server directly:
```powershell
python mcp_server.py
```
### API Testing
Test specific API endpoints:
```powershell
python test_api.py
```
### Debug Mode
The server includes comprehensive logging. Check console output for debugging information.
## Project Structure
```
Clinical Trial Gov - MCP/
├── mcp_server.py # Main MCP server implementation
├── ClinicalTrialsGovAPI.py # Original API client (reference)
├── test_api.py # API parameter testing script
├── test_server.py # Server testing utilities
├── requirements.txt # Python dependencies
├── pyproject.toml # Python project configuration
├── README.md # This file
└── .gitignore # Git ignore patterns
```
## API Reference
- **ClinicalTrials.gov API v2**: https://clinicaltrials.gov/data-api/api
- **Model Context Protocol**: https://modelcontextprotocol.io/
- **Claude Desktop MCP Integration**: https://claude.ai/docs/mcp
## Troubleshooting
### Common Issues
1. **Server not appearing in Claude Desktop**:
- Check the configuration file path and syntax
- Restart Claude Desktop after configuration changes
- Verify Python path in the configuration
2. **Import errors**:
- Ensure virtual environment is activated
- Run `pip install -r requirements.txt`
3. **API errors**:
- Check internet connectivity
- Review server logs for detailed error messages
### Logs
The server provides detailed logging. Check the console output when running the server for debugging information.
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
## License
This project is open source and available under the MIT License.
---
**Note**: This server uses the official ClinicalTrials.gov API v2 and is designed to provide accurate, up-to-date clinical trial information for research and educational purposes.
