Skip to main content
Glama
mitomap-link
by berntpopp

mitomap-link

Python 3.14+ CI Conformance License: MIT

An MCP (Model Context Protocol) server for MITOMAP, the human mitochondrial genome database: mtDNA disease mutations and polymorphisms on the rCRS reference with MITOMAP status, plasmy reports, GenBank frequency and literature, served from a digest-pinned snapshot of the MITOMAP daily dump over Streamable HTTP or stdio.

IMPORTANT

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

Why

Mitochondrial variants are easy to get wrong: positions are relative to the rCRS (NC_012920.1), not the Yoruba sequence older pipelines used; MITOMAP writes RNA mutations in a legacy A3243G style; its "Cfrm" status reports published literature rather than a pathogenicity call; and its plasmy flags describe reports, not a sample.

mitomap-link hands an agent the MITOMAP record without paraphrase. It normalizes m.3243A>G, MT-3243-A-G, chrM:3243 A>G and A3243G onto rCRS and rejects other references and reference-base mismatches outright. It keeps the MITOMAP status verbatim and splits out the bracketed ClinGen VCEP rating separately. GenBank counts come with their denominators, and a missing value stays null. Population frequency and heteroplasmy distributions belong to gnomAD, which next_commands points to; the tools do not run MITOMASTER sequence analysis or assign haplogroups.

Related MCP server: gencc-link

Quick start

Hosted — no install, through the GeneFoundry router (namespace mitomap, once deployed):

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

Local (Python 3.14+, uv). Production verifies a pinned data release that an init container materializes; for development, build a snapshot from the test fixture and serve it directly:

make install          # uv sync --group dev
make dev-data         # build data/dev.sqlite from tests/fixtures (tiny excerpt)
MITOMAP_LINK_DATA__LOCAL_DATABASE=data/dev.sqlite make dev   # http://127.0.0.1:8000/mcp
claude mcp add --transport http mitomap-link --scope user http://127.0.0.1:8000/mcp

The full dataset runs in Docker (make docker-up), which fetches and verifies the pinned release. Serving over HTTP behind a proxy requires adding the public hostname to the exact Host allowlist — read Configuration first.

Tools

Tool

Purpose

get_variant

Start here. Every MITOMAP record for one rCRS allele: disease, status, plasmy, GenBank frequency, PMIDs.

search_variants

Browse by locus (MT-TL1, MT-ATP6), disease text, MITOMAP status category or position window.

get_server_capabilities

Discovery surface: tools, signatures, accepted notations, semantics, license, data pin.

get_diagnostics

Whether the pinned data release is materialized and verified; dump identity and counts.

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

Every response carries _meta.next_commands; every data response carries recommended_citation. Data tools honour response_mode ∈ {minimal, compact, standard, full} (default compact). See Usage.

Data & provenance

  • Source — the MITOMAP daily PostgreSQL dump (https://mitomap.org/downloads/mitomap.dump.sql.gz), parsed as text (never restored or executed) into a derived SQLite snapshot of the mutation, polymorphism, GenBank-count, reference and locus tables. Submitter contact tables are never read. See Data.

  • Pin — an immutable, attested GitHub data release data-mitomap-<sha16>; its manifest records the dump's SHA-256 and Last-Modified. The app serves nothing unless the bytes match mitomap_link/store/pin.py.

  • Refresh — none at runtime: a new snapshot is a data-release workflow run, a reviewed pin bump, and a new release of this server.

  • Licence — MITOMAP content is CC BY 3.0; redistribution of the derived snapshot is the repository owner's determination (release/data-authorization.json), not a MITOMAP approval.

  • Citation — MITOMAP: A Human Mitochondrial Genome Database. https://www.mitomap.org. Lott MT, Leipzig JN, Derbeneva O, Xie HM, Chalkia D, Sarmady M, Procaccio V, Wallace DC. mtDNA Variation and Analysis Using MITOMAP and MITOMASTER. Curr Protoc Bioinformatics. 2013;44:1.23.1-26. doi:10.1002/0471250953.bi0123s44.

Documentation

  • Usage — workflows, notations, status/plasmy/GenBank semantics, response_mode.

  • Configuration — every MITOMAP_LINK_* variable, the transports, and the Host / Origin / CORS boundary.

  • Data — the dump, the derived snapshot, licence, and how to cut a new data release.

  • Deployment — the hardened container, the init sidecar, and the release flow.

Contributing

See AGENTS.md for engineering conventions. make ci-local is the definition-of-done gate: format, lint, line budget, README standard, mypy strict, and tests.

License

MIT © mitomap-link contributors. MITOMAP data are CC BY 3.0; cite them as above.

Available Tools

4 tools
get_diagnosticsGet DiagnosticsA
Read-onlyIdempotent

Report whether the pinned MITOMAP data release is materialized and verified: expected vs observed release tag and digest, upstream dump Last-Modified and SHA-256, MITOMAP edit dates and record counts. Use it to confirm the data version or diagnose an upstream_unavailable error. Signature: get_diagnostics().

Inputs: no named parameters.

get_server_capabilitiesGet Server CapabilitiesA
Read-onlyIdempotent

Return the mitomap-link discovery surface: tools with call signatures, argument aliases, response modes, accepted variant notations, status/plasmy/GenBank semantics, error codes, limits, data pin, license and citation. detail='full' adds the usage notes. Signature: get_server_capabilities(detail=).

Inputs: detail.

get_variantGet MITOMAP VariantA
Read-onlyIdempotent

Look up one mtDNA allele in MITOMAP on the rCRS reference (NC_012920.1): every MITOMAP record for it (coding/control-region or rRNA/tRNA disease mutation, polymorphism) with locus, disease, MITOMAP status verbatim ('Reported', 'Cfrm' = confirmed; a bracketed ClinGen VCEP rating is split out), homoplasmy/heteroplasmy as reported, GenBank count/frequency and PMIDs. Accepts m.3243A>G, NC_012920.1:m.3243A>G, MT-3243-A-G, chrM:3243 A>G, A3243G, and HGVS indels (m.5133_5134del, exact MITOMAP allele match). Other mito references (Yoruba NC_001807, RSRS) and rCRS reference-base mismatches are rejected. An allele MITOMAP does not list returns found=false, not an error. Signature: get_variant(variant, response_mode=).

Inputs: variant (required), response_mode.

search_variantsSearch MITOMAP VariantsA
Read-onlyIdempotent

Search MITOMAP mtDNA variants by locus (MT-TL1, MT-ATP6, MT-CR...), disease text, MITOMAP status category and/or an rCRS position range. record_type defaults to disease_mutation (MITOMAP's coding/control and rRNA/tRNA mutation lists); use polymorphism or any for population polymorphisms. Unknown loci are rejected. Ordered by position, or by MITOMAP reference count with sort_by='reference_count' (most-published first); returns results with total/truncated/next_offset. Signature: search_variants(locus=, disease_query=, status=, record_type=, position_start=, position_end=, sort_by=, limit=, offset=, response_mode=).

Inputs: limit, locus, offset, status, +6 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: capability discovery, data-release diagnostics, single-allele lookup, and filtered search. The boundary between get_variant (exact allele resolution across notation formats) and search_variants (locus/disease/position filtering) is explicitly drawn in the descriptions, so an agent can pick correctly.

    Naming Consistency5/5

    All four names follow a strict snake_case verb_noun pattern (get_server_capabilities, get_diagnostics, get_variant, search_variants). The verb choice also matches the operation type (get for single-target retrieval, search for filtered queries).

    Tool Count4/5

    Four tools is on the lean side but appropriate for a narrow read-only reference-data server; each tool maps to a real need. The capabilities tool is somewhat meta and could arguably fold into documentation, keeping it just short of ideal scoping.

    Completeness4/5

    The core lifecycle for a read-only variant reference—discovery, version/health verification, exact lookup, and filtered search with pagination—is covered with no obvious dead ends. The main gap is batch/multi-allele lookup, which agents would have to loop over get_variant to achieve.

    Maintenance

    ActivityMaintained
    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
      Not graded
      quality
      B
      maintenance
      Federates 13 gene-related MCP backends (gnomAD, GTEx, etc.) behind a single Streamable HTTP endpoint with collision-free namespacing and search-based tool discovery.
      7
      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