genealogy-mcp

# genealogy-mcp — find your family history with any AI assistant

<!-- mcp-name: io.github.igormel81/genealogy-mcp -->

**[Русская версия](README.ru.md)**

[![CI](https://github.com/igormel81/genealogy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/igormel81/genealogy-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/genealogy-mcp.svg)](https://pypi.org/project/genealogy-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/genealogy-mcp.svg)](https://pypi.org/project/genealogy-mcp/)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.igormel81%2Fgenealogy--mcp-1f3b33)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

An [MCP](https://modelcontextprotocol.io) server that turns Claude, ChatGPT, Cursor or any MCP-capable assistant into a
careful genealogist. It knows **where** the records of your ancestors are (114 archives and databases across Russia and
the former USSR, Europe, the British Isles, the USA and Latin America), **how** to search them (name variants,
transliterations, old spelling, the Julian calendar), and **when a find really is your person** — so the assistant gives
you working links and a plan instead of confident guesses.

Built from years of real research for an open family archive ([igoruan.ru/gene](https://igoruan.ru/gene), engine:
[gene_archive](https://github.com/igormel81/gene_archive)): parish registers, revision lists, WWI and WWII databases,
repression files, emigration records — and every trap we fell into along the way.

![You ask your assistant; genealogy-mcp knows where to look, how to search, how to read old dates and whether a find is your person, and writes into your project, your own GEDCOM tree or your family site](https://raw.githubusercontent.com/igormel81/genealogy-mcp/main/docs/overview.svg)

## At a glance

- **114 archives and databases in 55 countries**, each with what it holds and *how to search it well* — and which
  archive holds the records of a historical province today (borders moved; the answer is often not the obvious one).
- **24 tools** for the real work of a genealogist: name variants and 9 transliteration systems, Daitch–Mokotoff,
  Julian, Hebrew and French Republican calendars, dates by church feasts, Church Slavonic numerals, kinship in three
  languages, DNA, evidence checks, a tree audit, live search in open databases, archive request drafts.
- **It works on your tree, not beside it.** Point it at the `.ged` file from MyHeritage, Ancestry, Gramps or RootsMagic
  and it reads, searches and changes it in place — only the changed lines, everything else byte for byte, a copy kept,
  every change shown first. Or at a [gene-archive](https://github.com/igormel81/gene_archive) family website: changes go
  through the site's checks, logs and git history.
- **It remembers.** Sources with full citations, open leads and every search — "nothing found" included — so nobody
  searches the same place twice.
- **Honest by design.** A namesake is not a relative: a find is linked only with two independent facts beyond the name.
- **Private.** Runs on your computer; goes online only for a search you ask for, and only to that one site.
- **Any assistant:** Claude Desktop (one-click install), Claude Code, ChatGPT, Cursor, VS Code, Windsurf, Cline.
- Guides in English, Russian and Ukrainian, the main ones also in Spanish, Portuguese, Polish and German.

## Quick start

**Claude Desktop:** download `genealogy-mcp-<version>.mcpb` from the
[latest release](https://github.com/igormel81/genealogy-mcp/releases/latest) and open it.
**Claude Code:** `claude mcp add genealogy -- uvx genealogy-mcp`.
**Anything else:** `uvx genealogy-mcp` as the server command (details in [Install](#install)).

Then just ask: *"Help me find my great-grandfather. Here is what I know…"*

## What you can ask

> *My great-grandfather Ivan Kolodin was born about 1885 near Bogoroditsk, Tula province. Where do I look?*

The assistant makes a plan for Russia 1880–1945, reads the record guides, builds the name forms (Колодин / Колодина /
Колодинъ / Kolodin / Kołodin…), gives you search links for FamilySearch, the Internet Archive full text and the
Russian war databases, tells you which archive holds the parish registers and drafts the request.

> *Is this baptism record the same Ivan? It says «Іоаннъ, father Петръ, 1887, Сынково».*

`check_match` compares fact by fact with name variants and age tolerance: two independent facts beyond the name →
confirmed; one → probable; a contradiction → find a third document.

> *What is my grandmother's cousin's daughter to me? И как это по-русски?*

`kinship` → «троюродная сестра… / first cousin once removed» — in Russian, English and Romanian, with the expected DNA share.

> *Check my tree.* (a GEDCOM from Ancestry, MyHeritage, Gramps, Geni…)

`audit_tree` finds the impossible (born after the mother's death, a mother aged 10, death before birth), possible
duplicates and gaps — a to-do list for the next search.

> *The register says he was born «на Покров» 1885, the year is written ҂аѡ҃пе.*

`cyrillic_numerals` reads the year (1885), `feast_date` gives 1 October (Julian) = 13 October 1885.

> *We share 230 cM with a match on MyHeritage. Who could she be?*

`dna_match`: second cousin, first cousin twice removed, half first cousin… — and why only documents can decide.

> *Where are the parish registers of Volhynia governorate now?*

`where_are_records`: the state archives of Zhytomyr (the consistory), Rivne and Volyn — borders moved, so it is not
always the archive of today's region.

> *Remember what we found, and continue next week.*

A research project on your computer: people, sources with full citations, open leads and a log of every search —
including "nothing found" — so nobody searches the same place twice. GEDCOM in and out.

> *Write what we found into our family site.*

If your family archive is a [gene-archive](https://github.com/igormel81/gene_archive) site, give the project tools the
path of its folder: the assistant reads the archive itself — who is missing, which dates have no document — and every
change it makes goes through the site's own checks, lands in its corrections and research logs, is committed to git
under your name and rebuilds the site. It shows the change first and writes only after your yes.

> *Here is my tree — add what we found.*

Or give it the GEDCOM file of the tree you keep in MyHeritage, Ancestry, Gramps, RootsMagic, Family Historian or
webtrees: the assistant reads it, searches it and changes it in place. Only the lines of what changed are rewritten —
your program's own tags, photos, notes and the header stay byte for byte; it shows those lines before writing, keeps a
copy of the file, and keeps the search log, leads and corrections in a file next to it. Then import the file back into
your program (Family Historian and webtrees work on GEDCOM directly). Files not in UTF-8 are read-only.

## Why use it

| Without it | With genealogy-mcp |
|---|---|
| The assistant names two or three famous websites | 114 sources chosen by country, years and kind of record, each with "how to search it well" |
| Searches one spelling | Spelling variants, pre-1918 orthography, male/female forms, 9 transliteration systems, given-name equivalents (Иван = Іоаннъ = Jan = Johann = Juan) |
| Invented or broken URLs | Ready search links built from tested URL templates; a weekly job checks every site |
| "This is probably your ancestor" | An explicit evidence rule: a namesake is not a relative |
| Dates taken at face value | Julian ↔ Gregorian, birth years from ages with realistic drift, dates normalised to GEDCOM |
| Generic advice | Record guides: parish registers, confession lists, revision lists, household books, WWI/WWII, repression files, passenger lists, censuses, European civil registration, Latin American records |
| You write to archives from scratch | Request drafts for Russian ZAGS, state, military and FSB archives, and for any archive in English, Spanish or Portuguese |
| It forgets everything between chats | A research project that remembers people, sources, leads and every search |
| It cannot touch your tree | Reads and changes your own GEDCOM file in place, losing nothing, showing every change first |
| It cannot read old numbers and dates | Church Slavonic numerals, church feasts, Julian, Hebrew and French Republican calendars |
| "Search FamilySearch for your name" | Live search in the Internet Archive full text, WikiTree, Open Archives and Wikidata place history |
| DNA matches are a mystery | Shared cM → the relationships it fits |

Most genealogy MCP servers connect the assistant to one service or one file. genealogy-mcp gives it the research
method around them — where to look, how to search, how to read and weigh what it finds — and works on your own tree
file too. It runs happily next to a server for a service you use, such as a FamilySearch client.

Everything runs on your computer. The server goes online only when the assistant runs a live search
(`search_online`, `place_history`), and then sends that query to that one site.

## Coverage

- **Worldwide:** FamilySearch (records and the catalogue of unindexed images), Internet Archive full text, MyHeritage,
  Geni, WikiTree, Find a Grave, BillionGraves, Arolsen Archives, Yad Vashem, JewishGen, Matricula, Geneanet, Wikipedia.
- **Russia and the USSR:** Yandex Archive, archive guides, VGD forum, Pamyat Naroda, OBD Memorial, gwar.mil.ru,
  Open List, Immortal Barrack, Returned Names, PSTGU martyrs, Presidential and National Electronic Libraries,
  historical libraries, old maps, church history, RIA-1914, regional archives, ZAGS, TsAMO, RGVIA, RGIA, GARF.
- **Ukraine, Belarus, Moldova, Romania, Poland, the Baltics:** national archive portals and catalogues, TsDIAK,
  Geneteka, Szukajwarchiwach, epaveldas, Raduraksti, the Estonian archives.
- **Europe:** ICRC WWI prisoners,