hpo-link

MCP/API server that grounds phenotype work in the Human Phenotype Ontology (HPO).

hpo-link builds a local SQLite database from the HPO OBO release and HPOA gene/disease annotation files (served via OBO PURLs and the HPO GitHub releases) and serves a read-only MCP + REST surface for phenotype term lookup, the is_a hierarchy (ancestors/descendants via a transitive closure), cross-ontology mapping, and gene↔phenotype↔disease association queries. There is no live API — the local database is the only source, so lookups are fast and offline.

Every response is grounded in the local database and cites the HPO id + HPO release version. Research use only; not clinical decision support.

Tools

Discovery

Phenotype term lookup

Hierarchy

Cross-ontology mapping

Gene ↔ Phenotype ↔ Disease associations (HPOA)

Every response carries _meta.next_commands (ready-to-call follow-ups). Ids are normalised to HP:NNNNNNN. response_mode ∈ minimal | compact | standard | full (default compact).

Tools are unprefixed here (serverInfo.name = hpo-link); the GeneFoundry router applies the canonical gateway namespace token hpo at mount time.

Related MCP server: Unofficial HPO MCP Server

Quickstart

uv sync --group dev           # install dependencies
uv run hpo-link-data build    # download HPO (OBO + HPOA) and build the local database
uv run hpo-link-data status   # print the loaded HPO release + counts
uv run hpo-link-mcp           # stdio MCP server (for Claude Desktop)
uv run hpo-link               # unified REST + MCP server on http://127.0.0.1:8000

Or via make:

make install        # uv sync --group dev
make data           # build the local HPO database
make data-status    # print loaded release + counts
make dev            # unified REST + MCP server
make mcp-serve      # stdio MCP server

MCP client setup

HTTP (unified server exposes /mcp alongside /health):

claude mcp add --transport http hpo-link --scope user http://127.0.0.1:8000/mcp

stdio (Claude Desktop and similar):

make mcp-serve      # runs mcp_server.py on stdio (stdout is reserved for the protocol)

Data provenance

The database is built from:

• HPO ontology (hp.json) — downloaded from the HPO GitHub releases via the OBO PURL (http://purl.obolibrary.org/obo/hp.json). Contains ~19,800 active phenotype terms (HPO v2026-06-06). Fetched via conditional GET (ETag / Last-Modified); a 304 reuses the local file.

• HPOA annotations (phenotype.hpoa) — the HPO phenotype-to-disease annotation file linking HPO terms to OMIM/Orphanet/DECIPHER diseases, and gene associations derived from those annotations.

The build is atomic (temp file + os.replace) under a lock, and records provenance in a meta table (HPO release version, source validators, counts). get_diagnostics and get_server_capabilities report the loaded release.

Prebuilt artifact distribution

To skip the build step, set HPO_LINK_DATA__PREBUILT_DB_URL to the URL of a prebuilt SQLite artifact (e.g., from a GitHub Release). The entrypoint will download and verify it before serving. If absent, the server builds from source automatically (HPO_LINK_DATA__AUTO_BOOTSTRAP=true).

Documentation

• docs/architecture.md — the two planes, ingest pipeline, SQLite schema, request lifecycle.

• docs/usage.md — per-tool examples and workflows.

• docs/deployment.md — Docker, environment variables, refresh.

• AGENTS.md / CLAUDE.md — contributor + agent guide.

License & citation

Code: MIT.

Data: HPO is distributed under a custom license for research and educational use. See https://hpo.jax.org/app/license for details. Attribution required.

Citation: Köhler S, Gargano M, Matentzoglu N, et al. The Human Phenotype Ontology in 2021. Nucleic Acids Research 2021;49(D1):D1207–D1217. doi:10.1093/nar/gkaa1043.

For the most recent release cite: Gargano MA, Matentzoglu N, Coleman B, et al. The Human Phenotype Ontology in 2024: phenotypes around the world. Nucleic Acids Research 2024;52(D1):D1333–D1346. doi:10.1093/nar/gkad1005.

Research use only; not for diagnosis, treatment, triage, or patient management.