Mutation Clinical Trial Matching MCP
A Model Context Protocol (MCP) server that enables Claude Desktop to search for matches in clincialtrials.gov based on mutations.
Status
This is currently first phase of development. It works to retreive trials based on given mutations in the claude query. However, there are still bugs and further refinements and additions to be implemented.
Overview
This project follows the Agentic Coding principles to create a system that integrates Claude Desktop with the clinicaltrials.gov API. The server allows for natural language queries about genetic mutations and returns summarized information about relevant clinical trials.
Each node in the flow follows the PocketFlow Node pattern with prep
, exec
, and post
methods:
Project Structure
This project is organized according to the Agentic Coding paradigm:
- Requirements (Human-led):
- Search and summarize clinical trials related to specific genetic mutations
- Provide mutation information as contextual resources
- Integrate seamlessly with Claude Desktop
- Flow Design (Collaborative):
- User queries Claude Desktop about a genetic mutation
- Claude calls our MCP server tool
- Server queries clinicaltrials.gov API
- Server processes and summarizes the results
- Server returns formatted results to Claude
- Utilities (Collaborative):
clinicaltrials/query.py
: Handles API calls to clinicaltrials.govutils/call_llm.py
: Utilities for working with Claude
- Node Design (AI-led):
utils/node.py
: Implements base Node and BatchNode classes with prep/exec/post patternclinicaltrials/nodes.py
: Defines specialized nodes for querying and summarizingclinicaltrials_mcp_server.py
: Orchestrates the flow execution
- Implementation (AI-led):
- FastMCP SDK for handling the protocol details
- Error handling at all levels
- Resources for common mutations
Components
MCP Server (clinicaltrials_mcp_server.py
)
The main server that implements the Model Context Protocol interface, using the official Python SDK. It:
- Registers and exposes tools for Claude to use
- Provides resources with information about common mutations
- Handles the communication with Claude Desktop
Query Module (clinicaltrials/query.py
)
Responsible for querying the clinicaltrials.gov API with:
- Robust error handling
- Input validation
- Detailed logging
Summarizer (llm/summarize.py
)
Processes and formats the clinical trials data:
- Organizes trials by phase
- Extracts key information (NCT ID, summary, conditions, etc.)
- Creates a readable markdown summary
Node Pattern Implementation
This project implements the PocketFlow Node pattern, which provides a modular, maintainable approach to building AI workflows:
Core Node Classes (utils/node.py
)
- Node: Base class with
prep
,exec
, andpost
methods for processing data - BatchNode: Extension for batch processing multiple items
- Flow: Orchestrates execution of nodes in sequence
Implementation Nodes (clinicaltrials/nodes.py
)
- QueryTrialsNode:Copy
- SummarizeTrialsNode:Copy
Flow Execution
The MCP server creates and runs the flow:
This pattern separates preparation, execution, and post-processing, making the code more maintainable and testable. For more details, see the design document.
Usage
- Install dependencies with uv:Copy
- Configure Claude Desktop:
- The config at
~/Library/Application Support/Claude/claude_desktop_config.json
should already be set up
- The config at
- Start Claude Desktop and ask questions like:
- "What clinical trials are available for EGFR L858R mutations?"
- "Are there any trials for BRAF V600E mutations?"
- "Tell me about trials for ALK rearrangements"
- Use resources by asking:
- "Can you tell me more about the KRAS G12C mutation?"
Integrating with Claude Desktop
You can configure this project as a Claude Desktop MCP tool. Use path placeholders in your configuration, and substitute them with your actual paths:
Path Variables:
{PATH_TO_VENV}
: Full path to your virtual environment directory.{PATH_TO_PROJECT}
: Full path to the directory containing your project files.
Installation Instructions:
- Clone the repository to your local machine.
- Install uv if you don't have it already:Copy
- Create a virtual environment and install dependencies in one step:Copy
- Activate the virtual environment when needed:Copy
- Determine the full path to your virtual environment and project directory.
- Update your configuration with these specific paths.
Examples:
- On macOS/Linux:Copy
- On Windows:Copy
Path Finding Tips:
- To find the exact path to your Python interpreter in the virtual environment, run:
which python
(macOS/Linux)where python
(Windows, after activating the venv)
- For the project path, use the full path to the directory containing
clinicaltrials_mcp_server.py
.
Future Improvements
For a comprehensive list of planned enhancements and future work, please see the future_work.md document.
Dependencies
This project relies on the following key dependencies:
- Python 3.7+ - Base runtime environment
- PocketFlow (
pocketflow>=0.0.1
) - Framework for building modular AI workflows with the Node pattern - MCP SDK (
mcp[cli]>=1.0.0
) - Official Model Context Protocol SDK for building Claude Desktop tools - Requests (
requests==2.31.0
) - HTTP library for making API calls to clinicaltrials.gov - Python-dotenv (
python-dotenv==1.1.0
) - For loading environment variables from .env files
All dependencies can be installed using uv as described in the installation instructions.
Troubleshooting
If Claude Desktop disconnects from the MCP server:
- Check logs at:
~/Library/Logs/Claude/mcp-server-clinicaltrials-mcp.log
- Restart Claude Desktop
- Verify the server is running correctly
Development Process
This project was developed using an AI-assisted coding approach, following the Agentic Coding principles where humans design and AI agents implement. The original program on main built on 2025-04-30. The implementation was created through pair programming with:
- Windsurf
- ChatGPT 4.1
- Claude 3.7 Sonnet
These AI assistants were instrumental in translating high-level design requirements into functional code, helping with API integration, and structuring the project according to best practices.
Using PocketFlow Guidelines with Context7
Important Note: This project is based on the PocketFlow-Template-Python repository, which includes a comprehensive .windsurfrules
file. However, Windsurf has a 6,000 character limit for rules files, meaning the complete PocketFlow guidelines cannot be fully loaded into Windsurf's memory.
To address this limitation, we've created detailed instructions on using the Context7 MCP server to access PocketFlow guidelines during development. This approach allows you to leverage the full power of PocketFlow's design patterns and best practices without being constrained by the character limit.
For comprehensive instructions on using Context7 with PocketFlow, please refer to our Context7 Guide. This guide includes:
- Step-by-step instructions for configuring Context7 MCP in Windsurf
- Natural language prompts for accessing PocketFlow documentation
- Examples of retrieving specific implementation patterns
- How to save important patterns as memories for future reference
By following this guide, you can maintain alignment with PocketFlow's Agentic Coding principles while developing and extending this project.
Acknowledgements
This project was built using the PocketFlow-Template-Python as a starting point. Special thanks to the original contributors of that project for providing the foundation and structure that made this implementation possible.
The project follows the Agentic Coding methodology as outlined in the original template.
This project is licensed under the MIT License - see the LICENSE file for details.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
A Model Context Protocol server that enables Claude Desktop to search clinicaltrials.gov for matching clinical trials based on genetic mutations provided in natural language queries.
Related MCP Servers
- AsecurityFlicenseAqualityA Model Context Protocol server that enhances language models with protein structure analysis capabilities, enabling detailed active site analysis and disease-related protein searches through established protein databases.Last updated -26TypeScript
- -securityAlicense-qualityA specialized Model Context Protocol server that enhances AI-assisted medical learning by connecting Claude Desktop to PubMed, NCBI Bookshelf, and user documents for searching, retrieving, and analyzing medical education content.Last updated -PythonMIT License
- -securityFlicense-qualityA Model Context Protocol server providing AI assistants with access to healthcare data tools, including FDA drug information, PubMed research, health topics, clinical trials, and medical terminology lookup.Last updated -1Python
- -securityAlicense-qualityA Model Context Protocol server that enables AI tools like Claude or Cursor to directly interact with FamilySearch's family history data, including searching person records, viewing detailed information, and exploring ancestors and descendants.Last updated -7TypeScriptMIT License