BioMCP is a toolkit that connects AI systems to authoritative biomedical data sources, enabling them to answer questions about clinical trials, scientific literature, and genomic variants with precision. It follows the Model Context Protocol (MCP) to provide structured access to specialized biomedical knowledge databases.
uv if you don't have it (recommended):# MacOS
brew install uv
# Windows/Linux
pip install uv
{
"mcpServers": {
"biomcp": {
"command": "uv",
"args": ["run", "--with", "biomcp-python", "biomcp", "run"]
}
}
}
# Using pip
pip install biomcp-python
# Using uv (recommended for faster installation)
uv pip install biomcp-python
# Run directly without installation
uv run --with biomcp-python biomcp trial search --condition "lung cancer"
BioMCP supports optional environment variables for enhanced functionality:
# cBioPortal API authentication (optional)
export CBIO_TOKEN="your-api-token" # For authenticated access
export CBIO_BASE_URL="https://www.cbioportal.org/api" # Custom API endpoint
# Performance tuning
export BIOMCP_USE_CONNECTION_POOL="true" # Enable HTTP connection pooling (default: true)
export BIOMCP_METRICS_ENABLED="false" # Enable performance metrics (default: false)
BioMCP supports multiple transport protocols for different deployment scenarios:
For direct integration with Claude Desktop or local MCP clients:
# Default STDIO mode for local development
biomcp run
# Or explicitly specify STDIO
biomcp run --mode stdio
For backward compatibility with existing SSE clients:
biomcp run --mode worker
# Server available at http://localhost:8000/sse
The new MCP-compliant Streamable HTTP transport:
biomcp run --mode streamable_http
# Custom host and port
biomcp run --mode streamable_http --host 127.0.0.1 --port 8080
# Build the Docker image locally
docker build -t biomcp:latest .
# Run the container
docker run -p 8000:8000 biomcp:latest biomcp run --mode streamable_http
BioMCP provides 24 specialized tools for biomedical research:
# Start analysis with sequential thinking
think(
thought="Breaking down the query about BRAF mutations in melanoma...",
thoughtNumber=1,
totalThoughts=3,
nextThoughtNeeded=True
)
The search tool supports two modes:
# Simple natural language
search(query="BRAF melanoma")
# Field-specific search
search(query="gene:BRAF AND trials.condition:melanoma")
# Complex queries
search(query="gene:BRAF AND variants.significance:pathogenic AND articles.date:>2023")
# Get searchable fields schema
search(get_schema=True)
# Explain how a query is parsed
search(query="gene:BRAF", explain_query=True)
# Search articles (includes automatic cBioPortal integration)
search(domain="article", genes=["BRAF"], diseases=["melanoma"])
# Search with mutation-specific cBioPortal data
search(domain="article", genes=["BRAF"], keywords=["V600E"])
search(domain="article", genes=["SRSF2"], keywords=["F57*"]) # Wildcard patterns
# Search trials
search(domain="trial", conditions=["lung cancer"], phase="3")
# Search variants
search(domain="variant", gene="TP53", significance="pathogenic")
# Fetch article details (supports both PMID and DOI)
fetch(domain="article", id="34567890") # PMID
fetch(domain="article", id="10.1101/2024.01.20.23288905") # DOI
# Fetch trial with all sections
fetch(domain="trial", id="NCT04280705", detail="all")
# Fetch variant details
fetch(domain="variant", id="rs113488022")
BioMCP provides a comprehensive CLI for direct database interaction:
# Get help
biomcp --help
# Article search examples
biomcp article search --gene BRAF --disease Melanoma
biomcp article search --gene BRAF --no-preprints
biomcp article get 21717063 --full
# Clinical trial examples
biomcp trial search --condition "Lung Cancer" --phase PHASE3
biomcp trial search --condition melanoma --source nci --api-key YOUR_KEY
biomcp trial get NCT04280705 Protocol
biomcp trial get NCT04280705 --source nci --api-key YOUR_KEY
# Variant examples with external annotations
biomcp variant search --gene TP53 --significance pathogenic
biomcp variant get rs113488022
biomcp variant get rs113488022 --no-external
# NCI-specific examples (requires NCI API key)
biomcp organization search "MD Anderson" --api-key YOUR_KEY
biomcp organization get ORG123456 --api-key YOUR_KEY
biomcp intervention search pembrolizumab --api-key YOUR_KEY
biomcp intervention search --type Device --api-key YOUR_KEY
biomcp biomarker search "PD-L1" --api-key YOUR_KEY
biomcp disease search melanoma --source nci --api-key YOUR_KEY
# Get comprehensive gene information
gene_getter(gene_id_or_symbol="TP53")
# Returns: Official name, summary, aliases, links to databases
# Get disease information with synonyms
disease_getter(disease_id_or_name="GIST")
# Returns: "gastrointestinal stromal tumor" and other synonyms
# Search trials with automatic synonym expansion
trial_searcher(conditions=["GIST"], expand_synonyms=True)
# Searches for: GIST OR "gastrointestinal stromal tumor" OR "GI stromal tumor"
# 1. Always start with thinking
think(thought="Analyzing BRAF V600E in melanoma treatment", thoughtNumber=1)
# 2. Get gene context
gene_getter("BRAF")
# 3. Search for pathogenic variants
variant_searcher(gene="BRAF", hgvsp="V600E", significance="pathogenic")
# 4. Find relevant clinical trials with disease expansion
trial_searcher(conditions=["melanoma"], interventions=["BRAF inhibitor"])
Test your BioMCP setup with the MCP Inspector:
npx @modelcontextprotocol/inspector uv run --with biomcp-python biomcp run
This opens a web interface where you can explore and test all available tools.
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "biomcp" '{"command":"uv","args":["run","--with","biomcp-python","biomcp","run"]}'See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:
{
"mcpServers": {
"biomcp": {
"command": "uv",
"args": [
"run",
"--with",
"biomcp-python",
"biomcp",
"run"
]
}
}
}To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add this to your configuration file:
{
"mcpServers": {
"biomcp": {
"command": "uv",
"args": [
"run",
"--with",
"biomcp-python",
"biomcp",
"run"
]
}
}
}3. Restart Claude Desktop for the changes to take effect