Gedfire

GedFire

Give an AI agent genealogy tools, not a text editor for your GEDCOM.

GedFire is a local Model Context Protocol (MCP) server and command-line tool. It helps an agent find people, compare records, draft cited changes, and validate them before writing your family history. It also generates static family-page websites from the same data.

GedFire supports local MCP mode only, using stdio (standard input/output). Your MCP client launches the installed executable as a local process. There is no remote HTTP, Streamable HTTP or SSE transport, server URL, or listening port. This describes the MCP connection, not where your client's AI model runs.

historical records -> findings -> changesets -> review -> GEDCOM -> website

GedFire handles the mechanics. You and your reviewer judge the evidence. The server exposes nineteen typed tools; only apply_changeset can modify the bound GEDCOM. Other tools can write drafts and reports to separate files. Review and permission limits matter: GedFire validates changes, but it does not collect or authenticate your approval.

Quick start

Install with the .NET 10 SDK:

dotnet tool install --global GedFire

gedfire --version

Or download a self-contained release without installing .NET.

Start with a copy of your GEDCOM. Configure your MCP client to launch:

gedfire mcp --input "C:\Genealogy\family.ged" --read-only --enforce-privacy

Replace the input path with your file's absolute path. Let the client launch the local stdio server rather than running a second copy in a terminal; it communicates through the process streams, not a network connection.

Ask your agent: "How many people and families are in this file?" It should call get_document_stats and report both counts.

--read-only blocks GEDCOM changes, not drafting or report files. --enforce-privacy masks protected and plausibly living individuals in tool output. Keep both flags until you understand the safety and privacy limits.

Try the fictional demo

Browse the generated family pages. CI rebuilds this site from the fictional Ash family on every push. Hover over the footnotes to read each fact's citations.

To run the demo yourself, download or clone this repository. From its root:

Copy-Item docs\demo\ash-whitfield.ged family.ged

gedfire apply --input family.ged --changes docs\demo\proposed-findings.json --items all --dry-run gedfire apply --input family.ged --changes docs\demo\proposed-findings.json --items all gedfire generate --input family.ged --output-dir site --template docs\demo\template.html

The first apply only previews the changes. The second writes them to the copy. Open site/index.html to browse the result. All people, records, places, and sources in the demo are fictional. On Linux or macOS, use cp and / paths.

Why GedFire?

Online trees offer leads, not proof. Repeated claims can spread an error without adding evidence. GedFire supports a different workflow: capture what a record says, identify whom it concerns, then propose a cited change.

• Typed changes, not raw text edits. GedFire applies operations to a parsed GEDCOM document. It checks structure, pointers, and record-count changes before writing.
• Citations travel with facts. Findings carry verbatim extracts, source details, and quality grades. Drafted changes and generated pages retain them.
• Deterministic mechanics. Tools rank identity candidates, reconcile compatible findings, reuse sources, and flag disagreements. The agent supplies the evidence and judgment.
• Rules you control. A policy file can reject banned prose, require verification notes, and demand evidence for a death place.
• Local processing. GedFire makes no network requests and sends no telemetry. Your MCP client controls where tool results go.
• One publishing source. Generate family pages directly from the reviewed GEDCOM rather than maintaining a separate copy of its facts.

Agents exchange compact findings and operations instead of rewriting whole records. Token use depends on the client and task; this README makes no quantified savings claim.

GedFire is not a graphical tree editor, record provider, or hosted genealogy service. It cannot establish that a quotation is genuine or an identification is correct.

Connect an AI client

Choose local or stdio if your client asks for the MCP server type. Configure an executable command and arguments, not a remote server URL.

VS Code / GitHub Copilot

Add this to .vscode/mcp.json in your workspace:

{

"servers": { "gedfire": { "type": "stdio", "command": "gedfire", "args": [ "mcp", "--input", "C:\\Genealogy\\family.ged", "--read-only", "--enforce-privacy" ] } } }

Replace the input path, start the server from VS Code's MCP controls, and approve trust when prompted. Enable its tools in chat. See the VS Code MCP guide for user-level configuration and tool permissions.

Claude Desktop, Claude Code, Cursor, Windsurf, and Gemini CLI

These clients use an mcpServers entry:

{

"mcpServers": { "gedfire": { "command": "gedfire", "args": [ "mcp", "--input", "C:\\Genealogy\\family.ged", "--read-only", "--enforce-privacy" ] } } }

Codex

Add this to .codex/config.toml in the project or ~/.codex/config.toml:

[mcp_servers.gedfire]

command = "gedfire" args = ["mcp", "--input", "C:\\Genealogy\\family.ged", "--read-only", "--enforce-privacy"]

Options and troubleshooting

All examples use Windows paths. On Linux or macOS, replace the input with an absolute path such as /home/me/genealogy/family.ged. JSON and TOML double-quoted strings require escaped backslashes on Windows.

Restart or reload your client after changing its configuration. If startup fails, check:

1. gedfire --version works in a new terminal.
2. The absolute GEDCOM path exists.
3. The client's MCP log shows no startup error.
4. command names an absolute executable path if the client cannot find gedfire on its inherited PATH.

GedFire needs no API keys, credentials, or environment variables.

Research workflow

A finding records what a source says. Capture a verbatim extract, source and locator, source and information classes, claimed facts, and quality grades. Keep conflicting findings instead of flattening them into one conclusion.

Correlation identifies the person. Use find_person for a hinted name lookup or match_record for a household, obituary, or other multi-person record. Inspect the candidates and exclusions. A deterministic match score is not a probability or a substitute for a proof argument.

A changeset specifies the edits. draft_changeset compiles findings into typed operations. It reconciles compatible facts, preserves their citations, and leaves genuine disagreements as open decisions. Fix the findings and draft again when validation exposes a defect.

Findings saved to disk follow GedFire's versioned finding-file schema (gedfire schema finding-file). It holds the draft entry, the identity argument, the record it was matched from, and a meta object that belongs to your own workflow. validate_finding checks those files before drafting, using the same error text draft_changeset gives.

NAME facts can correct the target or an existing relative bound by existingPeople: ["@I10@"] or a relation. Corrections preserve the previous name and its citations in a note. An intentional surname change requires allowSurnameChange: true on the NAME fact.

A proposal presents the case for review. After validate_changeset and check_plausibility, call draft_package. It writes a numbered proposal from the finished changesets, including evidence, grades, and any identity arguments the author supplied.

Apply only what your review process accepts. Select the approved items with apply_changeset. It validates and verifies them again before writing. Generate the site when you are ready to publish.

Source and information classes bound citation quality; they do not prove a claim. A death certificate may offer primary information about death but secondary information about birth. Read the grading and drafting reference for the QUAY ceilings.

The tools

The server binds to one GEDCOM and reloads it when the file changes on disk. Every returned xref belongs to that document only; never reuse it against a different file or provider.

| `val