cbioportal

You have a high-performance MCP server that lets AI assistants interact with cancer genomics data from cBioPortal. It uses an async Python architecture and a modular BaseEndpoint design to deliver fast, reliable access to studies, genes, mutations, clinical data, and molecular profiles. This server is intended for production use and supports flexible configuration, robust validation, and concurrent data retrieval to power advanced AI workflows in oncology research.

How to use

To use the cBioPortal MCP Server, connect an MCP client to the local or remote server endpoint and start issuing data requests through the available MCP endpoints. You can browse studies, search for studies or genes, fetch mutations, retrieve clinical data, and obtain molecular profiles. For best performance, prefer concurrent operations that fetch multiple studies or genes in parallel and leverage automatic batching where supported.

How to install

# Prerequisites
Python 3.10+
uv (recommended package manager)
Git (optional, for cloning)

# Option A: Install via uv (recommended)
pipx install uv

# Clone repository and set up
git clone https://github.com/yourusername/cbioportal-mcp.git
cd cbioportal-mcp
uv sync

# Start the server
uv run cbioportal-mcp

# Option B: Traditional pip workflow
python -m venv cbioportal-mcp-env
# Activate the environment
# Windows: cbioportal-mcp-env\Scripts\activate
# macOS/Linux: source cbioportal-mcp-env/bin/activate

pip install -e .

Configuration and usage notes

Configure the MCP server using multiple layers with the following priority: CLI arguments, environment variables, a YAML config file, and defaults. The examples below show typical configurations you can adapt for your environment.

Configuration (examples)

# YAML configuration (config.yaml)
server:
  base_url: "https://www.cbioportal.org/api"
  transport: "stdio"
  client_timeout: 480.0
  
logging:
  level: "INFO"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

api:
  rate_limit:
    enabled: false
    requests_per_second: 10
  retry:
    enabled: true
    max_attempts: 3
    backoff_factor: 1.0
  cache:
    enabled: false
    ttl_seconds: 300
  batch_size:
    genes: 100

# Environment variables (examples)
export CBIOPORTAL_BASE_URL="https://custom-instance.org/api"
export CBIOPORTAL_LOG_LEVEL="DEBUG"
export CBIOPORTAL_CLIENT_TIMEOUT=600
export CBIOPORTAL_GENE_BATCH_SIZE=50
export CBIOPORTAL_RETRY_MAX_ATTEMPTS=5

# CLI usage (examples)
uv run cbioportal-mcp
uv run cbioportal-mcp --config config.yaml --log-level DEBUG
uv run cbioportal-mcp --base-url https://custom-instance.org/api
uv run cbioportal-mcp --create-example-config

}]} ,{"heading":"Security and integration notes","blocks":[{"type":"paragraph","text":"Ensure that you protect sensitive clinical data by using secure endpoints and strong access controls. When integrating with Claude Desktop or an IDE, configure environment variables and paths carefully to avoid exposing credentials. Use the configurable timeout and retry settings to handle transient network issues gracefully."}]} ,{

## Troubleshooting

If the server fails to start, verify the Python version is 3.10 or newer, run a fresh dependency sync, and check for conflicting packages. For connection issues with clients like Claude Desktop, prefer the direct script path setup and ensure absolute paths are used. If performance lags, increase the concurrent batch size or max concurrent requests and test the bulk fetching endpoints.

## Performance tips

Use get\_multiple\_studies and get\_multiple\_genes for bulk operations to take advantage of concurrent processing. Tune concurrent\_batch\_size in your config for optimal throughput. Monitor execution timing and batch counts in the response metadata to guide adjustments.

## Development and testing notes

If you are developing or testing locally, use the provided development commands to sync the environment, run tests, and check code quality. Ensure you run tests with pytest and review any linting issues with Ruff before deployment.

## Available tools

### get\_cancer\_studies

List all available cancer studies with pagination and optional filters.

### search\_studies

Search studies by keyword with full-text capabilities and sorting options.

### get\_study\_details

Fetch comprehensive metadata for a specific study.

### get\_samples\_in\_study

Retrieve samples belonging to a given study with paginated results.

### get\_genes

Obtain gene information by ID or symbol, with flexible identifiers.

### search\_genes

Search genes by keyword, including symbol and name matching.

### get\_mutations\_in\_gene

Retrieve mutation details for a gene across studies.

### get\_clinical\_data

Access patient clinical information associated with studies.

### get\_molecular\_profiles

Fetch molecular profile data for studies.

### get\_multiple\_studies

Concurrent fetching of multiple studies to improve throughput.

### get\_multiple\_genes

Concurrent retrieval of multiple genes with automatic batching.

### get\_gene\_panels\_for\_study

Retrieve gene panels defined within studies.