ftb-mcp

A read-only MCP server exposing genealogy data from a MyHeritage Family Tree Builder (.ftb) file or a GEDCOM (.ged) export over HTTP.

.ftb files are plain SQLite databases, but the format is undocumented. This repository contains both the server and — in Format notes — the results of reverse engineering the schema against a real 1864-person tree.

The FTB schema is also the server's internal representation: a GEDCOM file is imported into an in-memory database of that shape, so all 17 tools work identically against either source. See GEDCOM support.

Install

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Related MCP server: mcp-kindle

Run

ftb-mcp --db-path kafkova.ftb                      # http://127.0.0.1:8000/mcp
ftb-mcp --gedcom-path kafkova.ged                  # a GEDCOM export instead
ftb-mcp --db-path kafkova.ged                      # .ged/.gedcom is detected too
ftb-mcp --db-path kafkova.ftb --host 0.0.0.0 --port 9000 --path /mcp
ftb-mcp --db-path kafkova.ftb --transport stdio    # for stdio-based clients

Exactly one of --db-path / --gedcom-path is required.

An .ftb file is opened with SQLite's mode=ro URI; a GEDCOM file is read once into memory. No tool writes, and there is no code path that can modify either file.

Registering with Claude Code

claude mcp add --transport http ftb http://127.0.0.1:8000/mcp

Tools

Discovery

Person detail

Relations

Evidence and analysis

Every text-returning tool accepts an optional language (cs, en, or an FTB language number). Text falls back through requested → Czech → English → any, and results report the language actually used when it differs from the one requested.

Media tools deliberately return no image bytes, no file names and no paths. Scanned-record descriptions often carry genealogical detail found nowhere else, so their text is exposed; the binary content is not.

GEDCOM support

Parsing is done by ged4py. The file is read into an in-memory SQLite database using the FTB schema, so queries.py and graph.py — language ranking, fact shaping, pedigrees, statistics — are shared by both backends rather than duplicated.

What is mapped

GEDCOM states each family membership twice — on the family as CHIL/HUSB/WIFE and on the individual as FAMC/FAMS. A file can carry only one side, so both are read and memberships the family record failed to mirror are added afterwards. kafkova.ged does this for two children whose FAMC also records them as adopted and fostered; reading only the family side would drop both relationships.

Two defects in MyHeritage's own export

kafkova.ged is not a conforming GEDCOM file, in two ways worth knowing about because they break other parsers:

1. CONC records split mid-character. Nine values have a multi-byte UTF-8 sequence straddling a line break — Jarmila Mat / 4 CONC \x9bj\xc5\xaf for Matějů. ged4py concatenates CONC values as bytes and decodes once the record is complete, so this survives; a parser that decodes line by line raises UnicodeDecodeError on the file.

2. Bare newlines inside values. 49 lines continue a value with a raw newline instead of a CONT record, so they arrive with no level number. repair_bare_newlines re-tags each as the CONT it was meant to be, preserving the line break. This pre-pass runs only after a first parse attempt has failed, so well-formed files are never rewritten.

Deliberate differences from the .ftb path

• Date qualifiers are normalised. ged4py renders BEF 1856 as BEFORE 1856 and ABT 1762 as ABOUT 1762, where FTB stores the short form. 182 of 4319 dates in kafkova.ged; the rest are byte-identical. year_from/year_to are unaffected.

• Open-ended bounds match FTB exactly. For AFT/FROM dates the importer writes FTB's own 99999999 "no upper bound", and -99999999 below a BEF date, so year_to and year_from read the same from either source.

• language becomes a no-op. GEDCOM has one text language, taken from HEAD.LANG. Languages FTB has no number for are assigned one at or above 200 and registered with their real name and ISO code, so a Polish file is not labelled English.

• tree_name comes from the filename. A GEDCOM's HEAD.FILE is an export description (Exported by MyHeritage.com from … on Sun, 02 Aug 2026), not a name; it is kept as the ExportDescription parameter instead.

• Nothing is soft-deleted. delete_flag is always 0, since a GEDCOM export contains only live records.

Development

.venv/bin/python -m pytest -q      # 214 tests
.venv/bin/ruff check .
.venv/bin/ruff format --check .

Test data

Tests run against static fixtures in tests/data, not against any real tree:

Both are generated by python -m tests.make_fixtures and checked in, so the suite never depends on the generator having run. Regeneration is byte-for-byte reproducible.

The fixture is small but deliberately awkward: protobuf date and RESI header columns holding bytes copied from genuine rows, a soft-deleted person, connection and fact, an is_alive value that is not in the documented set, text present in one language and missing in the other, every child role and family status, doubly-escaped HTML in notes, a citation whose "page" is really a URL, and a place whose name is blank in the preferred language. That is what lets counts be asserted exactly.

kafkova.ftb and kafkova.ged in the repository root are live working files — the tree gains people whenever the author records one, so no test may assert a count, name or date against them. tests/test_live_files.py uses them when present, for invariants only: that the file opens, that no text decoded to a replacement character, that the relationship graph is reciprocal, that notes and media come back clean, and that every tool payload is JSON-serialisable. It skips when the files are absent.

Those two files are gitignored: they are personal data, not test input. Clone the repository and the suite runs on the fixtures alone.

Continuous integration

ci.yml runs ruff and the suite on Python 3.11 through 3.14, installing from uv.lock with --frozen so CI cannot silently resolve something the lockfile does not pin. It also regenerates the fixtures and fails if a byte changed, which catches the generator drifting away from the files the tests read.

Dependabot proposes weekly updates for the uv and github-actions ecosystems. Patch and minor bumps are grouped into one pull request and merge themselves once CI is green; major bumps arrive individually and wait for review, because a passing suite only evidences the behaviour the tests already cover.

Licence

Apache License 2.0. The reverse-engineering notes below describe MyHeritage's file format; they are not affiliated with or endorsed by MyHeritage.

Format notes

Everything below was derived by inspecting a real file (kafkova.ftb, FTB 8.0.0.8640, db_version 1.7, GEDCOM 5.5.1 dialect FTBDB, UTF-8). Values are marked UNVERIFIED where they did not occur in that file.

The row counts quoted below are the evidence each mapping was established from, measured against that tree as it stood at the time. kafkova.ftb is a live file and has grown since, so treat the counts as provenance for a conclusion, not as current statistics.

Table layout

FTB uses a consistent three-layer pattern:

• *_main_data — identity, flags, dates, foreign keys

• *_lang_data — all human-readable text, keyed by data_language

• *_connection — many-to-many joins

Soft deletion is pervasive: nearly every table has delete_flag, and rows with delete_flag = 1 must be filtered out. Soft-deleted family connections would otherwise appear as phantom relatives.

It is also two levels deep, which is easy to miss. FTB deletes a person by flagging their individual_main_data row and leaves the facts, citations and media hanging off them with delete_flag = 0 of their own. Filtering only the child table therefore still counts data belonging to someone who is no longer in the tree — and if a numerator does that while its denominator does not, the result can exceed 100% of the tree. Any aggregate over facts has to join back to the owner and check its flag too.

Languages

project_parameters.project_languages is a protobuf blob; 0A 02 00 14 decodes to field 1 = bytes [0, 20], the list of language codes in use.

Text rows exist per language and are frequently missing for one of them, so any read needs a fallback chain.

Polymorphic references

Notes, citations and media attach to entities through token_on_item(entity_id, item_type) rather than direct foreign keys.

family_individual_connection.individual_role_type

Verified against gender: every role 2 is male, every role 3 is female.

child_order_in_family holds the author's chosen ordering; -1 means unordered.

family_main_data.status

Verified against co-occurring facts — every status 3 family carries a MARR fact, every status 5 a DIV fact, every status 8 a Death of Spouse event.

individual_main_data.is_alive

Despite the name, this is not a boolean.

Facts

individual_fact_main_data.token holds a GEDCOM tag; custom events use EVEN with the real name in fact_type.

Observed: BIRT 1724, DEAT 1658, BURI 299, OCCU 225, CENS 209, RESI 111, CHR 37, BAPM 22, EDUC 22, RELI 18, IMMI 9, NATI 4, PROP 3, DSCR 1, plus custom EVEN subtypes (Settlement, AKA, Hobbies, MYHERITAGE:REL_PARTNERS, …). Family facts: MARR 391, DIV 6.

Three traps

1. date is protobuf, not text — despite the schema comment claiming free text like "22 NOV 1963". The real layout:

0A 0B "19 MAR 1791"          field 1, length 11 — display string
22 2D                        field 4, length 45 — nested date message
   08 01                       modifier (1 = exact, 5 = BETWEEN)
   20 13                       day   = 0x13 = 19
   28 03                       month = 3
   30 FF 0D                    year  = 0x7F | 0x0D<<7 = 1791
   58 E4 0F                    end year for ranges (999999 = none)

The parsed integer columns sorted_date, lower_bound_search_date and upper_bound_search_date (all YYYYMMDD) carry the same information in a far more usable form, so this server reads only field 1 for display and takes structured values from those columns.

Those columns have three distinct ways of saying "there is no date here", and reading any of them as a date invents one:

Each exceeds the magnitude of any real YYYYMMDD — the largest observed is 20250127, and nothing falls between that and 99999999 — so one test on the absolute value recognises all three. Taking 99999999 at face value yields the year 9999, which is larger than every real date and therefore wins any MAX(): it reported AFT 1904 as having an upper bound of 9999, and put 9999 as a tree's latest event year.

2. individual_fact_lang_data.header is protobuf for RESI facts only — 110 of 606 non-empty headers in the sample. Field 1 is address line 1, field 2 the full address. Every other fact type stores plain text in the same column, so the fact's token decides how to read it.

3. Note and citation text is HTML, sometimes escaped twice — notes contain <p> markup and named entities (š, í), and some citation descriptions arrive doubly escaped as <br>, needing two unescape passes before the line break appears.

Empty tables

Empty in kafkova.ftb and ignored by this server: album_main_data, album_lang_data, media_item_to_album_connection, repository_main_data, repository_lang_data, task_main_data, task_lang_data, task_to_individual_connection, individual_family_connection_order, intermediate_state, intermediate_state_ids.

intermediate_state* hold uncommitted editor state and are not genealogical data.