Skip to content
Back to search

mcp-genealogy

Model Context Protocol server for Geneanet genealogy: search all records, read family trees

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mgcrea--mcp-genealogy/badge.svg)](/listings/mgcrea--mcp-genealogy)

HTML

<a href="/listings/mgcrea--mcp-genealogy"><img src="/api/listings/mgcrea--mcp-genealogy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pnpm install
pnpm build

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

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

Inspect the tools

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'

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 243 lines
  1. # @mgcrea/mcp-genealogy
  2. A [Model Context Protocol](https://modelcontextprotocol.io) server for genealogy records. It
  3. reads people out of several genealogy sources, answers in one shared shape whatever the source,
  4. and writes what you collect to a GEDCOM 7.0 file.
  5. | Source | Status | What it gives |
  6. | ----------------------------------- | ---------- | ------------------------------------------------------------------------------ |
  7. | [Geneanet](https://en.geneanet.org) | available | Site-wide search of every public tree and archive index; persons and pedigrees |
  8. | [matchID](https://deces.matchid.io) | next phase | France's INSEE death index, with exact dates and certificate numbers |
  9. | [Geni](https://www.geni.com) | later | The world tree, with OAuth |
  10. It is **read-only toward every source and needs no account.** The only thing it writes is the
  11. GEDCOM file, in one folder of your choosing.
  12. ## Tools
  13. | Tool | What it does | Requests |
  14. | ------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------- |
  15. | `geneanet_search_records` | Search all Geneanet trees and archive indexes at once for one individual | 1 per page |
  16. | `geneanet_search_tree` | Search one tree by surname and/or first name, with each match's parents and spouses | 1 |
  17. | `geneanet_get_person` | One person's full record: events with places, sources, notes and witnesses | 1 (2 with n/p) |
  18. | `geneanet_get_people` | Up to 40 people of one tree in one call, `summary` or `full` | 1 per person |
  19. | `geneanet_get_tree` | Ancestors (up to 10 generations), descendants (up to 5) and siblings, links resolved | 1 |
  20. | `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 |
  21. | `genealogy_status` | Each source's settings and the export folder; with `check: true`, a live probe | 0, or 1 per check |
  22. People read earlier in the session come from an in-memory cache (one hour), so reading people
  23. with `geneanet_get_people` and then exporting them does not read anyone twice.
  24. ## The shared shape
  25. Every tool answers in the same compact JSON. Empty values are left out, never sent as `null`.
  26. - **`Ref`** `{source, id, url}` names a person in a source. A Geneanet id is `"<tree>:<index>"`
  27. (`"maudrenel1:27"`); a family-tree search hit has `"<tree>:<surname>/<given names>/<occurrence>"`
  28. until it is first read, and both forms are accepted wherever a ref is. `url` opens the record
  29. for a human.
  30. - **`DateValue`** `{date, qualifier, dateTo, calendar, text}`. `date` is ISO, as precise as known
  31. (`"1870-11-22"`, `"1870-11"`, `"1870"`). `qualifier` is `about`, `maybe`, `before`, `after`,
  32. `between`, `or`, `from` or `to`; `dateTo` is the second bound. A full Julian date is converted
  33. back to its own calendar, with `calendar: "julian"`; French republican and Hebrew dates, and
  34. Julian dates with only a year or month, are not parsed yet and stay `text`. `text` holds the
  35. source's wording only when it could not be parsed: nothing is guessed.
  36. - **`Place`** `{name, code, insee, department, region, country, raw}`. Only Geneanet's full
  37. `town, department, region, country` shape is split into slots; anything else keeps the first
  38. part as `name` and the whole string in `raw`. A five-character commune code is `code` when the
  39. source does not say what it is (trees write postal codes and INSEE codes alike); `insee` is set
  40. only by a source that gives INSEE codes, such as Geneanet's INSEE death index. Do not compare
  41. one with the other.
  42. - **`Citation`** `{source, url, title, text, acte, page}`: where a fact comes from. `acte` and
  43. `page` are filled only from a source field with that meaning.
  44. - **`Brief`** `{ref, name, sex, born, bornAt, died, diedAt, withheld}`: a person seen from
  45. another record (a parent, spouse, child or search match). `born` and `died` are short strings:
  46. `"1870-11-22"`, `"about 1768"`, `"between 1825 and 1875"`.
  47. - **`Person`** `{ref, name, given, surname, sex, aliases, occupation, events, parents, families,
  48. notes, withheld, withheldReason, detail}`. `events` are `{type, date, place, citations}` (plus
  49. `note` and `witnesses` in `full`). `families` are `{spouse, events, children}` in `full`, with
  50. `childCount` instead of `children` in `summary`.
  51. - **`withheld`** says why a record is empty: `"private"` (the source hides the person),
  52. `"probably-private"` (an empty record with no death, so inferred, with `withheldReason` saying
  53. so), or `"premium"` (a Geneanet search hit behind the `XXXX` mask).
  54. ## Exporting to GEDCOM
  55. `genealogy_export_gedcom` takes `people` (refs, as the other tools return them) or a `pedigree`
  56. (a Geneanet person with ancestors and descendants, read in one request) and writes a GEDCOM 7.0
  57. file. It returns `{file, people, families, sources, warnings}`, never the file's contents.
  58. - **The export folder.** Files go to `~/Library/Application Support/mcp-genealogy/exports`,
  59. created on first use, or to `GENEALOGY_EXPORT_DIR` (an absolute path or `~/…`). To let a
  60. Filiation agent read the exports, point `GENEALOGY_EXPORT_DIR` at the folder granted in
  61. Filiation › Settings › MCP Server.
  62. - **Names.** A new file is `<yyyy-mm-dd>-<surname>.ged`, with `-2`, `-3`… when taken. Next to it,
  63. `<file>.refs.json` lists the refs it holds and the `detail` it was written at.
  64. - **One file across calls.** Each call reads at most 40 people and stops scheduling new reads
  65. after 45 s, so it always answers within about 55 s; whoever was not reached comes back in
  66. `remaining`. Call again with `remaining` as `people`, the returned `file` and `append: true`:
  67. the whole file is rewritten from the people it already holds plus the new ones. An append
  68. keeps the file's `detail` unless you pass another, which re-renders every person in it.
  69. - **What the file holds.** `HEAD` 7.0, one `INDI` per person, `FAM` records built from the parent
  70. and spouse links between people in the file, one `SOUR` per tree, and on every fact a citation
  71. with `PAGE` (when the source has one) and the record's URL in a `NOTE`. `EXID` keeps each
  72. person's source id. A link to someone left out of the file becomes a warning, never a dangling
  73. pointer.
  74. ## Security
  75. - **Read-only toward every source.** No tool writes to Geneanet or anywhere else online.
  76. Geneanet's tree-editing API exists, but nothing here reaches it.
  77. - **One local write.** `genealogy_export_gedcom` writes its `.ged` and `.refs.json` files inside
  78. the export folder and nowhere else: a `file` that resolves outside it, or is a symlink, is
  79. refused before anything is read. It only ever replaces a file it wrote itself, atomically.
  80. - **No credentials.** Every route used answers anonymous requests, so there is nothing to leak.
  81. - **Two runtime dependencies**, the MCP SDK and Zod. Native `fetch`, and a hand-written protobuf
  82. codec (`src/sources/geneanet/proto/wire.ts`) rather than a protobuf runtime.
  83. - **Paced.** At most one Geneanet request per second across all tools by default
  84. (`GENEANET_MIN_INTERVAL_MS`, minimum 500). Retries are few and short.
  85. ### Terms of use
  86. Geneanet's terms of service forbid automated access. This server is meant for personal,
  87. low-volume research, the kind you would otherwise do by hand in a browser. Do not use it to
  88. crawl. The site-wide search also only works because of a gap in Geneanet's bot protection (see
  89. [How it reaches Geneanet](#how-it-reaches-geneanet)), and that gap can close at any time.
  90. ## Configure
  91. | Variable | Default | Description |
  92. | -------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- |
  93. | `GENEALOGY_EXPORT_DIR` | `~/Library/Application Support/mcp-genealogy/exports` | The only folder `genealogy_export_gedcom` writes to. |
  94. | `GENEALOGY_DEBUG` | unset | `1` logs every request to stderr. `GENEANET_DEBUG` is still accepted. |
  95. | `GENEANET_TREE` | none | Default tree for the tree tools: the `<tree>` in `gw.geneanet.org/<tree>`. |
  96. | `GENEANET_LANG` | `en` | Language of dates and event names in tree answers. |
  97. | `GENEANET_MIN_INTERVAL_MS` | `1000` | Minimum gap between two Geneanet requests (500-60000). |
  98. | `GENEANET_MAX_RETRIES` | `2` | Retries on 429, 5xx and network errors (0-5). |
  99. | `GENEANET_TIMEOUT_MS` | `20000` | Per-request deadline (5000-120000). |
  100. | `GENEANET_TREE_API_URL` | `https://gw.geneanet.org` | Family-tree API host. |
  101. | `GENEANET_SITE_URL` | `https://en.geneanet.org` | Site-wide search host. |
  102. An out-of-range or malformed value never stops the server. It is replaced by the default or
  103. clamped, and `genealogy_status` lists what was adjusted.
  104. ## Quick start
  105. ```bash
  106. pnpm install
  107. pnpm build
  108. ```
  109. Then add it to your client, for example `.mcp.json`:
  110. ```json
  111. {
  112. "mcpServers": {
  113. "genealogy": {
  114. "command": "node",
  115. "args": ["/absolute/path/to/mcp-genealogy/dist/cli.js"],
  116. "env": { "GENEALOGY_EXPORT_DIR": "~/Documents/Genealogy" }
  117. }
  118. }
  119. }
  120. ```
  121. ### Inspect the tools
  122. ```bash
  123. printf '%s\n' \
  124. '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
  125. '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  126. '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  127. | node dist/cli.js 2>/dev/null | jq -r '.result.tools[]?.name'
  128. ```
  129. ## Worked example
  130. > "Who were Marie Germaine LOUVIGNES's grandparents? She married in Cahuzac-sur-Vère around 1893. Put them in a GEDCOM file."
  131. 1. `geneanet_search_records { lastname: "LOUVIGNES", firstname: "Marie Germaine", places: ["Cahuzac-sur-Vère"], radiusKm: 30 }`
  132. finds her in two family trees, `maudrenel1` and `chantalrochethomas`, and in the Tarn
  133. marriage index. The tree hits carry a `ref` and `tree`, `n` and `p`.
  134. 2. `geneanet_get_tree { tree: "maudrenel1", index: 27, ancestors: 2, descendants: 0 }` returns her
  135. parents, Jean François Paulin LOUVIGNES and Honorine MAUREL, and four grandparents, each with
  136. `fatherIndex` and `motherIndex`.
  137. 3. `geneanet_get_people { tree: "maudrenel1", indexes: [27, 55, 28, 85, 86] }` reads five of them:
  138. Guilhaume LOUVIGNES (85), for one, was born 1797-03-20 in Gaillac, married 1835-07-02 in
  139. Lisle-sur-Tarn and died 1870-01-09 in Cahuzac-sur-Vère.
  140. 4. `genealogy_export_gedcom { people: [{source: "geneanet", id: "maudrenel1:27"}, …] }` writes
  141. `2026-11-21-louvignes.ged` with 5 people and 3 families without another request, and warns
  142. with a count of the links it left out by relation (her husband, and the parents of Honorine,
  143. Guilhaume and Antoinette).
  144. ## How it reaches Geneanet
  145. Geneanet publishes no API. This server uses the same two routes as Geneanet's own pages:
  146. - **The family-tree API**: `POST https://gw.geneanet.org/setup/api/?arbre=<op>&sourcename=<tree>`.
  147. This is GeneWeb's protobuf API, which the tree pages call themselves (`person`, `graph_v2`,
  148. `person_search_list`). Responses are framed as Latin-1 inside UTF-8. `proto/README.md` covers
  149. the framing, GeneWeb's raw dates, the privacy flags, and where Geneanet's schema departs from
  150. upstream GeneWeb.
  151. - **The site-wide search**: `https://en.geneanet.org/fonds/individus/?<form fields>`. It answers
  152. server-rendered HTML; there is no JSON behind it. Cloudflare challenges every GET from a
  153. non-browser client, but the same URL sent as a POST with an empty body gets through. That is a
  154. gap in Geneanet's bot protection, not an interface. When it closes, the tools say so
  155. (`BlockedError`, naming Cloudflare) instead of failing obscurely.
  156. Geneanet's "same person in other trees" is not exposed: the profile pages fetch no such list
  157. (see `proto/README.md`). The site-wide search's `family_tree` hits are how to find the same
  158. person in other trees.
  159. ## Traps worth knowing
  160. - **Indexes are per tree.** The same ancestor has a different `index` in every tree. Keep the
  161. tree with the index, which a `ref` id does for you.
  162. - **Archive details are Premium-only.** For `society_index`, `collaborative_index` and
  163. `archival_register` hits, the search result is all a free account can get. Its `url` opens the
  164. record for a human, and the full date may be masked even there (`withheld: "premium"`).
  165. - **Geneanet cannot tell "no such person" from "no such operation".** Both come back as an empty
  166. answer, which the tools report as a 404 with a remedy.
  167. - **Vital dates come from the events.** The person record holds display dates only, so the ISO
  168. form is taken from the matching birth, baptism, death or burial event's raw date. If
  169. `eventsLimit` cuts that event off, the date is read from the display form instead.
  170. - **Some form filters need Premium.** Occupation and spouse names are greyed out on a free
  171. account, which is why the search does not offer them.
  172. ## Troubleshooting
  173. - **A tool fails with "Cloudflare challenged the request".** The route is closed from outside a
  174. browser. Run `genealogy_status { check: true }` to see which route is affected. The tree tools
  175. and the site-wide search are independent.
  176. - **"The search page had N result rows but no result count".** Geneanet redesigned the results
  177. page, and `src/sources/geneanet/records.ts` needs updating against a fresh capture.
  178. - **"There is no Geneanet tree named …".** The tree name is the first path segment of the tree's
  179. URL, not the owner's display name.
  180. - **The export is refused.** `file` must be a `.ged` name directly in the export folder
  181. (`genealogy_status` shows it as `exportDir`), and an existing file is only replaced when this
  182. tool wrote it.
  183. ## Develop
  184. ```bash
  185. pnpm dev # tsdown --watch
  186. pnpm test # vitest, against real captured responses in test/fixtures
  187. pnpm typecheck
  188. pnpm lint
  189. pnpm format
  190. ```
  191. The fixtures are real Geneanet answers, captured live with `scripts/capture.ts`: protobuf bodies
  192. as `.bin`, and search pages trimmed to their result rows as `.html`. Recapture them when Geneanet
  193. changes something, rather than editing them by hand.
  194. ### Publish
  195. ```bash
  196. pnpm dlx release-it # bump, commit, tag
  197. git push --follow-tags # CI publishes to npm + GHCR from the tag
  198. ```
  199. ## License
  200. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.