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"
      ]
    }
  }
}

Client	Configuration file
Claude Desktop	Open Settings > Developer > Edit Config to edit claude_desktop_config.json.
Claude Code	.mcp.json in the project root.
Cursor	.cursor/mcp.json in the project, or the client's global mcp.json.
Windsurf	~/.codeium/windsurf/mcp_config.json.
Gemini CLI	.gemini/settings.json in the project, or ~/.gemini/settings.json.

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.

Option	Effect
--read-only	Refuse every apply_changeset call. Leave all other tools available, including draft and report output.
--enforce-privacy	Mask protected and plausibly living people in tool output. See privacy limits.
--policy <json>	Enforce editorial rules during changeset validation and apply. See the example policy and policy reference.

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

• gedfire --version works in a new terminal.
• The absolute GEDCOM path exists.
• The client's MCP log shows no startup error.
• 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.

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.

Tool	Purpose
get_document_stats	Report person and family counts, GEDCOM version, and GedFire version.
find_person	Rank name matches with optional birth, death, parent, and marriage hints.
find_family	Find a person through a named spouse, parent, or child.
find_source	Find existing sources by title, author, or URL.
get_record	Fetch a person, family, or source with citations and optional source text.
get_records	Fetch several records at once, optionally selecting fields.
list_people	Page through people in stable surname/name/xref order.
list_unanchored_people	Find people with no dated or placed anchors of their own or through immediate kin.
match_record	Compare a multi-person record with tree families and survey same-name rivals.
research_brief	Summarize a person's facts, kin, gaps, notes, duplicates, and plausibility issues.
select_targets	Score research gaps and draw targets, or score specified people.
date_calc	Normalize dual dates, add or subtract ages, or calculate elapsed time.
describe_changeset_ops	Return the changeset envelope, operation schemas, and worked examples.
draft_changeset	Compile findings into cited changesets and report unresolved decisions.
draft_package	Write a review proposal from finished changesets.
validate_changeset	Preview selected edits, enforce policy, and optionally score gap closures.
check_plausibility	Report chronological and biological issues the edits would introduce.
validate_document	Check the whole document for GEDCOM 7 conformance.
apply_changeset	Validate, apply, and verify selected items, then write the GEDCOM.

Use the advertised MCP schemas for exact parameters and the MCP reference for behavior and examples. Every tool rejects missing required parameters and unrecognized parameters. The error names the offending fields and lists the accepted ones.

Safety and review

What GedFire enforces

• Dry-run and apply use the same validation. If an operation fails validation, GedFire writes nothing.
• Path-based apply holds an exclusive file lock from the initial read through the verified write to prevent competing GedFire writers from racing.
• Before creating a person, validation rejects high-confidence duplicates among existing and planned people. Ambiguous candidates do not block creation.
• Before writing, GedFire checks a byte-stable reparse/format round trip, pointer resolution, and expected record-count changes.
• --read-only refuses apply calls even if the client approves them.
• A configured policy can reject a changeset at both preview and apply.

Keep backups or version history. Structural validation cannot catch every genealogical mistake.

What you and your client control

GedFire does not authenticate reviewer approval. apply_changeset accepts the caller's selected items; it does not verify that a human or independent reviewer approved them. A proposal supports consent but does not enforce it.

Use your MCP client's tool permissions to control apply access. For a hard GEDCOM write block, keep --read-only. Remove it only when you intend to allow writes. Decide explicitly whether a human must approve each change or whether you authorize an automated review workflow. GedFire does not require a human gate; an independent model can review every item.

Validation checks the edits, not the truth of the evidence. Review quotations, identity arguments, source independence, and unresolved conflicts yourself or through a reviewer you trust.

Privacy

GedFire makes no network requests and sends no telemetry. Your chosen client may send tool results to a model provider; local processing does not make the whole conversation local.

--enforce-privacy uses the site's privacy filter. It masks individuals with RESN CONFIDENTIAL or RESN PRIVACY, plus plausibly living people: no death-class fact and a birth within the last 100 years. Their tool views become Living <Surname> placeholders without dates, places, notes, or media.

The filter uses recorded facts, not verified living status. Placeholders still reveal surnames. Without a birth year or explicit restriction, the age heuristic does not mask a person. The flag does not promise to redact every mention in other records or user-supplied text. Inspect your data and your client's privacy settings before sharing results.

Installation

Install as a .NET tool

Requires the .NET 10 SDK:

dotnet tool install --global GedFire
gedfire --version

To update: dotnet tool update --global GedFire.

Download a release

Download your platform's archive from GitHub Releases and extract it. These self-contained binaries do not require a separate .NET install.

On Windows, run .\GedFire.exe help. On Linux or macOS, run ./GedFire help.

The command line

The CLI uses the same engine as the MCP server.

Command	Purpose
create	Create a seeded GEDCOM 7 document.
upgrade / downgrade	Convert between GEDCOM 5.5 and 7.
validate	Check GEDCOM 7 conformance.
apply	Preview or apply selected changeset items; use --dry-run to preview.
generate	Generate static family pages, with optional media staging.
export-index	Export a JSON person-name index.
select-targets	Detect, score, and draw research gaps for study surnames.
date-calc	Normalize dual dates or calculate dates and ages.
find-person / get-record / get-document-stats	Run one lookup and print JSON without starting a server.
pack / unpack	Create or extract a GEDZIP archive.
mcp	Start the local-only stdio MCP server; no HTTP or remote transport.
tools list / tools describe / tools call	Discover or invoke any MCP tool directly using the same JSON schemas and handlers.

Run gedfire help for command syntax. See the MCP reference for changeset semantics and date-arithmetic examples.

Use tools from scripts

Every MCP tool is also available as a one-shot command, without a server or AI client:

gedfire tools list
gedfire tools describe find_person
gedfire tools call find_person --input family.ged --args request.json --out result.json --enforce-privacy

The arguments file contains exactly the MCP tool's arguments object, for example:

{"query":"Mara Example","maxResults":8}

Use --args - to read JSON from stdin, or omit --args for {}. Results are JSON on stdout unless --out names a new file; existing output files are refused. Diagnostics go to stderr. The exit code is 0 on success and 1 on errors or failed validation/plausibility checks.

--policy, --read-only, and --enforce-privacy have the same meaning as on mcp. Read-only prevents GEDCOM changes, not separate draft or report files. Discovery needs no GEDCOM, and calls to date_calc and describe_changeset_ops need no --input. Existing convenience commands remain unchanged. See the script interface for output details.

Building from source

Requires the .NET 10 SDK:

git clone https://github.com/morrillonline/GedFire.git
cd GedFire
dotnet build --nologo
dotnet test --nologo
.\GedFire\bin\Debug\net10.0\GedFire.exe help

The solution contains GedCore (engine), GedFire (CLI, MCP server, and site generator), and GedCore.Tests.

Versions follow VersionMajor.VersionMinor.BuildNumber. Directory.Build.props defines major/minor (currently 4.1). Local builds default to build number 1; CI supplies its workflow run number, and release builds use the final segment of a v<major>.<minor>.<build> tag. Set -p:BuildNumber=<build> on dotnet build, test, or publish to reproduce a build number locally.

Standards and contributing

GedFire independently implements FamilySearch GEDCOM 7. It has no affiliation with or endorsement from FamilySearch or The Church of Jesus Christ of Latter-day Saints. See the official specification repository and registries for standards and extensions.

Bug reports, pull requests, and synthetic edge-case fixtures are welcome. Never include private family data in an issue, fixture, or pull request. Run dotnet test --nologo before opening a PR.

License

MIT.