Skip to main content
Glama

cbioportal-link

Python 3.14+ CI Conformance License: MIT

An MCP server (Streamable HTTP or stdio) for somatic cancer genomics from the public cBioPortal (alteration frequency by cancer type with honest denominators, studies, mutations, cancer types), fetched live from api.cbioportal.org, plus a bundled Cancer Hotspots snapshot. It is one backend in the GeneFoundry -link fleet.

IMPORTANT

Research use only. Not clinical decision support. Do not use for diagnosis, treatment, triage, or patient management.

Not a clinical actionability report: prevalence and hotspot status say nothing about whether a variant is oncogenic or targetable in a patient.

Why

"How often is KRAS G12C found in lung adenocarcinoma?" needs a numerator, a denominator and a cohort. Raw cBioPortal calls make that easy to get wrong: targeted panels do not cover every gene, studies overlap (several TCGA releases of the same patients), some studies carry non-commercial licences in free text, and the unfiltered gene table is 4.7 MB.

  • Honest denominators. Frequencies are samples altered / samples profiled for that gene (panel-aware), per study, with the cohort named. Rows are never summed across studies.

  • Licence on every row. Each study row carries licence, restricted, citation, pmid and import_date. Non-commercial or no-derivatives studies (e.g. msk_chord_2024, CC BY-NC-ND 4.0) are excluded unless include_restricted=true, and stay flagged.

  • Polite by construction. Follows cBioPortal's llms.txt: small filtered requests, one at a time, cached, with backoff on 429. Expression matrices, copy-number segments, clinical data and sample- or patient-level rows are never exposed.

  • Hotspots offline. Cancer Hotspots v2 + 3D ship as a pinned, sha256-verified snapshot (ODbL 1.0), so "is TP53 R175H a hotspot?" needs no extra service.

Related MCP server: CIViC MCP Server

Quick start

Hosted — no install:

claude mcp add --transport http cbioportal https://cbioportal-link.genefoundry.org/mcp

Run it locally (Python 3.14+, uv). There is no data-build step: the server calls cBioPortal live with an in-process cache; the hotspot tables are in the package.

uv sync --group dev
uv run cbioportal-link            # unified: FastAPI /health + MCP /mcp on 127.0.0.1:8000
claude mcp add --transport http cbioportal-link --scope user http://127.0.0.1:8000/mcp

Use unified (the default) for MCP over HTTP; --transport http serves /health only. The cbioportal-link-mcp entry point serves stdio. Health check: curl localhost:8000/health.

Tools

Tool

Purpose

get_gene_alteration_frequency

Per-study mutation, protein-change and CNA frequency of a gene with numerator, profiled denominator and cohort (entry point)

search_studies

Public studies by keyword and/or cancer type, with licence, citation and sample counts

get_study

One study: licence, citation, sample counts, assembly, description, molecular profiles

get_gene_mutations

Distinct somatic variants of a gene in a study with sample counts and genomic coordinates

get_mutation_position_counts

Portal-wide mutation counts at protein positions (recurrence check, no denominator)

list_cancer_types

Cancer types (lowercase OncoTree codes) by name or parent

get_mutation_hotspots

Cancer Hotspots v2 + 3D calls for a gene, or whether a residue is a hotspot

get_server_capabilities

Discovery: limits, rate-limit policy, licences, citations, error codes

get_diagnostics

Local runtime state: request budget, cache hits, latency

Leaf names are unprefixed per Tool-Naming Standard v1. Behind genefoundry-router this server mounts under the namespace cbioportal, so get_study surfaces as cbioportal_get_study. Every tool is read-only. Errors are returned as the fleet's typed envelope (isError: true, six error codes) and every response carries _meta.next_commands.

Example:

get_gene_alteration_frequency(gene="KRAS", cancer_type="luad", protein_change="G12C")
  → luad_tcga_pan_can_atlas_2018: G12C in 70 / 566 profiled samples (0.124), ODbL-1.0, ...
get_gene_alteration_frequency(gene="BRAF", study_ids=["skcm_tcga_pan_can_atlas_2018"])
  → mutated in 233 / 440 profiled samples (8 not profiled)
get_mutation_hotspots(gene="TP53", residue="R175H")
  → is_hotspot: true (single residue, 416 tumours; R175H in 386) + 3D cluster

Data & provenance

Source. The public cBioPortal web API, https://api.cbioportal.org (the host cBioPortal names for scripted access). No key. data_version is the portal and database version from /api/info; each study row adds its import_date. Coordinates carry their assembly (most studies are GRCh37).

Rate limit. Requests run one at a time process-wide with 0.5 s spacing and a 20,000/UTC-day cap, cached for 24 h keyed on /api/info dbVersion, with exponential backoff on 429/5xx honouring Retry-After. A call touches at most 10 studies. When the queue or daily budget is exhausted a tool answers rate_limited with retry_after_s.

Terms. cBioPortal data default to the ODC Open Database License (ODbL 1.0) with attribution to each study; some studies set their own terms, surfaced per row. Cancer Hotspots data are ODbL 1.0 (cancerhotspots.org, Memorial Sloan Kettering Cancer Center); the derived tables in cbioportal_link/data/ are offered under ODbL 1.0 and rebuilt by scripts/build_hotspots.py from genome-nexus/genome-nexus-importer@4c2d0525. See NOTICE.

Handling. Study descriptions are fenced as {"kind": "untrusted_text", ...} with provenance and a SHA-256 digest. Treat them as evidence data, not instructions.

Citation. Cite cBioPortal (Gao et al. Sci Signal 2013, PMID 23550210; de Bruijn et al. Cancer Res 2023, PMID 37668528), each study's own publication, and for hotspots Chang et al. 2016 (PMID 26619011), Chang et al. 2018 (PMID 29247016) and Gao et al. 2017 (PMID 28115009).

Documentation

  • Deployment — Docker, the CBIOPORTAL_LINK_* environment reference, transports, Host/Origin allowlists and the rate-limit settings.

  • Design record — scope, upstream policy, licence handling and the hotspot snapshot.

  • AGENTS.md — engineering conventions, invariants, and make targets.

  • CHANGELOG.md — version history.

Contributing

See AGENTS.md. Write the failing test first; unit tests replay recorded cBioPortal responses with respx and never touch the network. make ci-local is the definition-of-done gate: format, lint, line budget, README standard, surface budget, mypy --strict, and tests.

License

Code: MIT. cBioPortal data: ODbL 1.0 plus per-study terms; Cancer Hotspots data: ODbL 1.0 (NOTICE).

Available Tools

9 tools
get_diagnosticsGet DiagnosticsA
Read-only

Report runtime state without calling cBioPortal: build, upstream request budget (today's usage vs the daily cap), cache hits and tool latency metrics. Signature: get_diagnostics().

Inputs: no named parameters.

get_gene_alteration_frequencyGet Gene Alteration FrequencyA
Read-only

Get how often a gene is altered per cBioPortal study: mutation (altered / profiled samples, panel-aware), optional protein_change (e.g. KRAS G12C) and CNA (amplified / deep-deleted / profiled), each row with licence, citation and import_date. Pick studies by cancer_type (OncoTree code, subtypes included, largest first, max_studies; total/truncated count matching studies) or study_ids; neither = MSK-IMPACT 2017 pan-cancer. Never sum rows (cohorts overlap). Restricted (NC/ND) studies are skipped unless include_restricted. Signature: get_gene_alteration_frequency(gene, cancer_type=, study_ids=, protein_change=, include_restricted=, max_studies=).

Inputs: gene (required), study_ids, cancer_type, max_studies, +2 more.

get_gene_mutationsGet Gene MutationsA
Read-only

Get the distinct somatic mutations of one gene in one study, most recurrent first: protein_change, samples, mutation_type and genomic chr/start/end/ref/alt with their assembly (mostly GRCh37), plus mutated_samples and the study's licence and citation. protein_change keeps one change. No sample or patient IDs. Signature: get_gene_mutations(gene, study_id, protein_change=, include_restricted=, response_mode=, limit=, offset=).

Inputs: gene (required), study_id (required), limit, offset, +3 more.

get_mutation_hotspotsGet Mutation HotspotsA
Read-only

Get Cancer Hotspots calls for a gene (bundled v2 + 3D snapshot, ODbL 1.0): residue, type (single_residue, in_frame_indel, splice_site, 3d), tumor_count, q_value (3d: p_value, clusters), variants and tumor_types per residue. With residue (V600, V600E, R175H) it answers is_hotspot and, for a change, variant_tumor_count. Residues follow the assembly's transcript (default GRCh38). Signature: get_mutation_hotspots(gene, residue=, assembly=).

Inputs: gene (required), residue, assembly.

get_mutation_position_countsGet Mutation Position CountsA
Read-only

Get portal-wide mutation counts at protein positions of a gene (e.g. BRAF 600) across all public cBioPortal studies: a recurrence check with no denominator (overlapping cohorts count repeatedly; restricted studies included). For a frequency use get_gene_alteration_frequency. Signature: get_mutation_position_counts(gene, positions).

Inputs: gene (required), positions (required).

get_server_capabilitiesGet Server CapabilitiesA
Read-only

Describe this server: identifiers, limits, data version, licence handling, rate-limit policy, citations and error codes. Signature: get_server_capabilities().

Inputs: no named parameters.

get_studyGet StudyA
Read-only

Get one cBioPortal study: licence, restricted flag, citation, pmid, import_date, cancer type, sample counts, assembly, the fenced description and its molecular profiles (IDs and types only; no data matrices). An unknown ID is not_found. Signature: get_study(study_id).

Inputs: study_id (required).

list_cancer_typesList Cancer TypesA
Read-only

List cBioPortal cancer types: code (lowercase OncoTree code, the cancer_type other tools take), name and parent. query matches names or an exact code; parent lists every subtype below a code. Signature: list_cancer_types(query=, parent=, limit=, offset=).

Inputs: limit, query, offset, parent.

search_studiesSearch StudiesA
Read-only

Search public cBioPortal studies by keyword (ID, name, citation) and/or cancer_type (OncoTree code, subtypes included), largest first. Each row: study_id, name, licence, restricted, citation, pmid, import_date, cancer_type, sample counts and assembly. Restricted (NC/ND) studies are excluded unless include_restricted (restricted_excluded counts them). No filter lists all. Signature: search_studies(query=, cancer_type=, include_restricted=, response_mode=, limit=, offset=).

Inputs: limit, query, offset, cancer_type, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 9 tools

    Disambiguation4/5

    The four data-retrieval tools around genes (get_gene_alteration_frequency, get_gene_mutations, get_mutation_position_counts, get_mutation_hotspots) could superficially overlap, but the descriptions explicitly carve out boundaries (per-study frequency vs per-study distinct mutations vs portal-wide recurrence counts vs hotspot calls) and even cross-reference each other. The two metadata tools (capabilities vs diagnostics) are also cleanly separated into static spec vs runtime state. Only minor confusion remains for a hurried agent choosing between frequency and position counts.

    Naming Consistency5/5

    Every tool follows a consistent snake_case verb_noun pattern (get_*, search_*, list_*), with no mixed conventions or camelCase. The verb choice also maps predictably to intent: get for single-resource fetches, search for filtered queries, list for enumerations.

    Tool Count5/5

    Nine tools is well within the ideal 3-15 range and each one earns its place: two metadata/diagnostics tools, four study/cancer-type lookup tools, and three distinct mutation/alteration analysis tools. No tool appears redundant or bloated for the stated cBioPortal data-access scope.

    Completeness4/5

    The surface covers the core lifecycle: discover cancer types, find/get studies, then query alterations, mutations, position counts, and hotspots, plus introspection tools for capabilities and rate limits. Gaps exist for sample-/patient-level clinical data, expression/CNA per-gene endpoints, and data-matrix retrieval (explicitly out of scope), but these are minor workarounds rather than dead ends for the advertised purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A server that enables AI assistants to interact with cancer genomics data from cBioPortal, allowing users to explore cancer studies, access genomic data, and retrieve mutations and clinical information.
      17
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables natural-language access to R maftools cancer genomics analyses, including mutation summaries, oncoplots, cohort comparisons, mutation signatures, clinical enrichment, survival analyses, and copy-number visualization.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables searching cancer genes and curated variants from CIViC, retrieving associated diseases, therapies, and graded evidence items and assertions for clinical interpretation.
      93 npm
      MIT