Skip to main content
Glama
Unofficial HPO MCP Server

Unofficial HPO MCP Server

Logo

Unofficial HPO MCP Server

An MCP (Model Context Protocol) server that provides access to the Human Phenotype Ontology (HPO) API. The HPO contains over 18,000 terms describing human phenotypic abnormalities and is widely used in genetic research and clinical diagnostics.

Developed by Augmented Nature

Features

This MCP server provides 12 comprehensive tools to interact with the HPO API:

Core Search & Information Tools

  • search_hpo_terms - Search for HPO terms by keyword, ID, or synonym with pagination support

  • get_hpo_term - Get detailed information about a specific HPO term by its ID

  • get_all_hpo_terms - List all HPO terms with pagination

  • batch_get_hpo_terms - Retrieve multiple HPO terms in a single request (up to 20 terms)

Hierarchical Navigation Tools

  • get_hpo_ancestors - Get all ancestor terms (all terms higher in the hierarchy)

  • get_hpo_parents - Get direct parent terms (one level up)

  • get_hpo_children - Get direct child terms (one level down)

  • get_hpo_descendants - Get all descendant terms (all terms lower in the hierarchy)

Analysis & Utility Tools

  • validate_hpo_id - Validate HPO ID format and verify term exists

  • get_hpo_term_path - Get the full hierarchical path from root to a specific term

  • compare_hpo_terms - Compare two terms and find their relationship and common ancestors

  • get_hpo_term_stats - Get comprehensive statistics and analysis for an HPO term

Related MCP server: hpo-link

Prerequisites

  • Node.js: Version 18 or higher

  • Internet connection: Required for accessing the HPO API

Installation

  1. Clone or download this server:

cd hpo-server
npm install
  1. Build the server:

npm run build

Usage

Running the Server

npm start
# or
node build/index.js

Configuration

Add the server to your MCP settings file:

{
  "mcpServers": {
    "hpo-server": {
      "command": "node",
      "args": ["/path/to/hpo-server/build/index.js"]
    }
  }
}

Usage Examples

Search and Discovery

  1. Search for seizure-related terms:

    Search for HPO terms related to "seizure" using search_hpo_terms
  2. Search with pagination:

    Search for "heart defect" terms with 20 results per page using search_hpo_terms
  3. Get detailed term information:

    Get detailed information about seizure (HP:0001250) using get_hpo_term

Hierarchical Navigation

  1. Explore term hierarchy:

    Get all ancestors of seizure term using get_hpo_ancestors
  2. Find related terms:

    Get direct children of nervous system abnormality using get_hpo_children
  3. Browse term descendants:

    Get all descendant terms of seizure using get_hpo_descendants

Analysis and Utilities

  1. Validate HPO IDs:

    Validate if "HP:0001250" is a correct HPO ID using validate_hpo_id
  2. Get hierarchical path:

    Show the complete path from root to seizure term using get_hpo_term_path
  3. Compare two terms:

    Compare seizure and nervous system abnormality terms using compare_hpo_terms
  4. Get term statistics:

    Get comprehensive statistics for seizure term using get_hpo_term_stats
  5. Batch processing:

    Get information for multiple terms (HP:0001250, HP:0000707, HP:0001626) using batch_get_hpo_terms
  6. List all terms:

    Browse all HPO terms with pagination using get_all_hpo_terms

API Features

HPO ID Format Support

HPO IDs can be provided in multiple formats:

  • Full format: HP:0001250

  • Short format: 0001250

  • The server automatically handles format conversion

Pagination Support

Search and listing tools support pagination:

  • max - Maximum results per page (varies by tool)

  • offset - Number of results to skip (default: 0)

Parameter Details

  • id (string, required for most tools): HPO term ID

  • query (string, required for search): Search query - keyword, HPO ID, or synonym

  • category (array, optional): Filter by specific HPO categories

  • max (number, optional): Maximum results to return

  • offset (number, optional): Pagination offset

API Details

  • Base URL: https://ontology.jax.org/api/hp/

  • Authentication: None required (public API)

  • Rate Limiting: Managed by client with 30-second timeout

  • Error Handling: Comprehensive error messages and graceful degradation

Project Structure

hpo-server/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   ├── types/
│   │   └── hpo.ts           # TypeScript interfaces for HPO data
│   ├── utils/
│   │   └── api-client.ts    # HPO API HTTP client
│   └── handlers/
│       └── hpo-handlers.ts  # MCP tool implementations
├── build/                   # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

Development

Building the Server

cd hpo-server
npm run build

Dependencies

  • @modelcontextprotocol/sdk - MCP SDK for server implementation

  • axios - HTTP client for HPO API requests

About the Human Phenotype Ontology

The HPO provides a standardized vocabulary of phenotypic abnormalities encountered in human disease. Each term describes a phenotypic abnormality, such as "Atrial septal defect" or "Intellectual disability". The HPO is:

Error Handling

The server includes comprehensive error handling:

  • Invalid HPO IDs are properly formatted when possible

  • Network errors provide clear user-friendly messages

  • API errors are passed through with context

  • Parameter validation with helpful error messages

Limitations

  • Maximum result limits are enforced to prevent overwhelming responses

  • Network timeouts are set to 30 seconds for stability

  • Some HPO API endpoints may have their own rate limiting (handled gracefully)

Available Tools

12 tools
batch_get_hpo_termsA

Retrieve multiple HPO terms in a single request (maximum 20 terms)

Inputs: ids (required).

compare_hpo_termsB

Compare two HPO terms and find their relationship and common ancestors

Inputs: term1 (required), term2 (required).

get_all_hpo_termsA

Get a list of all HPO terms with pagination support

Inputs: max, offset.

get_hpo_ancestorsA

Get all ancestor terms for a given HPO term (all terms higher in the hierarchy)

Inputs: id (required), max, offset.

get_hpo_childrenA

Get direct child terms for a given HPO term (one level down in the hierarchy)

Inputs: id (required), max, offset.

get_hpo_descendantsB

Get all descendant terms for a given HPO term (all terms lower in the hierarchy)

Inputs: id (required), max, offset.

get_hpo_parentsA

Get direct parent terms for a given HPO term (one level up in the hierarchy)

Inputs: id (required), max, offset.

get_hpo_termA

Get detailed information about a specific HPO term by its ID

Inputs: id (required).

get_hpo_term_pathA

Get the full hierarchical path from root to a specific HPO term

Inputs: id (required).

get_hpo_term_statsA

Get comprehensive statistics and analysis for an HPO term including hierarchy counts and properties

Inputs: id (required).

search_hpo_termsB

Search for HPO terms by keyword, ID, or synonym. Supports pagination and filtering.

Inputs: query (required), max, offset, category.

validate_hpo_idA

Validate if a given string is a valid HPO ID format and check if the term exists

Inputs: id (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 12 tools

    Disambiguation5/5

    All tools have clearly distinct purposes: single/batch retrieval, hierarchy navigation (ancestors, parents, children, descendants, path), comparison, search, validation, and statistics. No meaningful overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern, predominantly using the prefix 'hpo'. Variations like 'batch_get' vs 'get' are logical and maintain clarity.

    Tool Count5/5

    12 tools is an appropriate scope for an HPO term server, covering all essential operations without unnecessary bloat or shortage.

    Completeness5/5

    The server provides comprehensive coverage for a read-only HPO term service: retrieval, hierarchy traversal, comparison, search, validation, and statistics. There are no obvious gaps for its intended domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables querying ClinGen curated evidence for gene-disease validity, dosage, actionability, and variant pathogenicity via MCP tools.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that provides tools for querying the Human Phenotype Ontology (HPO) including term lookup, hierarchy exploration, cross-ontology mappings, and gene-phenotype-disease associations, all grounded in a local SQLite database for fast offline lookups.
      17
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying and browsing ontologies from the EBI Ontology Lookup Service, including searching for terms, retrieving term details, and navigating ontology hierarchies via natural language.
      93 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying of the Monarch Initiative biomedical knowledge graph for genes, diseases, phenotypes, and their associations through natural language or direct tool calls.
      308 npm
      MIT