familysearch-mcp

CLI + servidor MCP para a árvore da sua conta no FamilySearch: ler pessoas, famílias, ancestrais, descendentes e o histórico de alterações; pesquisar registros históricos, lugares e as sugestões que o próprio FamilySearch faz; comparar duas pessoas lado a lado e mesclar duplicatas; corrigir fatos, ligar pais e cônjuges, anexar fontes e escrever notas. A sua linhagem vai para um cache local, de onde saem a lista do que falta pesquisar e a exportação em GEDCOM, sem bater no FamilySearch a cada pergunta.

Por dentro, ele fala a API documentada do FamilySearch (https://www.familysearch.org/platform/...), autenticado pelo token da sua sessão no navegador (o cookie fssessionid, enviado como Bearer), sem chave de desenvolvedor. A árvore do FamilySearch é uma só, compartilhada pelo mundo todo, então este projeto escreve nela de verdade. Por isso toda escrita passa por uma pergunta na tela que só você responde: sem a sua aprovação, nada é enviado.

Sumário

• Instalação

• Login

• Uso — CLI

• Uso — MCP

• Variáveis de ambiente

• Tools

• Como funciona

• Troubleshooting

• Documentação

• Licença

Related MCP server: familysearch-org-mcp

Instalação

Requer Bun ≥ 1.3 (o cache usa bun:sqlite) e macOS para as escritas pelo CLI e para importar a sessão do navegador. O login pela janela usa o Google Chrome.

Tudo de uma vez (Claude Code)

git clone https://github.com/maxwellmezadre/familysearch-mcp.git
cd familysearch-mcp
bun install
bun run setup

setup compila o binário para ~/.local/bin/familysearch, registra o servidor MCP familysearch no escopo de usuário do seu ~/.claude.json e instala a Skill em ~/.claude/skills/familysearch-mcp/. Se o Dia estiver instalado, o registro já leva FAMILYSEARCH_IMPORT_BROWSER=dia; outro navegador vai por bun run setup --import-browser=chrome. --dry-run mostra o que seria feito sem alterar nada.

npm

npm i -g @maxwellmezadre/familysearch-mcp   # instala `familysearch` e `familysearch-mcp` no PATH
familysearch --version

O pacote roda com o Bun (bun:sqlite), então o Bun precisa estar instalado. Ele fica disponível no npm a partir da primeira versão publicada.

Binário único

bun run build:binary   # gera ./familysearch, sem precisar de runtime instalado
./familysearch --version

O binário roda tudo, inclusive o login: o playwright-core vai embutido e o Chrome vem do sistema.

Login

A senha nunca passa por aqui. Na produção, o caminho normal é importar a sessão do navegador em que você já usa o FamilySearch:

familysearch login --from-browser dia   # dia, arc, chrome, chromium, brave ou edge (macOS)
familysearch login                      # usa FAMILYSEARCH_IMPORT_BROWSER, ou abre o Chrome

A importação lê o cookie fssessionid do banco de cookies do navegador, com a chave que ele guarda no Keychain (o macOS pede permissão uma vez), e confere o token com GET /platform/users/current antes de gravar. Sem navegador configurado, familysearch login abre uma janela do Chrome num perfil dedicado e espera você entrar.

O ambiente beta (FAMILYSEARCH_ENV=beta) entra sempre pela janela do Chrome dedicado. Produção e beta usam o mesmo cookie no domínio .familysearch.org, então entrar no beta pelo navegador do dia a dia desconectaria a produção.

A sessão fica cifrada com AES-256-GCM em ~/.config/familysearch-mcp/session.production.enc (ou session.beta.enc), modo 0600. Detalhes, o que é gravado e como revogar: docs/LOGIN.md.

Uso — CLI

familysearch status --verify              # a sessão ainda vale?
familysearch doctor                       # o que quebrou, camada a camada

familysearch search --given Giulia --surname Rossi --birth 1890
familysearch person KWCB-AAA --sources    # fatos, datas e fontes
familysearch family KWCB-AAA              # pais, cônjuges e filhos
familysearch ancestors KWCB-AAA --generations 4
familysearch duplicates KWCB-AAA          # o que o FamilySearch acha que é duplicata
familysearch records --surname Rossi --birth-place "Treviso, Itália"

familysearch compare KWCB-AAA KWCB-BBB    # lado a lado, só lê
familysearch sync                         # baixa a sua linhagem para o cache
familysearch gaps                         # o que falta pesquisar
familysearch export --format gedcom

familysearch link-parents KWCB-CCC --father KWCB-AAA --reason "Certidão de nascimento de 1921" --preview
familysearch merge KWCB-AAA KWCB-BBB --fingerprint "<do compare>" --reason "Mesma pessoa, mesmos pais" --preview

Todo comando de tool aceita --json e imprime exatamente o que o cliente MCP receberia. Os comandos que escrevem aceitam --preview, que mostra o plano sem perguntar nem escrever. Referência completa em docs/CLI.md.

Uso — MCP

O setup já registra o servidor. Manualmente:

claude mcp add -s user familysearch --env FAMILYSEARCH_IMPORT_BROWSER=dia -- /Users/você/.local/bin/familysearch mcp

Ou, à mão, em ~/.claude.json:

{
  "mcpServers": {
    "familysearch": {
      "type": "stdio",
      "command": "/Users/você/.local/bin/familysearch",
      "args": ["mcp"],
      "env": { "FAMILYSEARCH_IMPORT_BROWSER": "dia" }
    }
  }
}

Use o caminho absoluto: clientes MCP não herdam o PATH do seu shell. As escritas precisam de um cliente com suporte a elicitation (a pergunta na tela); o Claude Code tem. Num cliente sem esse suporte, as leituras funcionam e toda escrita é recusada, como erro de tool. Depois é só perguntar: "quem são os meus bisavós?", "essas duas pessoas são a mesma?", "o que falta pesquisar na minha árvore?".

Variáveis de ambiente

Todas opcionais. A tabela completa está em docs/CONFIGURATION.md.

Só FAMILYSEARCH_AUTO_APPROVE=1 desliga a pergunta de aprovação (ADR-0012). Sem sessão, os comandos falham na hora da chamada com uma mensagem que diz o que fazer, não no boot.

Tools

São 30, iguais no MCP e no CLI. Referência gerada: docs/TOOLS.md.

Nas escritas, a conta é: leituras antes da pergunta, as escritas aprovadas e a releitura que confere o resultado. Nenhuma delas foi provada ainda num uso real em produção, e a descrição de cada uma avisa isso.

Como funciona

1. O login guarda só o token fssessionid e o User-Agent do navegador que o gerou, cifrados. Toda requisição vai para o host do ambiente configurado, uma por vez, com intervalo e variação aleatória, e espera mais antes de cada escrita. Num 401 na produção, se FAMILYSEARCH_IMPORT_BROWSER estiver definido, a sessão é reimportada do navegador uma vez, em silêncio. Escritas nunca são repetidas sozinhas.

2. As leituras da árvore são sempre ao vivo, porque outras pessoas editam a árvore o tempo todo. O cache local serve à análise: sync baixa a linhagem (ancestrais e cônjuges até 8 gerações) e, para cada pessoa, a família e as contagens de fontes, sugestões e possíveis duplicatas. Ele trabalha em blocos e retoma de onde parou. find_gaps e export leem só dali, sem rede.

3. Datas genealógicas são guardadas como foram escritas, ao lado da forma padronizada do FamilySearch quando ela existe. Nenhuma vira um Date.

4. Antes de qualquer mesclagem vem compare_persons: fatos de cada lado, conflitos, sinais de que não são a mesma pessoa, a ordem que o FamilySearch aceita e o que a mesclagem levaria. A mesclagem confere que nada mudou desde a comparação, exige confirmar o id da duplicata, salva as duas pessoas num snapshot local logo antes de enviar e relê o resultado.

A trava de aprovação

Toda escrita monta um plano, pergunta e só então envia. A pergunta começa pelo motivo, que vai para o histórico público da pessoa. No servidor MCP a pergunta é uma elicitation: o cliente mostra um formulário a você e a resposta volta para o servidor, sem passar pelo modelo. No CLI é um diálogo nativo do macOS, com "Cancelar" como botão padrão, que não aceita resposta pela entrada padrão. A aprovação vira um ticket de uso único que cobre exatamente as escritas do plano, e a camada HTTP recusa qualquer escrita que não esteja nele.

O que ela protege: nenhuma escrita acontece pelas tools do MCP ou pelos comandos do CLI deste projeto sem uma resposta à pergunta na tela, nem por erro ou excesso de iniciativa do modelo. Sessões sem interface (claude -p, um CLI fora do macOS ou sem sessão gráfica) cancelam a pergunta, e nada é escrito. Não existe variável nem opção que desligue a trava.

O que ela não protege: um modelo decidido a contorná-la. Com Bash livre e um terminal com permissão de Acessibilidade no macOS, um osascript com System Events consegue clicar em "Aprovar" no diálogo e escolher o id pedido, e teclas enviadas ao terminal preenchem o formulário de elicitation. Quem tem acesso livre à sua máquina também pode ler a sessão e chamar a API direto, sem passar por este projeto. Hooks de Elicitation no Claude Code (nas configurações ou nos plugins) também poderiam responder no seu lugar; o doctor avisa quando encontra algum. Os detalhes estão no SECURITY.md.

O risco de termos de uso

Usar o token da sessão do navegador na API, sem uma aplicação registrada no FamilySearch, é zona cinza. O FamilySearch não dá chave de desenvolvedor para projeto pessoal, e este é o caminho que sobra. Uso pessoal, sobre a sua própria conta e em ritmo humano, reduz o risco, mas não o elimina. Se o FamilySearch bloquear ou mudar o caminho de autenticação, o projeto para de funcionar.

Arquitetura em detalhe: docs/ARCHITECTURE.md. O que a API não expõe: docs/DATA-MODEL.md.

Troubleshooting

Documentação

Licença

MIT. Uso pessoal, sobre a sua própria conta e em ritmo humano. Não use isto como serviço multiusuário nem para escrever em massa na árvore compartilhada.