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):

python -m venv .venv
.venv\Scripts\Activate.ps1

3. Install dependencies:

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:

{
  "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:

{
  "mcpServers": {
    "clinical-trials": {
      "command": "python",
      "args": ["/path/to/your/mcp_server.py"],
      "env": {}
    }
  }
}

Linux

Edit ~/.config/claude/claude_desktop_config.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:

python mcp_server.py

API Testing

Test specific API endpoints:

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.