Hgnc Link

Python 3.12+ CI Conformance License: MIT

An MCP (Model Context Protocol) server that grounds gene-nomenclature work in the HUGO Gene Nomenclature Committee (HGNC) dataset from genenames.org, served from a local index of HGNC's bulk downloads over Streamable HTTP or stdio.

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

Why

Every downstream genetics tool needs the same thing from HGNC: turn any gene symbol — current, outdated (previous), or alias — and any HGNC ID form into the canonical {hgnc_id, approved_symbol}, then pull cross-references.

HGNC does publish a REST API, but it is field-scoped (/fetch/{field}/{value}): the caller must already know whether a string is a current symbol, a previous symbol, an alias or an ID, and query the matching field — a network round-trip per guess. It will not tell you how a symbol matched, and it will not warn you that an alias belongs to several genes.

hgnc-link collapses that into one local call against a SQLite index of the bulk dumps. It runs the full cascade (HGNC ID → current → previous → alias → withdrawn redirect), returns the match provenance in match_type, and surfaces ambiguity as an ambiguous_query error with the candidate list rather than silently collapsing it to one gene.

Quick start

Hosted — no install:

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

Local (Python 3.12+, uv). make data is mandatory — the server has no data until the HGNC dumps (~33 MB) are downloaded and the local index is built:

make install          # uv sync --group dev
make data             # download the HGNC dumps, build the local SQLite index
make dev              # unified REST + MCP on http://127.0.0.1:8000/mcp
make mcp-serve        # ...or a stdio MCP server, for Claude Desktop

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

For stdio see claude-desktop-config.json. Keep the index fresh with make data-refresh from cron — it is conditional, so an unchanged dump costs one 304 and no rebuild (Deployment). Serving over HTTP behind a proxy requires adding the public hostname to the exact Host allowlist — read Configuration first.

Tools

Tool	Purpose
resolve_symbol	Start here. Any symbol/ID → {hgnc_id, approved_symbol, match_type} + candidates.
resolve_symbols_batch	Resolve many symbols/IDs at once; never fails the batch on a miss.
get_gene	Full HGNC record for one gene (alias- and previous-symbol aware).
search_genes	Full-text search over symbol, name, alias and previous symbols.
get_gene_cross_references	Gene → NCBI / Ensembl / UniProt / RefSeq / MANE / OMIM / … identifiers.
resolve_gene_by_xref	External ID → HGNC gene (the reverse mapping).
get_gene_group	Browse a gene family by group ID or name.
get_server_capabilities	Discovery surface: tools, signatures, workflows, vocabulary.
get_hgnc_diagnostics	Loaded release, record counts, freshness, data-source status.

serverInfo.name is hgnc-link, and leaf tool names are intentionally unprefixed per the GeneFoundry Tool-Naming Standard v1. The canonical gateway namespace token is hgnc: behind genefoundry-router these surface as hgnc_<tool> (e.g. hgnc_resolve_symbol).

Every response carries _meta.next_commands — a ready-to-call {tool, arguments} list, on success and on error — and honours response_mode ∈ {minimal, compact, standard, full} (default compact). See Usage.

Data & provenance

• Source — the HGNC bulk downloads (hgnc_complete_set.json + withdrawn.txt) from genenames.org, built into a local SQLite index. Queries are served from that index; there are no per-request REST round-trips.
• Refresh — HGNC publishes Tuesdays and Fridays. hgnc-link-data refresh is the cron entry point and is conditional (an unchanged dump returns 304, so no rebuild); the in-app scheduler is off by default. See Data.
• Licence — HGNC data is released with no usage restrictions (effectively public domain / CC0). Attribution is requested but not required.
• Citation — Seal RL, Braschi B, Gray K, Jones TEM, Tweedie S, Haim-Vilmovsky L, Bruford EA. Genenames.org: the HGNC resources in 2023. Nucleic Acids Res. 2023;51(D1):D1003-D1009. doi:10.1093/nar/gkac888. RRID:SCR_002827.

Documentation

• Usage — canonical workflows, response_mode, chaining, ambiguity and withdrawn-ID semantics, the hgnc:// resources.
• Configuration — every HGNC_LINK_* variable, the transports, and the Host / Origin / CORS boundary.
• Data — the bulk dumps, the index build, freshness, and the (unwired) live REST client.
• Deployment — cron and systemd refresh, and the Docker path.
• Architecture — the ingest → SQLite → service → MCP planes, and the schema.
• Design spec — why it is shaped this way.

Contributing

See AGENTS.md for engineering conventions — the error taxonomy, the next_commands contract, and how to add a tool. make ci-local is the definition-of-done gate: format, lint, line budget, README standard, mypy strict, and tests.

License

MIT © hgnc-link contributors. HGNC data carries no usage restrictions (effectively CC0); the attribution cited above is requested but not required.