GEDCOM MCP Server

GEDCOM MCP Server

A FastMCP server that enables AI assistants to query genealogy data from GEDCOM files.

Features

• 24 MCP Tools for comprehensive genealogy research:

Core Tools:

• get_home_person - Get the tree owner's record
• get_statistics - Tree stats (counts, date ranges, top surnames)
• get_individual - Get basic details by ID
• get_biography - Get comprehensive narrative package for one person
• get_family - Get family info (spouses, children, marriage)

Navigation Tools:

• get_parents - Get parents of an individual
• get_children - Get all children from all marriages
• get_spouses - Get all spouses with marriage details
• get_siblings - Get siblings (same parents)
• get_ancestors - Ancestor tree up to N generations
• get_descendants - Descendant tree up to N generations
• traverse - Generic graph traversal for custom navigation

Search & Discovery:

• search_individuals - Search by name (partial match)
• semantic_search - Vector-based semantic search (e.g., "farmers in Scotland")
• search_nearby - GIS proximity search or bounding box search

Relationship Analysis:

• get_relationship - Calculate relationships between two people
• detect_pedigree_collapse - Find ancestors appearing multiple times
• find_associates - FAN Club technique (Friends, Associates, Neighbors)

Timeline & Events:

• get_timeline - Chronological life events for an individual
• get_military_service - Find all veterans in the tree

Place & Surname Analysis:

• get_place_cluster - Get all people connected to a location
• get_surname_origins - Analyze surname distribution and geographic origins

Natural Language:

• query - Natural language questions (fallback for non-agent MCP clients)

• 4 MCP Resources:
• gedcom://individual/{id} - Individual record by ID
• gedcom://family/{id} - Family record by ID
• gedcom://stats - Tree statistics
• gedcom://surnames - All surnames with counts

• Optimized for large files - Parses GEDCOM once at startup, builds in-memory indexes for fast search

Optional Features

Semantic Search Enable natural language semantic matching (e.g., "coal miners in Pennsylvania", "emigrated from Ireland"): ``bash export SEMANTIC_SEARCH_ENABLED=true `` Requires sentence-transformers (included in dependencies). First run builds embeddings (~15-30 seconds for large files), subsequent runs load from cache.

GIS Proximity Search Find people within X miles of a location or within a region's bounding box. Enabled by default with background geocoding. Results include:

• Proximity mode: Within X miles of a point
• Within mode: Inside a region's bounding box

No configuration needed - geocoding runs automatically at startup and caches results.

Telemetry & Observability OpenTelemetry tracing with Arize Phoenix for debugging and performance monitoring: ``bash export PHOENIX_ENABLED=true ` Requires Phoenix server running (see .env.example and docker-compose.yml`).

Installation

Using uvx (recommended, no install needed)

uvx gedcom-server --gedcom-file /path/to/your/tree.ged

Using uv tool install

uv tool install gedcom-server
gedcom-server --gedcom-file /path/to/your/tree.ged

From source

git clone git@github.com:sjmatta/gedcom-mcp.git
cd gedcom-mcp
uv sync

Configuration

The server requires a GEDCOM file path. Optionally, you can specify a "home person" (the tree owner).

Configuration Options

| Method | Option | Description | |--------|--------|-------------| | CLI arg | --gedcom-file, -f | Path to GEDCOM file | | Env var | GEDCOM_FILE | Path to GEDCOM file | | CLI arg | --home-person, -p | GEDCOM ID of home person (e.g., @I123@) | | Env var | GEDCOM_HOME_PERSON_ID | GEDCOM ID of home person |

CLI arguments override environment variables.

If --home-person is not specified, the server auto-detects the most connected individual in the tree.

Examples

# Using CLI arguments
gedcom-server --gedcom-file ~/Documents/family.ged

# Using environment variables
export GEDCOM_FILE=~/Documents/family.ged
gedcom-server

# With explicit home person
gedcom-server -f ~/Documents/family.ged -p @I500@

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

Using uvx (recommended)

{
  "mcpServers": {
    "gedcom": {
      "command": "uvx",
      "args": ["gedcom-server"],
      "env": {
        "GEDCOM_FILE": "/path/to/your/tree.ged"
      }
    }
  }
}

Using uv tool install

{
  "mcpServers": {
    "gedcom": {
      "command": "gedcom-server",
      "args": ["--gedcom-file", "/path/to/your/tree.ged"]
    }
  }
}

From source

{
  "mcpServers": {
    "gedcom": {
      "command": "/path/to/gedcom-mcp/.venv/bin/python",
      "args": ["-m", "gedcom_server"],
      "env": {
        "GEDCOM_FILE": "/path/to/your/tree.ged"
      }
    }
  }
}

GEDCOM File

The server supports GEDCOM 5.5.1 format, which can be exported from:

• Ancestry.com
• FamilySearch
• MyHeritage
• Gramps
• Most other genealogy software

Development

# Install dev dependencies
uv sync

# Run tests
uv run poe test

# Run linter
uv run poe lint

# Run formatter
uv run poe format

# Run type checker
uv run poe typecheck

# Run all checks
uv run poe check

# Start server (requires GEDCOM_FILE env var)
uv run poe serve

For detailed development instructions, see CONTRIBUTING.md.

Pre-commit Hooks

Pre-commit hooks are configured for:

• Pre-commit: ruff linting, ruff formatting, mypy type checking
• Pre-push: pytest test suite

Install hooks: ``bash uv run pre-commit install --install-hooks ``

License

MIT License - see LICENSE for details.