# 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](https://github.com/ball2jh/ancestry-com-mcp); both can be attached at once.

> **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](https://github.com/apify/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 `fs_session login` tool 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.

## Setup

```bash
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):

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

## Tools

| Tool | Actions |
|---|---|
| `fs_session` | status, login |
| `person` | get, search, ancestry, descendancy, changes, matches, create, update, delete_conclusion, delete |
| `relationship` | create_couple, create_child_parents, get_couple, get_child_parents, delete_couple, delete_child_parents |
| `source` | list_person, source_box, create, get, delete_description, attach, detach |
| `note` | list, add, delete |
| `memory` | list_person, list_mine, get, download, upload, attach, delete |
| `record` | search, get, download_image, collections |
| `place` | search, get |
| `raw_request` | any platform request (or a `/service/` website request with `viaSite`) |

Files: `record.download_image` (the scanned record image, full size or scaled) and `memory.download` write to a
local `outPath` or return base64; `memory.upload` reads 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 tools require a `changeMessage`/`reason` and the server instructions tell the model to be
conservative and cite sources. Tests: `pnpm mcp-test` (read-only) and `pnpm mcp-write-test` (adds and removes a
note, a fact, a source, a memory, and one unconnected test person on the user's own account).

## 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 `fs_session login` gets you back in.
- FamilySearch throttles (HTTP 429); requests are spaced 120 ms apart.
- 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.