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

Related MCP server: GEDCOM MCP Server

Configuration

One required environment variable:

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

Tools

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.