familysearch-org-mcp

An MCP server for FamilySearch.org: the shared Family Tree (read, search, add people, facts, relationships, sources, notes, memories), historical record search and record reading, and standardized places. Companion to ancestry-com-mcp; both can be attached at once. Tools are prefixed familysearch_ and ancestry_ so they never collide.

Unofficial. Not affiliated with or endorsed by FamilySearch. It authenticates with your own website session rather than a developer key, which FamilySearch may not sanction; the Family Tree is shared and public, so every write is visible to everyone. Use it with care, at your own risk.

How it works

FamilySearch has a documented platform API (GEDCOM X). Production developer keys are only issued to registered businesses, but the website's own session cookie (fssessionid) is accepted as an OAuth bearer token by api.familysearch.org, and plain Node requests are not bot-blocked there. So this server runs without a browser: all API calls go straight from Node with Authorization: Bearer <cookie>. Historical record search lives on www.familysearch.org/service/… behind Imperva bot protection and goes through a Chrome-impersonating client (impit) instead. Cookies are kept in .session.json (mode 600, git-ignored). The token expires after 24 h or 60 min idle, but the server mints a new one silently by replaying the website's OAuth login redirect with the saved identity cookies, so a real Chrome is needed only for the initial sign-in (pnpm login or the familysearch_session tool's login action: opens a dedicated Chrome profile, waits for you to log in, saves the cookies, closes the window) and again if the identity session itself expires.

Requirements: Node 26+, pnpm, Google Chrome.

Related MCP server: Gramps MCP

Setup

git clone https://github.com/ball2jh/familysearch-org-mcp
cd familysearch-org-mcp
pnpm install
pnpm login            # one-time: opens Chrome to sign in, saves .session.json, closes Chrome
pnpm mcp-test         # read-only check

Claude Code / Claude Desktop config (stdio):

{ "mcpServers": { "familysearch": { "command": "node", "args": ["/absolute/path/to/familysearch-org-mcp/src/server.ts"] } } }

Tools

Tools are grouped by resource and split into a read tool and an edit tool, so an MCP client can auto-approve reads and ask before writes based on the tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint, all set honestly on every tool). Every tool takes an action parameter; every parameter is described in the schema, and a missing parameter for an action comes back as an error naming it. The whole definition set is about 10K tokens.

Files: familysearch_download writes record images and memory files to a local outPath; without outPath, images come back inline (record images scaled to maxWidth, default 1600 px, and always fitted to what the model can see: at most 2000 px on the long edge and 4784 visual tokens) so the assistant can look at them. To read small handwriting, region cuts part of the page from the full-resolution scan (with the sharp image library), so a quarter page reaches the model near full resolution. familysearch_memory_edit upload reads from a local filePath.

The Family Tree is a single shared public tree. Every write is visible to everyone and attributed to the user, so the edit tools take a changeMessage/reason and the server instructions tell the model to search before creating, be conservative, cite sources, and confirm deletions.

Results: JSON, trimmed to what a caller acts on. A result over 36K characters (about 9K tokens, under the 10K-token warning and 25K-token cap Claude Code applies to tool results; override with MCP_MAX_RESULT_CHARS) is cut at an item boundary so it stays valid JSON, and carries a _truncated field with the count shown, the total, and how to get the rest. Errors, including validation errors and upstream HTTP failures, come back as tool results with isError: true and a message that says what to do next. A 429 from FamilySearch is retried once after its Retry-After; if it persists the error says how long to wait.

Tests

• pnpm test — unit tests, no network: result helpers, error and Warning parsing, fact-type normalization, restricted-image access rules (test/restricted.test.ts), the search, relationship, ancestry, descendancy, collection, catalog (holdings, film paging and filter), full-text (the boolean query compiler, paging through split searches, facets) and waypoint projections on recorded response shapes (test/fixtures/), and test/writes.test.ts, which runs the real client against a fake person in test/fake-transport.ts that applies each write the way FamilySearch does, to check the body every edit sends and the result it reads back (a date-only fact edit keeps its place, a second Birth is refused, a new name is not preferred, a warning is an error). test/conventions.test.ts and test/tools.test.ts are static checks: no write swallows a failed read, every write's result comes from a returned id or a read-back and never an optional id or a bare ok: true, every person POST goes through the Warning check, failed requests keep their HTTP status, every tool action has a handler and every parameter a description.

• pnpm mcp-test — read-only end-to-end run over stdio against your account: checks that every tool has a title, full annotations and described parameters, calls every read action, downloads one image inline and one to disk, and checks that error paths come back as isError results. Prints definition size and per-call latency.

• pnpm mcp-write-test — creates three living (therefore private) "Mcptest" people and touches nothing else: adds and removes a note, facts, names, a source and a memory on one of them, checks each refusal (a second Birth, a new preferred name, an unknown place id or source description, a delete without a reason), links them as a couple and a child, and reads every write back to check what was stored and that the unmentioned fields survived. Cleanup runs in a finally, so a failing step does not leave test people behind.

Repository layout

• src/transport.ts — bearer-token HTTP, silent token renewal, Imperva client, pacing, rate-limit handling, error unwrapping

• src/session.ts — cookie jar persisted in .session.json

• src/browser.ts — Chrome bootstrap used only by login

• src/client.ts — typed client over the GEDCOM X platform API, with response compaction

• src/result.ts — tool-result helpers: JSON-safe truncation, inline images, errors, action dispatch

• src/tools.ts — MCP tool definitions

• src/server.ts — stdio entry point and server instructions

• scripts/ — login.ts, the Chrome launcher, the traffic recorder, and the two end-to-end tests

• test/ — unit tests

• docs/endpoints.md — verified endpoint table, including which documented paths do not work

Caveats

• The session token expires (24 h / 60 min idle); the server renews it silently from the saved identity cookies. When that renewal fails too, tools report not logged in and familysearch_session login gets you back in.

• FamilySearch throttles (HTTP 429); requests are spaced 120 ms apart and a 429 is retried once after Retry-After.

• Unindexed material: fulltext searches the OCR'd text of wills, deeds, probate, court and land books and newspapers, which the indexed search never sees; every hit carries the entire page text upstream, so the tool returns a snippet around the match unless includeText is asked for. FamilySearch's own query language is not boolean (+word required, -word excluded, every other word optional; AND/OR are ignored words and parentheses group nothing), so the tool compiles its boolean text into that: words are required, and an OR inside an AND runs as up to 8 searches that do not overlap, whose totals add up (see "Full-text query syntax" in docs/endpoints.md). Its place, collection, year and record-type filters are the site's facets: the upstream q.place parameter is silently ignored, so place is matched against the index's place tree (region > country or state > county > town) and a part it cannot match is refused with the choices rather than searched wider. browse walks a collection's waypoints (county → volume → images) and film lists a digital film's images in order (the storage service ignores paging offsets, so the tool pages client-side). Both hand back image arks or storage ids that familysearch_download record_image accepts.

• Restricted images (viewable only at a FamilySearch center or affiliate library, only by Church members, or not at all) cannot be downloaded: record_image fails naming the rule, get on the image ark returns restricted with its collection, waypoint and citation, and film says restricted (or mixed: …) up front. The index of such an image is often still readable with search and get. See "Restricted images" in docs/endpoints.md.

• Replace-style writes refill what the caller left out. A conclusion sent with an id replaces the stored one wholesale, so familysearch_person_edit update reads the person first and keeps the unmentioned date, place, value, name type, preferred flag and name parts; scripts/mcp-write-test.ts edits a fact with only a date and checks the place survived. Any new write that replaces a record must follow the same rule.

• Some writes that look like additions are replacements upstream and are refused instead: a second Birth, Christening, Death, Burial or other single-instance fact without an id (FamilySearch overwrites the stored one), and a new name sent as preferred (it replaces the preferred name). New names are added as alternates.

• FamilySearch answers HTTP 200 to writes it only partly applied or ignored (an unknown place id, an unknown source description, a repeated source attachment). A person POST with a Warning header is reported as an error, place ids and source descriptions are checked before writing, and every write's result is read back from the person.

• Tool schemas are strict: a parameter the tool does not have is rejected by name rather than dropped. Per-page counts are clamped to what fits the result budget (record search 40, full text 20, film and browse 250, collections 80, catalog 50, catalog_item films 200); recorded sessions asked for 50 to 1000 and got truncated results they then worked from.

• Tree search accepts a year range ("1745-1780") and sends it as from/to; the platform rejects the single value.

• The research project that uses these servers should run them from a separate stable clone (see CLAUDE.md), not from a checkout that is being edited.

• Not covered: LDS ordinance data, user (private) trees, discussions, and the Source Box folder management.

• .session.json, .profile/ and captures/ hold live session cookies and are gitignored. Never commit them.

• The server logs only to stderr, so it is safe on stdio.