gedcom-mcp
MCP server for reading, searching, and editing GEDCOM family-tree files (.ged) with lossless writes and backups.
Read tools: list files, file summaries, search individuals by name/place/years/sex, get full individual records, family records, source records, ancestor and descendant trees.
Write tools: create/rename GEDCOM files, add/update/remove individuals, set/remove events/facts, add notes, create families, add children, set parents, and delete individuals with back-reference cleanup.
Safety: every edit writes a .bak backup, stamps CHAN dates, preserves unknown tags/encoding/line endings, and saves atomically.
Resources:
gedcom://{file}summary andgedcom://{file}/person/{id}person cards for MCP resource-aware clients.
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., "@gedcom-mcp Find the parents of John Smith, born about 1840 in Bristol."
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.
gedcom-mcp
A Model Context Protocol server that lets Claude (or any MCP
client) read, search and edit GEDCOM .ged family-tree files — the export format used by
Ancestry.com, FamilySearch, MyHeritage, Gramps, RootsMagic, Family Tree Maker and most other
genealogy software.
Point it at a folder of .ged files and ask things like:
"Who were the parents of John Smith, born about 1840 in Bristol?" "Show me four generations of ancestors for @I123@." "Add a burial for Mary Jones on 3 May 1901 at St Mary's, Islington." "Which source records cite the 1881 census?"
Edits are written straight back to the file — safely, with a backup, and without disturbing anything you didn't touch.
Contents
Related MCP server: gedcom-mcp
Features
Current MCP SDK — built on
mcp>=2.2(MCPServer, structured/typed output, tool annotations for read-only / destructive hints).Proper search — free-text name search that is case- and accent-insensitive (
Müllermatchesmuller), ranked by match quality; filter by given name, surname, birth/death year ranges, place and sex; paginated.Relationship navigation — parents, spouses, children, siblings; N-generation pedigree (ancestor) and descendant trees, with children grouped per marriage.
Sources, citations and notes — full source records, per-fact citations (including Ancestry's
_APIDrecord ids), and note text everywhere it appears.Editing — add, update and remove people; create or update any event/fact; add notes; create families; link children to parents; delete people cleanly (all back-references removed).
Lossless — the file is held as a line tree and only lines you actually change are re-rendered. Unknown and vendor tags (
_APID,_OID,OBJE,_MILT, …), record order, character encoding, byte-order mark and line endings all survive byte-for-byte. Round-tripping a file without edits produces an identical file.Safe — every edit writes a
<name>.ged.bakfirst, then saves atomically. File names are plain names inside the configured directory: no path traversal, no globs, no writes anywhere else.No log files — diagnostics go to stderr only; nothing is written next to your data.
Any GEDCOM 5.5 / 5.5.1 file — tested against Ancestry.com exports (BOM + CRLF, ~2,300 people) and standard fixtures.
Requirements
Python 3.10 or newer
uv(recommended) orpipAn MCP client — Claude Code, Claude Desktop, Cursor, VS Code Copilot, etc.
Installation
Clone the repository and create a virtual environment:
git clone https://github.com/ggoosen/gedcom-mcp.git
cd gedcom-mcp
# with uv (recommended)
uv venv
uv pip install -e .
# or with plain pip
python -m venv .venv
.venv/Scripts/activate # Windows
source .venv/bin/activate # macOS / Linux
pip install -e .This installs a gedcom-mcp console script into the virtual environment:
Platform | Executable |
Windows |
|
macOS / Linux |
|
You'll need that full path when registering the server with a client (clients don't activate your venv for you).
Tip: if you'd rather not clone,
uv tool install git+https://github.com/ggoosen/gedcom-mcpinstallsgedcom-mcponto yourPATH, or run it ad hoc withuvx --from git+https://github.com/ggoosen/gedcom-mcp gedcom-mcp --gedcom-path DIR.
Running the server
The server speaks MCP over stdio. It takes one required setting — the directory that holds
your .ged files:
gedcom-mcp --gedcom-path "C:/Users/you/Documents/Genealogy"
# or
GEDCOM_PATH="/home/you/genealogy" gedcom-mcpOptions:
Flag | Description |
| Directory containing |
| Debug logging on stderr. |
| Show help. |
Run from a terminal it will simply wait for a client on stdin — that's normal. Press Ctrl+C to
exit. Normally you don't run it yourself; the MCP client launches it.
Put your files in a dedicated folder. The server can read and write every .ged in the
directory, so don't point it at a folder that also holds files you'd rather it never touched.
Keep your own backups too — the .bak only holds the state before the most recent edit.
Connecting an MCP client
Claude Code
Register the server for the current project (local scope):
# Windows
claude mcp add gedcom -- "C:/path/to/gedcom-mcp/.venv/Scripts/gedcom-mcp.exe" --gedcom-path "C:/Users/you/Documents/Genealogy"
# macOS / Linux
claude mcp add gedcom -- /path/to/gedcom-mcp/.venv/bin/gedcom-mcp --gedcom-path /home/you/genealogyAdd --scope user to make it available in every project, or --scope project to write a
shareable .mcp.json into the current repo. Check with claude mcp list; remove with
claude mcp remove gedcom.
Equivalent .mcp.json (project scope):
{
"mcpServers": {
"gedcom": {
"type": "stdio",
"command": "C:/path/to/gedcom-mcp/.venv/Scripts/gedcom-mcp.exe",
"args": ["--gedcom-path", "C:/Users/you/Documents/Genealogy"]
}
}
}Once registered, start Claude Code in that project and the tools appear as mcp__gedcom__*.
Try: "list the gedcom files and give me a summary of the first one."
Claude Desktop
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
Windows:
%APPDATA%\Claude\claude_desktop_config.jsonmacOS:
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"gedcom": {
"command": "C:/path/to/gedcom-mcp/.venv/Scripts/gedcom-mcp.exe",
"args": ["--gedcom-path", "C:/Users/you/Documents/Genealogy"]
}
}
}Restart Claude Desktop. The server shows up under the tools (🔨) icon.
Cursor, Windsurf, VS Code and others
Any client that supports stdio MCP servers works with the same shape — a command and args.
For example, VS Code (.vscode/mcp.json):
{
"servers": {
"gedcom": {
"type": "stdio",
"command": "/path/to/gedcom-mcp/.venv/bin/gedcom-mcp",
"args": ["--gedcom-path", "/home/you/genealogy"]
}
}
}You can also pass the directory via the environment instead of args:
"env": { "GEDCOM_PATH": "/home/you/genealogy" }Usage
The intended workflow is:
list_files(orfile_summary) — see what's there.search_individuals— find people and get their ids.get_individual/get_family/get_ancestors/get_descendants/get_source— drill in.The write tools — make changes; each returns a short confirmation and saves immediately.
Claude figures this out on its own from the tool descriptions; you just ask questions in plain English.
Ids and file names
Record ids are GEDCOM cross-references including the
@signs:@I12@(individual),@F3@(family),@S7@(source). Ancestry exports use long numeric ids such as@I200180069284@; those work too.File names are plain names relative to the configured directory, with or without the
.gedextension:Smith Family TreeorSmith Family Tree.ged. Path separators,.., globs and control characters are rejected.filemay be omitted on every tool when the directory contains exactly one.gedfile. With several files, the error message lists the available names.
Dates
Dates are GEDCOM-style and are normalised on write:
Input | Meaning |
| Exact date |
| Partial date |
| Approximate / estimated / calculated |
| Before / after |
| Range |
| Period |
Year filters in search_individuals (birth_year_from, etc.) understand all of these forms.
Example conversations
Finding someone
You: Find anyone called Smith born in Bristol between 1830 and 1850.
Claude calls
search_individuals(surname="Smith", place="Bristol", birth_year_from=1830, birth_year_to=1850)and returns a ranked list with ids, life spans and birth places.
Exploring a family
You: Show me William Smith's family and four generations of his ancestors.
Claude calls
get_individual(id="@I1@")— parents, every marriage with its children, siblings, all facts with citations — thenget_ancestors(id="@I1@", generations=4).
Correcting a record
You: William's birth date is wrong — it should be 12 March 1841, and add a note that this came from his baptism register entry.
Claude calls
set_event(id="@I1@", tag="BIRT", date="12 MAR 1841")andadd_note(id="@I1@", text="Birth date corrected from baptism register …"). Both save immediately with a.bakwritten first.
Adding a new person and linking them
You: Add a daughter for William and Mary, Elizabeth, born 4 June 1866 in Bristol.
Claude calls
add_individual(given="Elizabeth", surname="Smith", sex="F", birth_date="4 JUN 1866", birth_place="Bristol, Gloucestershire, England")which returns@I9@, thenset_parents(child_id="@I9@", father_id="@I1@", mother_id="@I2@")— reusing William and Mary's existing family record.
Tracing sources
You: What does source @S2@ cover and who is cited against it?
Claude calls
get_source(id="@S2@")— title, author, publisher, repository, Ancestry_APID, and every individual/fact that cites it.
Tool reference
Every tool accepts an optional file argument (see Ids and file names).
Read tools
All read tools are annotated readOnlyHint so well-behaved clients won't prompt for approval.
Tool | Parameters | Returns |
| — | Each |
|
| Record counts (individuals, families, sources, notes), originating software, earliest/latest year, top surnames. |
|
| Ranked matches with id, name, sex, birth and death (date + place), plus |
|
| Full record: all names, every event/fact with date, place, value, citations and notes; parents; each marriage with spouse and children; siblings; |
|
| Husband, wife, children (with life spans), marriage/divorce and other family events, notes, citations. |
|
| Pedigree tree — each node is a person with |
|
| Descendant tree — each node lists marriages, and each marriage its children as sub-trees. |
|
| Title, author, publication, repository, Ancestry |
Write tools
Write tools save immediately. Each one first writes <name>.ged.bak, then replaces the file
atomically, and stamps the touched record with a CHAN (change date) entry. Tools that delete
data are annotated destructiveHint so clients can ask for confirmation.
Tool | Parameters | What it does |
|
| Create a new, empty GEDCOM 5.5.1 file (UTF-8, with header and submitter). |
|
| Rename a file. Refuses to overwrite an existing one. |
|
| Add a person. Returns the new |
|
| Change name parts and/or sex. Only supplied fields change; other name sub-tags are kept. |
|
| Create or update a fact. |
|
| ⚠️ Delete the Nth fact with that tag, including its citations and notes. |
|
| Attach a free-text note. Multi-line text is folded into |
|
| Create an |
|
| Add an existing person as a child of an existing family. |
|
| Make the named people the child's parents. Reuses the parents' existing family if they already have one together (or fills the empty spouse slot of a one-parent family), otherwise creates a new one. |
|
| ⚠️ Delete a person and every reference to them (as spouse or child). Families left with no members are removed as well. |
All write tools return a WriteResult with the affected id, a human-readable message, and the
path of the backup that was written.
Resources
For clients that support MCP resources:
URI | Content |
| Markdown summary of the file (same data as |
| A Markdown card for one person — handy to attach to a conversation as context. |
How editing works (safety guarantees)
GEDCOM files from commercial software are full of vendor extensions, odd ordering and encoding quirks, and most parsers silently drop or rewrite things they don't understand. This server avoids that entirely:
The file is parsed into a tree of lines, and every line keeps its original raw bytes.
Only a line that you actually change is re-rendered; everything else is written back exactly as it was read.
parse(data).to_bytes() == dataholds for every file we've tried.CONT/CONCcontinuation lines are handled as ordinary children of a line, so note text with embedded newlines or stray carriage returns round-trips correctly.Before saving, the previous content is copied to
<name>.ged.bak; the new content is then written to a temporary file and atomically renamed over the original, so a crash mid-write can't leave you with a truncated file.Edited records get a
CHAN/DATE/TIMEstamp (local time, per GEDCOM convention) so you can see in any genealogy program what was touched.Deleting a person walks every family and removes their
HUSB/WIFE/CHILreferences; families left with nobody in them are deleted too. No dangling pointers.
Files are cached in memory and re-read automatically when their modification time or size changes, so you can edit them in other software while the server is running.
Working with Ancestry.com exports
Ancestry's Export tree produces a GEDCOM 5.5.1 file with a UTF-8 BOM, CRLF line endings, long numeric ids and a number of custom tags. All are preserved:
_APID— Ancestry's record-collection id on each citation. Surfaced on citations and sources so you can trace a fact back to the exact Ancestry record._OID,_MTYPE,_PRIM,OBJE— media links and metadata. Preserved untouched._MILT,_DEG,_EMPLOYetc. — custom facts. Preserved, and readable/editable viaset_eventwith the raw tag name.
Editing an Ancestry export and re-importing it is up to Ancestry (their importer creates a new tree rather than merging), but the file stays valid for any desktop program — Family Tree Maker, RootsMagic, Gramps, Legacy — and for re-upload.
Development
uv venv && uv pip install -e ".[dev]"
pytest # 51 tests, ~1.5 s
ruff check src tests # lint
ruff format src tests # format
pyright # type-check
python tests/make_fixture.py # regenerate tests/fixtures/sample.gedTests cover the lossless parser (round-trip of BOM + CRLF fixtures and files with embedded
\r), the person/family model, search ranking and filters, every write tool (save → reload →
assert, and untouched records byte-identical), and the MCP surface itself through an in-memory
mcp.Client.
The .gitattributes marks *.ged as binary so fixture bytes are never altered by line-ending
normalisation on checkout.
Architecture
src/gedcom_mcp/
__main__.py CLI entry point (argparse → configure → mcp.run())
server.py MCPServer instance; all @mcp.tool / @mcp.resource; converters to schemas
config.py Settings: root directory, safe file-name resolution, per-file cache
schemas.py pydantic output models (MCP structured output)
gedcom/
lines.py Lossless line tree: GedLine / GedDocument, parse_bytes() / to_bytes()
file.py GedcomFile: load, xref index, CHAN stamping, atomic save + .bak
model.py Person / Family / Event / Citation / Source views over the line tree
search.py ranked search; ancestors() / descendants() walkers
edit.py every mutation (add/update/remove person, set_event, families, notes)
dates.py year extraction, normalisation, today's date in GEDCOM form
names.py "Given /Surname/ Suffix" parsing; accent-insensitive folding
tests/ pytest; fixtures/sample.ged is a synthetic Ancestry-style fileData flows lines.py → file.py → model.py → search.py / edit.py → server.py. The
line tree is the single source of truth; the model classes are thin views over it, and edits
mutate the tree directly so nothing has to be "serialised back".
Dependencies: mcp (server framework),
pydantic (output models), and
ged4py — used only for its date parser and encoding
detection, not as the storage layer.
Troubleshooting
The client says the server failed to start / no tools appear.
Run the exact command from your config in a terminal. --gedcom-path must be an existing
directory; the message will tell you if it isn't. On Windows use forward slashes or escaped
backslashes in JSON.
No .ged files in …
The directory is right but empty. Files must end in .ged (lower-case is safest).
Several GEDCOM files are available; pass 'file'
More than one .ged in the directory — ask for the one you want by name.
Invalid file name
File names must be bare names (My Tree or My Tree.ged), not paths.
Non-ASCII names don't display correctly.
The file's declared CHAR is honoured (UTF-8, ANSEL, ASCII, …) and the encoding is auto-detected
when the header is wrong. If a file was mis-encoded by the exporting software the text will look
wrong everywhere, not just here.
I want to undo an edit.
Copy <name>.ged.bak back over <name>.ged. Only the most recent pre-edit state is kept, so for
longer histories keep the folder under version control or take periodic copies.
Enable debug output.
Add -v to the args; output goes to stderr, which the client captures in its MCP log (Claude
Desktop: Settings → Developer → Open Logs Folder; Claude Code: /mcp shows server status).
License
MIT © George Goosen
Available Tools
19 toolsadd_childA
Add an existing individual as a child of an existing family.
Inputs: child_id (required), family_id (required), file. Returns: id, file, backup, message
add_familyB
Create a family (@F..@) linking spouses and/or children; FAMS/FAMC back-links are written too.
Inputs: file, wife_id, child_ids, husband_id, +2 more. Returns: id, file, backup, message
add_individualB
Add a new individual and save. Returns the new @I..@ id; link them with add_family / set_parents.
Inputs: given (required), surname (required), sex, file, +5 more. Returns: id, file, backup, message
add_noteC
Attach a free-text note to a record.
Inputs: id (required), text (required), file. Returns: id, file, backup, message
create_fileA
Create a new, empty GEDCOM 5.5.1 file in the server's directory.
Inputs: name (required). Returns: id, file, backup, message
file_summaryARead-onlyIdempotent
Overview of a GEDCOM file: record counts, originating software, year range, most common surnames.
Inputs: file. Returns: file, notes, sources, families, +5 more
get_ancestorsARead-onlyIdempotent
Pedigree tree (father/mother recursively) for an individual, up to N generations.
Inputs: id (required), file, generations. Returns: father, mother, person, truncated, +1 more
get_descendantsARead-onlyIdempotent
Descendant tree (children per marriage, recursively) for an individual, up to N generations.
Inputs: id (required), file, generations. Returns: person, families, truncated, generation
get_familyBRead-onlyIdempotent
One family record (@F..@): spouses, children, marriage and other family events.
Inputs: id (required), file. Returns: id, wife, notes, events, +3 more
get_individualBRead-onlyIdempotent
Full record for one individual: names, all events/facts, notes, citations, parents, spouses, children, siblings.
Inputs: id (required), file, include_notes, include_sources. Returns: id, sex, name, given, +11 more
get_sourceBRead-onlyIdempotent
A source record (@S..@): title, author, publisher, repository, Ancestry _APID, and who cites it.
Inputs: id (required), file. Returns: id, apid, text, notes, +6 more
list_filesARead-onlyIdempotent
List the GEDCOM (.ged) files available to this server.
Inputs: no named parameters. Returns: result
remove_eventBDestructive
Delete the index-th fact with the given tag from an individual or family.
Inputs: id (required), tag (required), file, index. Returns: id, file, backup, message
remove_individualADestructive
Delete an individual and all references to them. Families left with no members are removed too.
Inputs: id (required), file. Returns: id, file, backup, message
rename_fileB
Rename a GEDCOM file. Refuses to overwrite an existing file.
Inputs: file (required), new_name (required). Returns: id, file, backup, message
search_individualsARead-onlyIdempotent
Search individuals by name, birth/death year range, place or sex.
Matching is case- and accent-insensitive. Results are ranked: exact full-name matches first,
then surname/given matches, then partial matches; ties sort by surname then given name.
Inputs: sex, file, given, limit, +8 more. Returns: total, offset, results
set_eventA
Create or update an event/fact on an individual or family (e.g. set a birth date, add an occupation).
Inputs: id (required), tag (required), date, file, +4 more. Returns: id, file, backup, message
set_parentsB
Make father/mother the parents of a child, reusing their existing family or creating one.
Inputs: child_id (required), file, father_id, mother_id. Returns: id, file, backup, message
update_individualB
Change an individual's given name, surname and/or sex. Only supplied fields change.
Inputs: id (required), sex, file, given, +1 more. Returns: id, file, backup, message
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools have clearly distinct purposes (e.g., get_ancestors vs get_descendants, add_individual vs update_individual). However, set_parents and add_family both create family links, and add_child could be seen as a special case of add_family, causing slight overlap. Descriptions mitigate this by clarifying specific use cases.
All tool names follow a consistent verb_noun pattern (list_files, get_ancestors, add_individual, remove_event, etc.). No deviations or mixing of conventions.
19 tools is on the higher end but appropriate for a GEDCOM server covering querying, traversal, and CRUD operations. Each tool appears to serve a distinct function, though the count could be slightly consolidated.
The surface covers most CRUD and traversal needs: file management (list, create, rename), individual and family creation/update/deletion, event handling, notes, and sources. However, there is no explicit tool to remove or update families, and no direct way to delete a note or source, leaving minor gaps.
Maintenance
Related MCP Connectors
MCP server for Gramps genealogy via the Gramps Web API: CRUD, search, merge, timelines, DNA.
Human Lineage MCP server — search and query the public genealogical graph of all humanity
Remote MCP server to read and edit GanttFather projects: tasks, dates, dependencies, critical path.
Pedigree charts from GEDCOM
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to create, edit, and query genealogical data from GEDCOM files. Supports complex genealogy searches, automatic data enrichment from web sources, relationship analysis, and biography generation for individuals and families.17MIT
- AlicenseAqualityDmaintenanceReads and searches GEDCOM 5.5.1 files, enabling AI agents to look up individuals, families, sources, and multimedia references in a family tree.10MIT
- AlicenseNot gradedqualityBmaintenanceRead-only MCP server for genealogy data from Family Tree Builder (.ftb) or GEDCOM files, exposing tools for person search, family relationships, and statistical analysis via HTTP or stdio.2Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to query, validate, and safely update GEDCOM family-history files through a local MCP server with read-only tools and reviewable changesets.1MIT