hgnc-link grounds gene-nomenclature work in a local HGNC index, resolving symbols/IDs to canonical records and exposing cross-references through an MCP server.
Resolve any current/previous/alias gene symbol or HGNC ID to {hgnc_id, approved_symbol, match_type}, with ambiguity and withdrawn-symbol handling.
Batch-resolve up to 200 symbols/IDs without failing the whole batch on individual misses.
Fetch full HGNC gene records, including aliases, previous symbols, location, groups, and cross-references.
Search genes by free text over symbols, names, aliases, and previous symbols.
Get forward cross-references to NCBI, Ensembl, UniProt, RefSeq, MANE, OMIM, and others.
Resolve external identifiers back to HGNC genes via reverse cross-reference lookup.
Browse HGNC gene groups/families with pagination.
Discover server capabilities, tool signatures, workflows, vocabularies, and data diagnostics.
Control verbosity with response_mode and chain follow-up calls via _meta.next_commands.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hgnc-link resolve TP53 to its canonical HGNC ID"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Research use only. Not clinical decision support. Do not use for diagnosis, treatment, triage, or patient management.
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.
Related MCP server: plant-genomics-mcp
Hosted — no install:
claude mcp add --transport http hgnc https://hgnc-link.genefoundry.org/mcpLocal (Python 3.14+, 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 Desktopclaude mcp add --transport http hgnc-link --scope user http://127.0.0.1:8000/mcpFor 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.
Tool | Purpose |
| Start here. Any symbol/ID → |
| Resolve many symbols/IDs at once; never fails the batch on a miss. |
| Full HGNC record for one gene (alias- and previous-symbol aware). |
| Full-text search over symbol, name, alias and previous symbols. |
| Gene → NCBI / Ensembl / UniProt / RefSeq / MANE / OMIM / … identifiers. |
| External ID → HGNC gene (the reverse mapping). |
| Browse a gene family by group ID or name. |
| Discovery surface: tools, signatures, workflows, vocabulary. |
| 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.
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.
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.
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.
MIT © hgnc-link contributors. HGNC data carries no usage restrictions (effectively CC0); the attribution cited above is requested but not required.
Return the full HGNC record for a gene, resolved from an HGNC id, current symbol, previous symbol, or alias. Includes name, status, locus group/type, location, aliases/previous symbols, gene groups, and all cross-references. response_mode controls verbosity (compact drops dates/provenance; minimal keeps identity + anchor ids). Signature: get_gene(query, response_mode=).
Inputs: query (required), response_mode.
Return external database cross-references for a gene (forward identifier mapping): NCBI Gene, Ensembl, UniProt, RefSeq, MANE Select, OMIM, UCSC, VEGA, CCDS, MGI, RGD, Orphanet, COSMIC, PubMed. response_mode sets the default field set: minimal=NCBI+Ensembl ids; compact (default)=the high-value ids (NCBI, Ensembl, UniProt, RefSeq, MANE Select, OMIM, CCDS); standard/full=every populated field. databases optionally filters to specific sources by field key OR friendly label (e.g. 'mane', 'ncbi', 'uniprot') and OVERRIDES the response_mode tier; an unknown key is rejected with invalid_input + did-you-mean. Resolve the gene from an id/symbol/alias first. Signature: get_gene_cross_references(query, databases=, response_mode=).
Inputs: query (required), databases, response_mode.
Browse a HGNC gene group/family by numeric group id (e.g. '1157') or by name (e.g. 'RAF family'). Returns the member genes as symbol-ordered summaries. Members are paginated with limit + offset; the response carries member_count, returned, truncated, and next_offset, and (when truncated) a next_commands entry that fetches the next page. A name matching several groups returns the candidate groups so you can re-call with a specific id. Signature: get_gene_group(group, limit=, offset=, response_mode=).
Inputs: group (required), limit, offset, response_mode.
Report the local HGNC index status: whether the data is built, the loaded release date, gene/withdrawn counts, schema version, and when it was built. Use this to confirm freshness or diagnose an unavailable-data error. Signature: get_hgnc_diagnostics().
Inputs: no named parameters.
Return the hgnc-link discovery surface. detail='summary' (default) is light: identity/build/HGNC release, the tool list WITH call signatures, accepted argument aliases, response modes, recommended workflows, error taxonomy, and limits. detail='full' adds vocabularies (locus groups, status values, match types) and the cross-reference database catalogue. Call this first in a cold session, or read hgnc://tools / hgnc://capabilities. Signature: get_server_capabilities(detail=).
Inputs: detail.
Reverse identifier mapping: find the HGNC gene(s) for an external database id. source is the database (entrez_id/ncbi, ensembl_gene_id, uniprot, refseq, mane_select, omim, ucsc, vega, ccds, mgi, rgd) and value is the id (e.g. source='ensembl_gene_id', value='ENSG00000157764'). A version suffix is tolerated (ENSG00000012048.23 resolves like ENSG00000012048), and a MANE Select transcript (ENST…/NM_…) resolves back to its gene. Signature: resolve_gene_by_xref(source, value, response_mode=).
Inputs: value (required), source (required), response_mode.
Resolve any gene symbol or HGNC id to its canonical record. Accepts a current symbol, a previous (withdrawn) symbol, an alias, or an HGNC id in either form (HGNC:1100 or 1100), case-insensitively. Returns {hgnc_id, approved_symbol, match_type (hgnc_id|current|previous|alias)}. An alias shared by several genes returns an ambiguous_query error with the candidate list (not silently picked); a withdrawn/merged symbol returns a not_found error that redirects to the successor record. Signature: resolve_symbol(query, response_mode=).
Inputs: query (required), response_mode.
Resolve a batch of gene symbols / HGNC ids in one call (max 200). Each entry is resolved with the same current->previous->alias cascade as resolve_symbol; an individual miss or withdrawal never fails the batch (it is marked unresolved / obsolete in that entry). Returns per-query results plus resolved/unresolved counts. Signature: resolve_symbols_batch(queries, response_mode=).
Inputs: queries (required), response_mode.
Free-text search over gene symbols, names, aliases, and previous symbols (FTS, relevance-ranked). Returns ranked {hgnc_id, symbol, name, locus_type, score} summaries. Nomenclature-only: there is NO disease/phenotype semantics, so a descriptive query (e.g. 'polycystin kidney') only matches words present in a gene's nomenclature. Use resolve_symbol for an exact symbol/id; use this for partial names. Signature: search_genes(query, limit=, response_mode=).
Inputs: query (required), limit, response_mode.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 9 tools
All nine tools have clearly distinct purposes: gene retrieval, cross-references, group browsing, diagnostics, capabilities, reverse lookup, single/batch symbol resolution, and free-text search. There is no overlap or ambiguity between any two tools.
Tool names follow a consistent verb_noun pattern (e.g., get_gene, resolve_symbol, search_genes). The verbs are either get, resolve, or search, each clearly indicating the action, and the nouns specify the target. No mixing of conventions.
With 9 tools, the server is well-scoped for the HGNC nomenclature domain. Each tool serves a distinct and necessary function (lookup, batch, search, cross-references, etc.), and the count is neither too sparse nor overwhelming.
The tool surface covers all core operations for a gene nomenclature service: single and batch resolution, forward and reverse cross-reference mapping, group browsing, free-text search, and server diagnostics/capabilities. There are no obvious missing operations for the stated purpose.
dbSNP refSNP records and HGVS/SPDI/rsID normalization for human genetic variants, from NCBI…
NCBI Datasets — the US National Library of Medicine's genome, gene and taxonomy reference service…
UniProt protein data: find proteins, map genes to proteins, function and disease links
HGNC (HUGO Gene Nomenclature Committee) MCP.