FamilySearch MCP Server

A local Model Context Protocol (MCP) server for FamilySearch. Gives AI assistants access to search the Family Tree, view person details, explore ancestors and descendants, and search historical records.

About this fork

This fork combines the work spread across the forks of JonathanReiss15/familysearch-mcp and adds a security pass on top:

See AUDIT.md for the full review.

Related MCP server: GEDCOM MCP Server

Features

• Family Tree search — find individuals by name, dates, places, and gender

• Person details — view a person card by ID, with parents, spouses (and marriage) and children

• Family view — parents, siblings, spouses and children in one call

• Research suggestions — record hints and FamilySearch research flags across your pedigree

• Pedigree exploration — ancestors (up to 8 generations) and descendants (up to 3)

• Historical records — search indexed records by the person, their father, mother or spouse, marriage or residence place, and open any record to see everyone on it

• AI full-text search — search OCR transcripts with OR, AND, or exact-phrase matching

• Catalog and film browsing — find catalog items and resolve pages in a DGS image group

• High-resolution downloads — download by ARK image ID or by DGS + image number

• Browser session auth — log in once with Brave, Chrome, or Chromium; no FamilySearch API key required

How it works

FamilySearch does not approve direct API access for most personal projects. This server reuses your browser session cookies and calls the same internal /service/ endpoints the website uses. Your session is stored locally at ~/.familysearch-mcp/config.json.

Prerequisites

• Node.js 18+ and npm

• Brave, Chrome, or Chromium (Brave is preferred where available)

• A free FamilySearch account

Installation

1. Clone and build

git clone https://github.com/G4rutti/familysearch-mcp.git
cd familysearch-mcp
npm install
npm run build

2. Log in to FamilySearch

npm run login

This opens an installed browser with a dedicated profile. Sign in when prompted. Your session is saved to ~/.familysearch-mcp/config.json.

Tip: You can also ask your AI assistant to run the login-with-browser tool after the MCP is connected.

3. Configure your MCP client

Add the server to your client using stdio transport. Replace /path/to/familysearch-mcp with the absolute path to this repo.

Recommended config (uses cwd so you don't need absolute paths in args):

{
  "mcpServers": {
    "familysearch": {
      "command": "node",
      "args": ["build/index.js"],
      "cwd": "/path/to/familysearch-mcp"
    }
  }
}

Run npm run build whenever you pull changes.

MCP client setup

Cursor

Project-scoped — create .cursor/mcp.json in your project (or add globally in Cursor Settings → MCP):

{
  "mcpServers": {
    "familysearch": {
      "command": "node",
      "args": ["build/index.js"],
      "cwd": "/path/to/familysearch-mcp"
    }
  }
}

Restart Cursor or reload MCP servers after saving.

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "familysearch": {
      "command": "node",
      "args": ["build/index.js"],
      "cwd": "/path/to/familysearch-mcp"
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

From the repo directory:

claude mcp add familysearch -- node build/index.js

Or with an absolute path from anywhere:

claude mcp add familysearch -- node /path/to/familysearch-mcp/build/index.js

Verify with claude mcp list.

Codex

From the repo directory (after npm run build):

codex mcp add familysearch -- node build/index.js

Or add to ~/.codex/config.toml:

[mcp_servers.familysearch]
command = "node"
args = ["build/index.js"]
cwd = "/path/to/familysearch-mcp"

Use /mcp in Codex to confirm the server is connected.

VS Code

Add to your user MCP config (Command Palette → MCP: Open User Configuration) or .vscode/mcp.json in a workspace:

{
  "servers": {
    "familysearch": {
      "command": "node",
      "args": ["build/index.js"],
      "cwd": "/path/to/familysearch-mcp"
    }
  }
}

Windows

If node is not found, use the full path to your Node executable. For clients that struggle with direct node invocation, wrap with cmd:

{
  "mcpServers": {
    "familysearch": {
      "command": "cmd",
      "args": ["/c", "node", "build/index.js"],
      "cwd": "C:\\path\\to\\familysearch-mcp"
    }
  }
}

Authentication

Option 1: Browser login (recommended)

npm run login

Opens Brave when available, otherwise Chrome or Chromium. Set FAMILYSEARCH_BROWSER_PATH to select a different browser executable.

Option 2: Copy cookies manually

Prefer option 1. Cookies passed to set-session-cookie become part of the AI conversation (and so reach the model provider). npm run login writes them straight to the local config file.

1. Log in at familysearch.org

2. In DevTools → Console, run: copy(document.cookie)

3. Use the set-session-cookie MCP tool with the copied string

The full cookie string is required — bot protection cookies like reese84 and incap_ses_* must be included, not just fssessionid.

Tools

Example prompts

Search for persons named "John Smith" born in "New York"

Get person with personId G2KQ-JTH

Get 4 generations of ancestors for personId G2KQ-JTH

Search historical records for surname "Reiss" in "Pennsylvania"

Search marriage records in Aiuruoca, Minas Gerais between 1905 and 1910 for a groom
surnamed Diniz whose bride is named Ana Maria

Show research suggestions for my ancestors, 6 generations up from GJZ7-7SH

Search the full text for "voogd" and "Leeuwarden" between 1700 and 1800

Set matchMode to all to require every word (+word) or to exact to search for an exact quoted phrase. The default, any, retains FamilySearch's OR behavior.

Full-text results include an OCR excerpt and a direct FamilySearch ARK link to the scan. Set includeFullTranscript to true to return the complete AI transcript; use a low result limit because transcripts can be large.

Download image 3:1:3QHK-93G5-35Q3 as a high-resolution JPG

Find catalog material for Leeuwarden with "trouwregister" in the title

List 20 images from DGS 008903222, starting at image 500

Download image 517 from DGS 008903222 as a high-resolution JPG

Downloads are saved to ~/Downloads/familysearch-mcp by default (set FAMILYSEARCH_DOWNLOAD_DIR to change it). outputDirectory can only name a sub-folder inside that root. The official FamilySearch viewer opens briefly while preparing the file. JPG downloads use the original scan resolution; PDF downloads are available with or without highlights.

Troubleshooting

Rate limiting

FamilySearch's security service blocks clients that issue requests too quickly (error 15). This server is deliberately conservative to avoid getting your IP address blocked. It:

• spaces every API request out by at least ~4 seconds, plus random jitter so the cadence is not perfectly regular

• retries transient failures (HTTP 429/5xx and network errors) with slow, jittered exponential backoff (starting at ~3s, capped at 60s)

• honors the Retry-After header when FamilySearch sends one

• enters a 15-minute cooldown after a security block (error 15) or a rate-limit response, during which all requests fail fast instead of hammering the API

Error 15 is a hard bot-protection block and is not retried automatically. If you see it, wait for the cooldown to finish, refresh your session with npm run login, and then retry.

All values are configurable through environment variables in your MCP client config (values are milliseconds unless noted):

To be extra gentle, raise the interval and cooldown, for example:

{
  "mcpServers": {
    "familysearch": {
      "command": "node",
      "args": ["build/index.js"],
      "cwd": "/path/to/familysearch-mcp",
      "env": {
        "FAMILYSEARCH_MIN_INTERVAL_MS": "8000",
        "FAMILYSEARCH_COOLDOWN_MS": "1800000"
      }
    }
  }
}

Security

• Session cookies are stored locally in ~/.familysearch-mcp/config.json (chmod 600 on macOS/Linux; on Windows it relies on your user profile's permissions)

• They grant the same access as your browser session — never share this file

• Sessions expire after inactivity; re-authenticate when tools return auth errors

• The server runs locally over stdio and only ever talks to https://*.familysearch.org: any other URL, including one returned by the API or reached through a redirect, is refused before the cookies are attached

• Person and record IDs are validated before they are put into request paths

• Downloads can only be written inside the download root

• All tools are read-only on FamilySearch; nothing edits your tree

• This is an unofficial client of FamilySearch's internal website endpoints, not its public API. Use it at a human pace (the defaults do this) and be aware it is outside FamilySearch's supported integrations

See AUDIT.md for details.

Environment variables

License

MIT