Skip to main content
Glama
mcp-geneanet

mcp-geneanet

by mgcrea
README.md
# @mgcrea/mcp-genealogy

A [Model Context Protocol](https://modelcontextprotocol.io) server for genealogy records. It
reads people out of several genealogy sources, answers in one shared shape whatever the source,
and writes what you collect to a GEDCOM 7.0 file.

| Source                              | Status     | What it gives                                                                  |
| ----------------------------------- | ---------- | ------------------------------------------------------------------------------ |
| [Geneanet](https://en.geneanet.org) | available  | Site-wide search of every public tree and archive index; persons and pedigrees |
| [matchID](https://deces.matchid.io) | next phase | France's INSEE death index, with exact dates and certificate numbers           |
| [Geni](https://www.geni.com)        | later      | The world tree, with OAuth                                                     |

It is **read-only toward every source and needs no account.** The only thing it writes is the
GEDCOM file, in one folder of your choosing.

## Tools

| Tool                      | What it does                                                                         | Requests                                     |
| ------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------- |
| `geneanet_search_records` | Search all Geneanet trees and archive indexes at once for one individual             | 1 per page                                   |
| `geneanet_search_tree`    | Search one tree by surname and/or first name, with each match's parents and spouses  | 1                                            |
| `geneanet_get_person`     | One person's full record: events with places, sources, notes and witnesses           | 1 (2 with n/p)                               |
| `geneanet_get_people`     | Up to 40 people of one tree in one call, `summary` or `full`                         | 1 per person                                 |
| `geneanet_get_tree`       | Ancestors (up to 10 generations), descendants (up to 5) and siblings, links resolved | 1                                            |
| `genealogy_export_gedcom` | Write people, or a pedigree, to a GEDCOM 7.0 file in the export folder               | 1 per person not yet read, +1 for a pedigree |
| `genealogy_status`        | Each source's settings and the export folder; with `check: true`, a live probe       | 0, or 1 per check                            |

People read earlier in the session come from an in-memory cache (one hour), so reading people
with `geneanet_get_people` and then exporting them does not read anyone twice.

## The shared shape

Every tool answers in the same compact JSON. Empty values are left out, never sent as `null`.

- **`Ref`** `{source, id, url}` names a person in a source. A Geneanet id is `"<tree>:<index>"`
  (`"maudrenel1:27"`); a family-tree search hit has `"<tree>:<surname>/<given names>/<occurrence>"`
  until it is first read, and both forms are accepted wherever a ref is. `url` opens the record
  for a human.
- **`DateValue`** `{date, qualifier, dateTo, calendar, text}`. `date` is ISO, as precise as known
  (`"1870-11-22"`, `"1870-11"`, `"1870"`). `qualifier` is `about`, `maybe`, `before`, `after`,
  `between`, `or`, `from` or `to`; `dateTo` is the second bound. A full Julian date is converted
  back to its own calendar, with `calendar: "julian"`; French republican and Hebrew dates, and
  Julian dates with only a year or month, are not parsed yet and stay `text`. `text` holds the
  source's wording only when it could not be parsed: nothing is guessed.
- **`Place`** `{name, code, insee, department, region, country, raw}`. Only Geneanet's full
  `town, department, region, country` shape is split into slots; anything else keeps the first
  part as `name` and the whole string in `raw`. A five-character commune code is `code` when the
  source does not say what it is (trees write postal codes and INSEE codes alike); `insee` is set
  only by a source that gives INSEE codes, such as Geneanet's INSEE death index. Do not compare
  one with the other.
- **`Citation`** `{source, url, title, text, acte, page}`: where a fact comes from. `acte` and
  `page` are filled only from a source field with that meaning.
- **`Brief`** `{ref, name, sex, born, bornAt, died, diedAt, withheld}`: a person seen from
  another record (a parent, spouse, child or search match). `born` and `died` are short strings:
  `"1870-11-22"`, `"about 1768"`, `"between 1825 and 1875"`.
- **`Person`** `{ref, name, given, surname, sex, aliases, occupation, events, parents, families,
  notes, withheld, withheldReason, detail}`. `events` are `{type, date, place, citations}` (plus
  `note` and `witnesses` in `full`). `families` are `{spouse, events, children}` in `full`, with
  `childCount` instead of `children` in `summary`.
- **`withheld`** says why a record is empty: `"private"` (the source hides the person),
  `"probably-private"` (an empty record with no death, so inferred, with `withheldReason` saying
  so), or `"premium"` (a Geneanet search hit behind the `XXXX` mask).

## Exporting to GEDCOM

`genealogy_export_gedcom` takes `people` (refs, as the other tools return them) or a `pedigree`
(a Geneanet person with ancestors and descendants, read in one request) and writes a GEDCOM 7.0
file. It returns `{file, people, families, sources, warnings}`, never the file's contents.

- **The export folder.** Files go to `~/Library/Application Support/mcp-genealogy/exports`,
  created on first use, or to `GENEALOGY_EXPORT_DIR` (an absolute path or `~/…`). To let a
  Filiation agent read the exports, point `GENEALOGY_EXPORT_DIR` at the folder granted in
  Filiation › Settings › MCP Server.
- **Names.** A new file is `<yyyy-mm-dd>-<surname>.ged`, with `-2`, `-3`… when taken. Next to it,
  `<file>.refs.json` lists the refs it holds and the `detail` it was written at.
- **One file across calls.** Each call reads at most 40 people and stops scheduling new reads
  after 45 s, so it always answers within about 55 s; whoever was not reached comes back in
  `remaining`. Call again with `remaining` as `people`, the returned `file` and `append: true`:
  the whole file is rewritten from the people it already holds plus the new ones. An append
  keeps the file's `detail` unless you pass another, which re-renders every person in it.
- **What the file holds.** `HEAD` 7.0, one `INDI` per person, `FAM` records built from the parent
  and spouse links between people in the file, one `SOUR` per tree, and on every fact a citation
  with `PAGE` (when the source has one) and the record's URL in a `NOTE`. `EXID` keeps each
  person's source id. A link to someone left out of the file becomes a warning, never a dangling
  pointer.

## Security

- **Read-only toward every source.** No tool writes to Geneanet or anywhere else online.
  Geneanet's tree-editing API exists, but nothing here reaches it.
- **One local write.** `genealogy_export_gedcom` writes its `.ged` and `.refs.json` files inside
  the export folder and nowhere else: a `file` that resolves outside it, or is a symlink, is
  refused before anything is read. It only ever replaces a file it wrote itself, atomically.
- **No credentials.** Every route used answers anonymous requests, so there is nothing to leak.
- **Two runtime dependencies**, the MCP SDK and Zod. Native `fetch`, and a hand-written protobuf
  codec (`src/sources/geneanet/proto/wire.ts`) rather than a protobuf runtime.
- **Paced.** At most one Geneanet request per second across all tools by default
  (`GENEANET_MIN_INTERVAL_MS`, minimum 500). Retries are few and short.

### Terms of use

Geneanet's terms of service forbid automated access. This server is meant for personal,
low-volume research, the kind you would otherwise do by hand in a browser. Do not use it to
crawl. The site-wide search also only works because of a gap in Geneanet's bot protection (see
[How it reaches Geneanet](#how-it-reaches-geneanet)), and that gap can close at any time.

## Configure

| Variable                   | Default                                               | Description                                                                |
| -------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- |
| `GENEALOGY_EXPORT_DIR`     | `~/Library/Application Support/mcp-genealogy/exports` | The only folder `genealogy_export_gedcom` writes to.                       |
| `GENEALOGY_DEBUG`          | unset                                                 | `1` logs every request to stderr. `GENEANET_DEBUG` is still accepted.      |
| `GENEANET_TREE`            | none                                                  | Default tree for the tree tools: the `<tree>` in `gw.geneanet.org/<tree>`. |
| `GENEANET_LANG`            | `en`                                                  | Language of dates and event names in tree answers.                         |
| `GENEANET_MIN_INTERVAL_MS` | `1000`                                                | Minimum gap between two Geneanet requests (500-60000).                     |
| `GENEANET_MAX_RETRIES`     | `2`                                                   | Retries on 429, 5xx and network errors (0-5).                              |
| `GENEANET_TIMEOUT_MS`      | `20000`                                               | Per-request deadline (5000-120000).                                        |
| `GENEANET_TREE_API_URL`    | `https://gw.geneanet.org`                             | Family-tree API host.                                                      |
| `GENEANET_SITE_URL`        | `https://en.geneanet.org`                             | Site-wide search host.                                                     |

An out-of-range or malformed value never stops the server. It is replaced by the default or
clamped, and `genealogy_status` lists what was adjusted.

## Quick start

```bash
pnpm install
pnpm build
```

Then add it to your client, for example `.mcp.json`:

```json
{
  "mcpServers": {
    "genealogy": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-genealogy/dist/cli.js"],
      "env": { "GENEALOGY_EXPORT_DIR": "~/Documents/Genealogy" }
    }
  }
}
```

### Inspect the tools

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| node dist/cli.js 2>/dev/null | jq -r '.result.tools[]?.name'
```

## Worked example

> "Who were Marie Germaine LOUVIGNES's grandparents? She married in Cahuzac-sur-Vère around 1893. Put them in a GEDCOM file."

1. `geneanet_search_records { lastname: "LOUVIGNES", firstname: "Marie Germaine", places: ["Cahuzac-sur-Vère"], radiusKm: 30 }`
   finds her in two family trees, `maudrenel1` and `chantalrochethomas`, and in the Tarn
   marriage index. The tree hits carry a `ref` and `tree`, `n` and `p`.
2. `geneanet_get_tree { tree: "maudrenel1", index: 27, ancestors: 2, descendants: 0 }` returns her
   parents, Jean François Paulin LOUVIGNES and Honorine MAUREL, and four grandparents, each with
   `fatherIndex` and `motherIndex`.
3. `geneanet_get_people { tree: "maudrenel1", indexes: [27, 55, 28, 85, 86] }` reads five of them:
   Guilhaume LOUVIGNES (85), for one, was born 1797-03-20 in Gaillac, married 1835-07-02 in
   Lisle-sur-Tarn and died 1870-01-09 in Cahuzac-sur-Vère.
4. `genealogy_export_gedcom { people: [{source: "geneanet", id: "maudrenel1:27"}, …] }` writes
   `2026-11-21-louvignes.ged` with 5 people and 3 families without another request, and warns
   about the links it left out (her husband, and the parents of Honorine, Guilhaume and Antoinette).

## How it reaches Geneanet

Geneanet publishes no API. This server uses the same two routes as Geneanet's own pages:

- **The family-tree API**: `POST https://gw.geneanet.org/setup/api/?arbre=<op>&sourcename=<tree>`.
  This is GeneWeb's protobuf API, which the tree pages call themselves (`person`, `graph_v2`,
  `person_search_list`). Responses are framed as Latin-1 inside UTF-8. `proto/README.md` covers
  the framing, GeneWeb's raw dates, the privacy flags, and where Geneanet's schema departs from
  upstream GeneWeb.
- **The site-wide search**: `https://en.geneanet.org/fonds/individus/?<form fields>`. It answers
  server-rendered HTML; there is no JSON behind it. Cloudflare challenges every GET from a
  non-browser client, but the same URL sent as a POST with an empty body gets through. That is a
  gap in Geneanet's bot protection, not an interface. When it closes, the tools say so
  (`BlockedError`, naming Cloudflare) instead of failing obscurely.

Geneanet's "same person in other trees" is not exposed: the profile pages fetch no such list
(see `proto/README.md`). The site-wide search's `family_tree` hits are how to find the same
person in other trees.

## Traps worth knowing

- **Indexes are per tree.** The same ancestor has a different `index` in every tree. Keep the
  tree with the index, which a `ref` id does for you.
- **Archive details are Premium-only.** For `society_index`, `collaborative_index` and
  `archival_register` hits, the search result is all a free account can get. Its `url` opens the
  record for a human, and the full date may be masked even there (`withheld: "premium"`).
- **Geneanet cannot tell "no such person" from "no such operation".** Both come back as an empty
  answer, which the tools report as a 404 with a remedy.
- **Vital dates come from the events.** The person record holds display dates only, so the ISO
  form is taken from the matching birth, baptism, death or burial event's raw date. If
  `eventsLimit` cuts that event off, the date is read from the display form instead.
- **Some form filters need Premium.** Occupation and spouse names are greyed out on a free
  account, which is why the search does not offer them.

## Troubleshooting

- **A tool fails with "Cloudflare challenged the request".** The route is closed from outside a
  browser. Run `genealogy_status { check: true }` to see which route is affected. The tree tools
  and the site-wide search are independent.
- **"The search page had N result rows but no result count".** Geneanet redesigned the results
  page, and `src/sources/geneanet/records.ts` needs updating against a fresh capture.
- **"There is no Geneanet tree named …".** The tree name is the first path segment of the tree's
  URL, not the owner's display name.
- **The export is refused.** `file` must be a `.ged` name directly in the export folder
  (`genealogy_status` shows it as `exportDir`), and an existing file is only replaced when this
  tool wrote it.

## Develop

```bash
pnpm dev            # tsdown --watch
pnpm test           # vitest, against real captured responses in test/fixtures
pnpm typecheck
pnpm lint
pnpm format
```

The fixtures are real Geneanet answers, captured live with `scripts/capture.ts`: protobuf bodies
as `.bin`, and search pages trimmed to their result rows as `.html`. Recapture them when Geneanet
changes something, rather than editing them by hand.

### Publish

```bash
pnpm dlx release-it       # bump, commit, tag
git push --follow-tags    # CI publishes to npm + GHCR from the tag
```

## License

MIT

TDQS

A4.4/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct role: status/diagnostics, broad record search, single-tree search, single-person retrieval, and multi-generation tree retrieval. The descriptions explicitly cross-reference search_records vs. search_tree and get_person vs. get_tree, reducing misselection.

Naming Consistency4/5

All tools use a consistent geneanet_ snake_case prefix, and most follow a verb_noun pattern (search_records, get_person, get_tree). auth_status is a minor deviation from the action-verb pattern but remains clear and predictable.

Tool Count5/5

Five tools is well-scoped for a read-only genealogy search and retrieval server. Each tool earns its place by covering a distinct layer: diagnostics, broad search, tree-scoped search, person detail, and tree traversal.

Completeness4/5

The surface covers the core read-only workflows: searching across Geneanet, searching within a tree, fetching a person, traversing ancestors/descendants, and checking service health. Minor gaps exist around explicitly listing or selecting trees, but the default-tree model and available retrieval tools make this workable.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues