GedFire

GedFire is a command-line tool that lets an AI agent help with your family history research without giving it write access to your GEDCOM file. The agent writes its findings as a JSON proposal; you review it, approve the items you want, and GedFire applies them, keeping each citation attached to the claim it supports. It can then generate a static family-page site from the result.

agent research -> JSON proposal -> your review -> verified GEDCOM -> static HTML

GedFire works only with local files and makes no network requests. Your chosen AI client controls where tool results are processed.

Why not just let the agent edit the file? GEDCOM looks like plain text, but the level hierarchy, cross-record pointers, and continuation rules are easy to get wrong — agents asked to rewrite raw GEDCOM tend to produce broken levels, dangling references, or files that no longer validate. GedFire instead applies typed operations to a parsed document and refuses to write anything invalid, so a valid input file stays valid. As a bonus, the agent doesn't have to read and reproduce whole GEDCOM records, which saves a lot of tokens.

Browse a live generated family-page site → Generated from the synthetic family in docs/demo, rebuilt by CI on every push. Facts retain their source citations, available as hover-popover footnotes in the HTML.

MCP server

GedFire also runs as a Model Context Protocol server, so clients including Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI, and Codex can query your GEDCOM directly, in conversation, instead of shelling out to the CLI:

gedfire mcp --input family.ged

Install the global .NET tool before configuring a client. The command above starts a long-running stdio server, so waiting silently for a client connection is normal.

Most MCP clients accept the same local stdio server entry. Add this block to the client's MCP configuration, replacing the GEDCOM path with an absolute path:

{
  "mcpServers": {
    "gedfire": {
      "command": "gedfire",
      "args": [
        "mcp",
        "--input",
        "/absolute/path/to/family.ged"
      ]
    }
  }
}

Use that mcpServers entry in the location your client supports:

Codex uses TOML instead of the JSON wrapper above. Add this to .codex/config.toml in the project or ~/.codex/config.toml:

[mcp_servers.gedfire]
command = "gedfire"
args = ["mcp", "--input", "/absolute/path/to/family.ged"]

Two optional flags follow --input in args (or after --input <path> on the claude mcp add / TOML command lines above):

On Windows, JSON paths use escaped backslashes such as C:\\Users\\me\\family.ged; forward slashes also work. The gedfire command must be available on the environment PATH inherited by the client, or command must contain the absolute path of the executable. GedFire needs no environment variables, API keys, or other credentials.

Restart or reload the client after changing its configuration, approve the local server if prompted, and confirm that it discovers find_person, date_calc, get_document_stats, get_record, describe_changeset_ops, validate_changeset, validate_document, and apply_changeset.

As a smoke test, ask "How many people and families are in this file?" The client should call get_document_stats and report both counts.

The server binds to one document over stdio and exposes eight tools. Seven are read-only; apply_changeset is the only one that writes to the file, and only after validation and in-memory verification both pass (or not at all, if the server was started with --read-only). The server also watches the bound file and reloads automatically if it changes on disk — including a change apply_changeset itself just wrote — no restart needed:

date_calc, find_person, get_document_stats, and get_record also have a one-shot CLI mirror — find-person, get-record, get-document-stats, and date-calc — that runs the same engine and prints the same JSON without starting a server. validate_changeset and apply_changeset mirror the CLI's own apply --dry-run and apply, and validate_document mirrors validate, described under "Command reference" below, rather than having a same-named CLI counterpart of their own.

For example, an MCP client can call find_person with:

{
  "query": "Frederick Morrill",
  "hints": {
    "birth": { "year": 1841, "place": "New Hampshire" },
    "parents": { "father": "Wyman Morrill" },
    "spouse": {
      "name": "Sarah Blake",
      "marriage": { "year": 1865, "place": "Maine" }
    }
  },
  "maxResults": 20
}

Every hint leaf is optional, but each supplied object must contain at least one fact. Birth and death places are event-specific; census or otherwise unclassified places are not hints. Parent names require a known father or mother role. All fields under spouse describe one marriage and are never combined across different marriages. Hints rank only people already recalled by the name query, and missing candidate data is not penalized.

Every result has the same top-level fields: matchType, confidentMatchXref, confidentMatchScore, person, candidates, suggestions, totalMatches, and truncated. Candidates and suggestions always include matchScore. Scores rank evidence within this matcher; they are not statistical probabilities. Use matchType and confidentMatchXref to decide whether the lookup resolved one person. maxResults changes only the returned comparison-list length, never recall, ranking, or confidence classification.