GEDCOM 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"):

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:

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 [email protected]: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:

uv run pre-commit install --install-hooks

License

MIT License - see LICENSE for details.