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

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