gnomancer

https://gnomancer.com

A private, local deep dive into your raw DNA file. One command turns an AncestryDNA, 23andMe, MyHeritage, FamilyTreeDNA, LivingDNA or VCF export into a readable HTML report: file quality, Y and mitochondrial lineages, traits, carrier sites and pharmacogenomics, each with plain-language context and honest limits.

Nothing is uploaded. The only network traffic is the one-time download of public tools and reference files.

pipx install gnomancer          # or: pip install gnomancer   (Python 3.10+; Java 11+ for haplogroups and PharmCAT)
gnomancer setup                 # downloads the open-source tools and reference files once (~250 MB) into ~/.gnomancer
gnomancer ~/Downloads/AncestryDNA.zip
open AncestryDNA_analysis/REPORT.html

No Python yet? curl -fsSL https://gnomancer.com/install.sh | bash does all of it on macOS/Linux/WSL.

Not sure how to get the file? gnomancer.com/get-your-data has the steps for every vendor. Full install notes, including Windows: gnomancer.com/install.

Use it from your AI assistant. gnomancer is also an MCP server, so Claude Desktop, Claude Code, Cursor and others can run it and answer questions about your report, all locally:

claude mcp add gnomancer -- ~/gnomancer/.venv/bin/gnomancer serve        # Claude Code

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "gnomancer": { "command": "/Users/you/gnomancer/.venv/bin/gnomancer", "args": ["serve"] } } }

Tools: analyze, summary, section, lookup, narrative_prompt / set_narrative, and (only on request) clinvar_findings, pharmacogenomics. The raw file never leaves the machine; only derived results reach the assistant. The repo also doubles as a Claude plugin (skills/gnomancer/SKILL.md).

What you get

<input>_analysis/

Report sections:

0. In plain language / At a glance – a narrative summary (yours or Claude's) and an automatic digest: who the data says you are, what is worth knowing, what is reassuring, sensible next steps
1. Overview – vendor, build, sex, lineages, blood group, quality flags
2. Quality – no-call rate, heterozygosity per chromosome, independent sex inference, contamination flags
3. Runs of homozygosity – parental relatedness and founder-population signal
4. Lineages – Y haplogroup via yhaplo with a second opinion from Yleaf on current YFull/FTDNA/ISOGG trees; mtDNA via Haplogrep3; each with population context
5. Multi-site readings – ABO blood group, lactase persistence, TAS2R38 taster haplotype, APOE (collapsed by default)
6. Marker panel – ~110 curated sites: ancestry-informative, traits, health, carrier, pharmacogenomics
7. ClinVar scan – every typed site checked against ClinVar; pathogenic alleles listed with a plausibility score (strand-ambiguous and homozygous-rare calls are flagged as probable array artifacts)
8. PharmCAT – star-allele diplotypes and CPIC phenotypes for 18 pharmacogenes via PharmCAT, with per-gene coverage so you can see how much of each gene the chip actually typed
9. Ancestry estimate (--ancestry) – 1000 Genomes population classification via ezancestry
10. Limits – what a genotyping array cannot tell you

Health and carrier sections are collapsed by default so that people who would rather not see, say, their APOE genotype are not shown it by accident.

Vendors and quirks

Parsing is delegated to snps, which detects the vendor from the header and normalizes everything. Quirks that are handled:

The marker panel

gnomancer/data/markers.tsv is a plain TSV anyone can extend:

rsid  category  gene  label  ref  effect  interp0  interp1  interp2  note

ref/effect are the two alleles on the GRCh37 forward strand. effect is the allele that gets counted and interp0/1/2 is shown for 0/1/2 copies. Categories: ancestry, trait, health, carrier, pgx. See CONTRIBUTING.md for the sourcing rules.

Haplogroup context lives in gnomancer/data/haplogroup_context.tsv, matched by prefix so a call like R-M269 / R1b1a2a1a2 shows the chain R → R1b → R-M269.

MCP server

gnomancer serve speaks MCP over stdio. Registry manifest: server.json; publishing steps: docs/mcp-registry.md.

Options

gnomancer FILE [--out DIR] [--markers TSV] [--no-y] [--no-yleaf] [--no-mt] [--no-clinvar] [--no-pharmcat] [--ancestry]
          [--summary summary.md] [--ai]

Plain-language summary. The report opens with an automatic "at a glance" block built from the results. For a narrative on top of that, every run also writes summary-prompt.md: paste it to whatever AI assistant you use (Claude, ChatGPT, a local model), save the answer as summary.md, and re-run with --summary summary.md. Or pass --ai to have Claude write it directly (pip install anthropic, credentials via ANTHROPIC_API_KEY or ant auth login). --ai is the one path that sends anything off your machine: the structured results in summary-prompt.md, never the raw genotype file.

--ancestry runs ezancestry for a 1000 Genomes population classification. ezancestry and Yleaf need Python ≤3.11; setup.sh builds a side venv (.venv-ancestry) for both automatically when python3.11 is on the PATH, and the CLI uses it when present. First runs download reference data (ezancestry models; Yleaf's hg19 reference, ~900 MB).

Tools used under the hood

Evaluated and not used (yet): PLINK 2 (nothing an array file needs that is not already here), ADMIXTURE (needs a multi-GB reference panel), pgsc_calc polygenic scores (arrays need imputation first), SNPedia (non-commercial license, no bulk use).

Try it without your own data

.venv/bin/python examples/make_demo.py demo      # synthetic AncestryDNA / 23andMe / MyHeritage files
.venv/bin/gnomancer demo/demo_AncestryDNA.txt

Limits, stated plainly

• A genotyping array covers roughly 0.02% of the genome at pre-chosen common sites. It is not a sequence.
• Negative at a site ≠ gene is normal. BRCA1/2, CFTR and similar are covered at a handful of sites only.
• Positive at a rare site is often wrong: 40% of variants from consumer raw data were false positives when a clinical lab re-tested them (Tandy-Connor et al. 2018). The ClinVar section scores each hit for plausibility for this reason.
• CYP2D6 copy number, full HLA typing and rare variants are invisible.
• Y and mtDNA resolution stops at the few thousand / few hundred sites typed.
• Admixture percentages need a reference panel; the vendor's own estimate is the easy source.
• This is not medical advice. Confirm anything that matters with a clinical-grade test and a clinician or genetic counselor.

Website

site/ is the landing page at https://gnomancer.com, served as a Cloudflare Worker with static assets (wrangler.toml). Deploy with npx wrangler deploy (Node 22+, wrangler login once). It is static: no cookies, no analytics.

Development

./setup.sh            # venv, editable install, tools
.venv/bin/pytest
python -m build       # sdist + wheel; releases publish to PyPI from GitHub Actions (trusted publishing)

CI runs the tests and builds a demo report on every push. Real raw-data files and *_analysis/ folders are git-ignored; never commit them.

Related tools

Local: apriha/lineage (shared segments between kits), PLINK 2, ADMIXTURE + 1000 Genomes, SNPedia. Web (uploads your data): GEDmatch, James Lick's mthap, Morley's Y-SNP predictor, Promethease, Genetic Genie.

License

MIT. Haplogroup tools and references have their own licenses: yhaplo (23andMe), Haplogrep3 (GENEPI Innsbruck), PhyloTree, ISOGG.

mcp-name: com.gnomancer/gnomancer