gedcom-mcp

MCP server for querying local GEDCOM genealogy files through AI assistants. Load any .ged file and search, browse, and traverse your family tree without leaving your AI workflow.

Part of the Genealogy-MCP organization.

Note: GitHub is a read-only mirror. Development happens on GitLab.

Available Tools

Tool	Description
load_file	Load and parse a GEDCOM (.ged) file into memory
search_persons	Search individuals by name, dates, place, sex
get_person	Retrieve a specific individual by cross-reference ID
get_family	Retrieve a family record (accepts family or individual xref)
get_ancestors	Get the ancestor tree for an individual
get_descendants	Get the descendant tree for an individual
get_stats	Get statistics about the loaded GEDCOM file

Configuration

All settings are optional with sensible defaults.

Environment Variable	Default	Description
GEDCOM_MAX_FILE_SIZE_MB	100	Maximum allowed GEDCOM file size in MB
GEDCOM_DEFAULT_ANCESTOR_DEPTH	5	Default ancestor traversal depth
GEDCOM_DEFAULT_DESCENDANT_DEPTH	5	Default descendant traversal depth
GEDCOM_MAX_TREE_DEPTH	50	Hard ceiling on traversal depth
GEDCOM_MAX_SEARCH_RESULTS	100	Maximum search results returned
GEDCOM_ALLOWED_BASE_DIRS	(empty)	Comma-separated allowed directories for file loading

Setup: Claude Desktop

Add to your claude_desktop_config.json:

Using uv (local)

{
  "mcpServers": {
    "gedcom": {
      "command": "uv",
      "args": ["--directory", "/path/to/gedcom-mcp", "run", "gedcom-mcp"],
      "env": {
        "GEDCOM_ALLOWED_BASE_DIRS": "/path/to/your/gedcom/files"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "gedcom": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/gedcom/files:/data:ro",
        "-e", "GEDCOM_ALLOWED_BASE_DIRS=/data",
        "ghcr.io/genealogy-mcp/gedcom-mcp"
      ]
    }
  }
}

Setup: Claude Code

Using uv (local)

claude mcp add gedcom -- uv --directory /path/to/gedcom-mcp run gedcom-mcp

Using Docker

claude mcp add gedcom -- docker run -i --rm \
  -v /path/to/your/gedcom/files:/data:ro \
  -e GEDCOM_ALLOWED_BASE_DIRS=/data \
  ghcr.io/genealogy-mcp/gedcom-mcp

Development

# Install dependencies
make install

# Run tests with coverage
make test

# Run all checks (lint + type-check + test + audit)
make ci

# Format code
make format

# Run via stdio transport
make run-stdio

# Run via streamable-http on port 8000
make run

License

AGPL-3.0-only