gedcom-mcp

A small MCP server that reads and searches a GEDCOM 5.5.1 file. It gives an AI agent a fast, structured way to look up individuals, families, sources, and multimedia references in a family tree, and to suggest folder slugs for an archive of per-person pages.

It is tolerant of the custom tags that Ancestry.com exports emit (_APID, _TREE, _PRIM, _OID, and M/D/YYYY dates), but it works with any spec-compliant GEDCOM.

No family data is bundled with this server — you point it at your own .ged file via an environment variable.

Install

Requires Python 3.10+ and uv.

git clone https://github.com/<you>/gedcom-mcp.git
cd gedcom-mcp
uv sync

Configuration

One required environment variable:

Variable	Description
GEDCOM_FILE	Absolute path to the .ged file to load.

The file is parsed lazily on the first tool call and cached in memory.

Tools

Tool	What it does
info	File path, Ancestry tree id (if present), counts by record type.
find_individual(query, limit=25)	Token search over INDI names (incl. AKAs).
get_individual(id)	Full INDI record: events, residences, sources, multimedia, family links, suggested slug, external_ids.
find_family(husband_query, wife_query, marriage_year, limit=25)	Match FAM records by spouses and/or year.
get_family(id)	Full FAM record with husband/wife/children resolved.
list_children(individual_id)	Children across all spouse families.
list_ancestors(individual_id, generations=4)	Bounded ancestor walk.
list_descendants(individual_id, generations=4)	Bounded descendant walk.
get_sources(individual_id)	SOUR citations attached to the person and their events, including Ancestry _APID codes.
suggest_slug(id)	Suggest a stable folder slug for the record (see below).

IDs may be passed with or without @ delimiters (I123 and @I123@ are equivalent).

Running locally

GEDCOM_FILE="/path/to/your-tree.ged" uv run gedcom-mcp

It speaks MCP over stdio.

Registering with an MCP client

Add an entry like this to your MCP client's server config (paths are examples — adjust to your checkout and your .ged file):

{
  "mcpServers": {
    "gedcom": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gedcom-mcp", "gedcom-mcp"],
      "env": {
        "GEDCOM_FILE": "/path/to/your-tree.ged"
      }
    }
  }
}

Output conventions

The server returns plain JSON-shaped data. Dates are normalized to ISO 8601 (YYYY-MM-DD, partial dates allowed). The agent is responsible for turning these dicts into whatever it needs; the server stays out of formatting decisions.

Slug convention

suggest_slug produces a lowercase, hyphenated, ASCII slug intended as a stable folder name for a per-record page:

• Individual: <surname>-<given>-<birthyear> (e.g. smith-john-1901)
• Family: <husband-surname>-<wife-surname>-<marriageyear>

unknown is used for a missing year. This convention is opinionated; if your archive uses a different scheme, adapt suggest_slug / the *_slug helpers in src/gedcom_mcp/model.py.

License

MIT. See LICENSE.