bioportal-mcp

A Model Context Protocol (MCP) server for interacting with the BioPortal API to search and retrieve ontology terms.

Features

• Search ontology terms: Search across BioPortal's extensive collection of biomedical ontologies

• Search ontology properties: Find object properties, annotation properties, and datatype properties

• Get ontology analytics: Access visitor statistics and usage analytics for ontologies

• Flexible filtering: Filter by specific ontologies (e.g., NCIT, GO, HP, MONDO)

• Exact matching: Option to require exact matches or allow fuzzy matching

• Rich results: Returns term IDs, preferred labels, ontology information, and ontology page URLs

Related MCP server: BioOntology MCP Server

Installation

You can install the package from source:

pip install -e .

Or using uv:

uv pip install -e .

Setup

Before using this MCP server, you need to obtain a BioPortal API key:

1. Visit BioPortal

2. Create an account or sign in

3. Go to your account settings to get your API key

4. Set the API key as an environment variable:

export BIOPORTAL_API_KEY="your_api_key_here"

Usage

As an MCP Server

Run the MCP server:

bioportal-mcp

Available Tools

search_ontology_terms

Search for ontology terms in BioPortal.

Parameters:

• query (str): The search term (e.g., "melanoma", "breast cancer", "neuron")

• ontologies (str, optional): Comma-separated list of ontology acronyms (e.g., "NCIT,GO,HP")

• max_results (int, default=10): Maximum number of results to return

• require_exact_match (bool, default=False): Whether to require exact matches

• api_key (str, optional): BioPortal API key (uses environment variable if not provided)

Returns: List of tuples containing:

• Term ID (e.g., "http://purl.obolibrary.org/obo/NCIT_C4872")

• Preferred label (e.g., "Breast Cancer")

• Ontology acronym (e.g., "NCIT")

• Ontology URL (e.g., "https://bioportal.bioontology.org/ontologies/NCIT")

Examples:

# Search for cancer terms
results = search_ontology_terms("cancer")

# Search for cell types in Cell Ontology  
results = search_ontology_terms("neuron", ontologies="CL")

# Search for exact matches only
results = search_ontology_terms("melanoma", require_exact_match=True)

# Limit results
results = search_ontology_terms("disease", max_results=5)

search_ontology_properties

Search for ontology properties (object properties, annotation properties, datatype properties) by their labels and IDs.

Parameters:

• query (str): The search term (e.g., "has part", "related to", "has dimension")

• ontologies (str, optional): Comma-separated list of ontology acronyms (e.g., "NCIT,GO,HP")

• max_results (int, default=10): Maximum number of results to return

• require_exact_match (bool, default=False): Whether to require exact matches by property id, label, or generated label

• require_definitions (bool, default=False): If True, only return properties that have definitions

• property_types (str, optional): Comma-separated list of property types to filter by: "object", "annotation", "datatype"

• api_key (str, optional): BioPortal API key (uses environment variable if not provided)

Returns: List of tuples containing:

• Property ID (e.g., "http://www.w3.org/2000/01/rdf-schema#label")

• Property label (e.g., "label")

• Ontology acronym (e.g., "NCIT")

• Ontology URL (e.g., "https://bioportal.bioontology.org/ontologies/NCIT")

Examples:

# Search for properties containing "part"
results = search_ontology_properties("part")

# Search for object properties only
results = search_ontology_properties("related", property_types="object")

# Search for properties with definitions in specific ontologies
results = search_ontology_properties("has", ontologies="GO,CHEBI", require_definitions=True)

get_ontology_analytics

Get visitor analytics for BioPortal ontologies using Google Analytics data.

Parameters:

• ontology_acronym (str, optional): Ontology acronym to get analytics for (e.g., "NCIT", "GO"). If None, returns analytics for all ontologies

• month (int, optional): Month number (1-12) to filter analytics. Only valid when ontology_acronym is None

• year (int, optional): Year to filter analytics (e.g., 2024). Only valid when ontology_acronym is None

• api_key (str, optional): BioPortal API key (uses environment variable if not provided)

Returns: Dictionary containing visitor statistics:

• For all ontologies: dict with ontology acronyms as keys and visit counts

• For single ontology: detailed analytics with monthly/yearly breakdowns

Examples:

# Get analytics for all ontologies
analytics = get_ontology_analytics()

# Get analytics for a specific ontology
analytics = get_ontology_analytics(ontology_acronym="NCIT")

# Get analytics for all ontologies in April 2024
analytics = get_ontology_analytics(month=4, year=2024)

# Get analytics for all ontologies in 2024
analytics = get_ontology_analytics(year=2024)

Integration with AI Assistants

This MCP server can be integrated with AI assistants like Claude Desktop. Add the following to your MCP configuration:

{
  "mcpServers": {
    "bioportal": {
      "command": "bioportal-mcp",
      "env": {
        "BIOPORTAL_API_KEY": "your_api_key_here"
      }
    }
  }
}

A streamable version of this MCP is also available from the following URL:

https://bioportal.fastmcp.app/mcp

This means it may be used through any agentic framework supporting HTTP streaming of MCPs.

API Endpoints Supported

This MCP server provides access to the following BioPortal API endpoints:

• Search (/search): Search for ontology terms/classes across all ontologies

• Property Search (/property_search): Search for ontology properties (object, annotation, datatype)

• Analytics (/analytics): Retrieve visitor statistics and usage analytics for ontologies

Supported Ontologies

BioPortal hosts hundreds of ontologies. Some popular ones include:

• NCIT: NCI Thesaurus - comprehensive cancer terminology

• GO: Gene Ontology - gene and protein functions

• HP: Human Phenotype Ontology - phenotypes and clinical features

• MONDO: Disease ontology

• CHEBI: Chemical entities

• UBERON: Anatomy ontology

• CL: Cell Ontology

• SO: Sequence Ontology

Development

Local Setup

# Clone the repository
git clone https://github.com/ncbo/bioportal-mcp.git
cd bioportal-mcp

# Install development dependencies
uv pip install -e ".[dev]"

License

BSD-3-Clause