家谱数据查询MCP服务

GEDCOM MCP Server

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

Features

Version 2.0 advertises 9 read-only tools, or 13 with edits enabled. A consolidated interface covers tree context, people search, batch person views, qualified relatives, relationships, evidence timelines and original records. Specialized research and exact edit schemas are discovered on demand using search_tools; call_research_tool executes reads only.

• All research functionality retained: source/repository reads, reverse citations, event search, GIS proximity, place/surname analysis, military evidence, associates, pedigree collapse and whole-tree audit.
• Explicit editing stages: prepare_change previews person creation, name corrections, atomic record batches or restoration; apply_tree_change applies a specifically reviewed proposal. maintain_tree creates backups/exports.
• Evidence preserved: original fields, unknown tags, alternate facts, citations, date text and qualified parent-family assertions remain available.
• Bounded results: summary/detail views, pagination, snapshot guards and traversal limits keep results useful without silently hiding incompleteness.
• Six resources: individual, family, source, sources, statistics and surnames.
• Large-tree indexes: GEDCOM parses once at startup; search and graph reads use in-memory indexes.

This is a new major interface, with no legacy aliases or compatibility profile. See API.md for the complete interface and discovery examples, RESEARCH_TOOLS.md for evidence semantics and research gaps, and WRITES.md for versioned edit guarantees.

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 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

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.

ChatGPT deployment

The authenticated Rivendell deployment is documented in deploy/README.md, including the OAuth portal URL, service operations, credential rotation, and rollback.

Versioned writes (opt-in)

The original GEDCOM remains an immutable baseline. Optional write tools support reviewed field/subtree corrections, multiline notes, citations, sourced events, reciprocal relationship edits, evidence-preserving person merges, explicit deletion/pruning, revision history, whole-tree undo, lossless exports, and verified backups. A record inventory locates sources, repositories, media, shared notes and custom records for editing. Subtree hashes guard evidence-preserving updates and explicit replacement/removal; source creation and citation can share one atomic batch. A whole-tree audit and conservative pruning planner expose review blockers and selected force=true overrides before any change is applied. Unchanged records are shared between revisions to keep storage growth small. See WRITES.md for configuration, limitations, recovery, and the replaceable editor interface.