FamilySearch

familysearch-mcp

FamilySearchでの系譜調査のためのMCPサーバーです。歴史的地名ガゼッティア、索引付き記録の検索、記録のページ画像、共有家系図の閲覧を提供します。

このサーバーからFamilySearchに書き込みを行うことはありません。共有家系図はコミュニティによって編集されており、同姓同名の人物が混同されていることもよくあります。そのため、家系図の検索結果は手掛かりとして扱い、元の記録を確認して引用してください。

これは独立したプロジェクトです。FamilySearchによって開発、推奨、サポートされているものではありません。

認証情報

このパッケージにはクライアント ID が同梱されておらず、FamilySearch のパスワードを扱うこともありません。 記録、画像、家系図を利用するには、ご自身で登録したFamilySearchアプリケーションのアクセストークンが必要です。理由と取得方法についてはdocs/AUTH.mdをご覧ください。

地名ガゼッティア、コレクションカタログ、フィルムブラウザーはトークンなしで利用できるため、何も設定せずに新規インストールした状態でも動作します。

インストール

uvx familysearch-mcp

これによりサーバーがstdio経由で実行されます。MCPクライアントはこの方法でサーバーを起動します。通常は自分で実行するのではなく、クライアントの設定に記述します。

Claude Desktop

{
  "mcpServers": {
    "familysearch": {
      "command": "uvx",
      "args": ["familysearch-mcp"],
      "env": { "FS_ENV_FILE": "/path/to/familysearch.env" }
    }
  }
}

トークンを env に直接貼り付けるのではなく、環境変数ファイルを指定してください。クライアントの設定に保存したトークンを置き換えるには、設定を編集して再起動する必要があります。ファイルに保存したトークンなら、セッション中に再読み込みできます。トークンがない場合は env を省略してください。匿名で利用できるツールは引き続き動作します。

Claude Code

claude mcp add familysearch -e FS_ENV_FILE=/path/to/familysearch.env -- uvx familysearch-mcp

設定

変数	意味
FS_ACCESS_TOKEN	アプリケーションのOAuthフローで取得したベアラートークンです。
FS_ENV_FILE	これらの設定を読み込む環境変数ファイルと、更新されたトークンを再読み込みするファイルです。デフォルトは、作業ディレクトリから上位に向かって最初に見つかった .env です。
FS_CLIENT_ID	登録したアプリケーションのクライアント ID です。auth_status で確認できます。
FS_ENVIRONMENT	FamilySearchサンドボックスの production（デフォルト）または integration です。
FS_TIMEOUT	HTTPタイムアウト（秒）です。デフォルトは60です。

.env.exampleには、コメント付きでこれらの変数が記載されています。

ツール

ツールは28個あります。すべて読み取り専用です。download_image は取得したページをローカルファイルにも書き込みます。

場所

FamilySearchのPlaces APIは匿名で利用できます。

ツール	トークンが必要	用途
search_places	いいえ	地名を、管轄区域の完全な名称と座標に解決します。
search_places_at_date	いいえ	指定した年当時の場所を解決します。現在は存在しない郡を記録が示しているのはよくあることです。その記録を現代の郡に分類するのは、気づきにくい誤りです。
get_place	いいえ	1つの場所について、管轄区域の階層、種類、座標、その管轄区域が存在した期間を読み取ります。
get_place_jurisdictions	いいえ	上位の包含関係をたどります。「Kaskaskia」が「Kaskaskia, Randolph, Illinois, United States」になるまでの経路を確認できます。
get_place_children	いいえ	管轄区域に直接含まれる場所をたどります。

記録とコレクション

ツール	トークンが必要	目的
search_records	はい	名前、ライフイベント、両親、配偶者、記録の種類、またはコレクションで歴史的記録を検索します。各条件で絞り込み、FamilySearch が各条件を正確に適用、緩和、または無視したかを結果に示します。記録ごとに 1 件の結果を返し、同じ記録に記載されたほかの人物も示します。
get_record	はい	インデックス化された記録を 1 件、全文で読み取ります。記録に記載されたすべての人物と、それぞれの人物に紐づくラベル付きフィールドを確認できます。
get_record_image	はい	記録の元になった文書画像を探します。画像が公開されていない場合は、フィルム番号を返します。
get_records_on_image	はい	1 枚の画像からインデックス化されたすべての記録を取得します。国勢調査のページには 40 人分の記録が含まれます。
fulltext_search	はい	主に証書、遺言、遺産検認、裁判記録のページ画像から、手書き文字認識されたテキストを検索し、ページ内のどこにでもある名前や語句を探します。これは機械による読み取りです。画像を開いて引用してください。
search_collections	いいえ	タイトルの語句で記録コレクションを探し、その収録範囲と、キャッシュされたカタログの規模や古さを確認します。
get_collection	いいえ	コレクションを 1 件読み取り、収録範囲と収録数を確認します。
get_collection_fields	いいえ	コレクションのインデックスフィールドコード（PR_FTHR_NAME →「父親の名前」）を解読します。
browse_waypoints	いいえ	コレクションの場所、巻、画像を閲覧して、インデックス化されていないページにたどり着きます。
get_catalog_entry	はい	FamilySearch のカタログ項目を読み取ります。タイトル、著者、場所、注記のほか、各フィルムまたは DGS の説明、画像数、閲覧できるかどうかを確認できます。contains を使うと、数千件に及ぶ項目を目的の巻や事件に絞り込めます。film_number を使うと、DGS 番号またはマイクロフィルム番号だけで項目と巻を見つけられます。

ページ画像

ツール	トークンが必要	目的
get_image_links	ページの取得に必要	画像 ark を取得可能な URL に解決します。全ページ画像、ディープズーム、サムネイル、前後のページを取得できます。また、トークンがあれば、引用に必要なフィルム番号と画像番号も取得できます。トークンがない場合はナビゲーション情報のみ返されます。
get_film_image	ページの取得に必要	引用に ark ではなくフィルム番号と画像番号が記載されている場合に、そのページにアクセスします。ページの存在確認にはトークンは不要です。
download_image	はい	ページ画像を新しいローカルファイルにダウンロードし、読み取れるようにします。

共有ツリー — 手がかりであり、情報源ではありません

ここにある各ツールは、コミュニティによって編集されたプロフィールを読み取ります。その旨は各ツールの説明に記載されています。

ツール	トークンが必要	目的
get_person	はい	共有ツリーにある人物の名前、性別、事実を読み取ります。
get_person_relatives	はい	両親、配偶者、子ども、兄弟姉妹を 1 回の呼び出しで取得します。
get_person_sources	はい	ツリーで情報源として紐づけられているものと、それぞれが裏付ける事実を確認します。ツリーから抜け出す最短ルートです。
get_ancestry	はい	最大 8 世代まで祖先をたどり、アーレンフェル番号で示します。
get_descendancy	はい	最大 4 世代まで子孫をたどります。
get_person_memories	はい	添付された写真、文書、ストーリーを確認します。
get_person_changes	はい	変更ログを確認します。このプロフィールを誰が、いつ、どのような理由で編集したかが記載されています。
get_matches	はい	FamilySearch 独自の重複候補と記録一致候補を取得します。
compare_person	はい	故人についての手元の記録と、その人物のプロフィールを比較します。一致する点、プロフィールにない情報、異なる点を確認し、パケットごとに変更案を 1 件提示します。変更は手動で行ってください。

セットアップ

ツール	トークンが必要	目的
auth_status	いいえ	設定済みの項目と不足している項目を報告し、FamilySearch が引き続きトークンを受け付けるかどうかを確認します。

動作

• ツリーは証拠ではありません。 ツリーツールが読み取るプロフィールは、誰でも編集できます。記録を探すために使ってください。get_person_sourcesは、ツリーから文書へとたどれるため、特に有用です。
• 比較は提案するだけで、変更はしません。 compare_personは、ある人物について、あなた自身が持つ名前、出来事、親族、出典を受け取り、プロフィールを読み、合致している点、プロフィールにない点、異なる点を報告します。変更案はそれぞれ、出典、関連付ける事実、あなたが不足部分を記入する変更理由の草案、ウェブサイトで変更する場所をひとまとめにして提示します。記録を読んだうえで、変更は一度に一つずつ、あなた自身で行います。存命の可能性がある人物については処理を拒否し、プロフィールの統合、項目の削除、関係の置き換え、存命状況の変更を提案することはありません。docs/COMPARE.mdを参照してください。
• ペルソナは記録そのものではありません。 検索結果には、ある記録について一人の人物が述べた内容の要約が返されます。get_recordはその裏付けとなるインデックス済みのフィールドを、get_record_imageは文書そのものを返します。引用する前に、この一連の情報をたどって確認してください。
• 管轄区域は変わります。 search_places_at_dateは、指定した年当時の地名と場所を特定します。1820年の記録を、現在その土地を管轄する郡に分類するのは、よくあるうえに見つけにくい誤りです。
• 記録検索にはウェブサイトの検索サービスを使用します。 API独自の記録検索は、ほぼすべてが移民記録で構成される部分的なインデックスを参照します。search_recordsは、代わりにFamilySearchウェブサイトが使用するサービスに問い合わせます。このサービスには、あなたのトークンとブラウザーのUser-Agentが必要です。これは文書化されておらず、FamilySearchによって変更または終了される可能性があります。比較についてはdocs/API-NOTES.mdを参照してください。
• 全文検索は機械による読み取りです。 fulltext_searchは、記録検索と同様に、あなたのトークンとブラウザーのUser-Agentを使い、文書化されていない経路からウェブサイトの全文検索サービスに問い合わせます。検索対象のテキストは手書き文字認識によるものなので、名前や数字はよく誤読されます。各ヒットには、一致した箇所とページの画像ARKが示されます。読むべきなのはページそのものであり、引用する際もページを参照してください。一部のコレクションと巻のみが機械で読み取られているため、結果がないからといって何も存在しないとは限りません。ORと記述しない限り、すべての単語が一致する必要があります。そうしない場合、サービスはどれか一つの単語に一致するだけで結果を返します。
• カタログに記載されるのは所蔵資料であり、記録ではありません。 get_catalog_entryは、記録検索と同様に、ウェブサイトのカタログページが読み取る項目を取得します。各フィルムについて、get_film_imageとfulltext_searchが使用するDGS番号を報告し、あなたのアカウントで閲覧できるか、また何枚の画像が収録されているかを画像ストアに問い合わせます。DGSはマイクロフィルム番号ではありません。フィルムは閲覧制限が設けられている場合も、デジタル化されていない場合もあります。また、説明はカタログ担当者による要約です。画像を読み、引用してください。
• 検索条件は、exactを指定しない限り、緩やかに絞り込みます。 FamilySearchは、明示的に指定しない限り、検索語をランキングの手掛かりとして扱うため、名前検索に死亡年を追加しても、結果の順序が変わるだけです。このサーバーは、すべての条件に一致するよう検索します。loose=Trueを指定すると、ランキング方式に戻ります。必須条件であっても、条件と矛盾する記録だけが除外されます。出生年の記載がない記録は「1850年生まれ」という検索条件にも一致し、年は前後5年まで一致とみなされます。exact=Trueを指定すると、各条件が記録に存在し、かつ一致している必要があります。また、場所は指定した郡または州まで一致します。各結果のfiltersには、各条件がどのように適用されたかが示されます。そのため、結果がない場合は、その不在を否定的な証拠として解釈できる場合も、できない場合もあります。
• トークンは期限切れになりますが、更新後のトークンが取得されます。 トークンの有効期間は約1時間です。401が返されると、サーバーは環境ファイルからFS_ACCESS_TOKENを再読み込みし、1回だけ再試行します。そのため、ファイルを更新するだけで十分です。無効な場合は、auth_statusがtoken_accepted: falseを報告します。
• スロットリング時には1回再試行します。 最大15秒待つよう求める429が返された場合は、その時間待ってから再試行します。待ち時間がそれより長い場合、または2回目の429が返された場合は、サーバーのRetry-Afterとともにrate_limitedが返されます。
• 不明なパラメーターは拒否されます。 スペルミスや、存在しない引数を指定するとエラーになり、そのツールが受け付けるパラメーターの一覧が表示されます。指定が黙って無視され、絞り込み検索のつもりが気付かないうちに絞り込みなしの結果を返すことはありません。
• download_imageは、渡された内容を慎重に扱います。 リクエストにあなたのトークンが含まれるため、FamilySearchのホスト上にあるHTTPS URLのみを取得します。作成するのは画像ファイルとPDFファイルのみで、既存ファイルを上書きすることはありません。
• 一部の経路は公開されている文書に記載されていません。 FamilySearch Historical Records APIはログインウォールの向こう側にあるため、該当する経路とレスポンス形式は、代わりに実際にアクセスして確認されています。コードのそばのコメントに確認時期が記載されており、確認内容はdocs/API-NOTES.mdに記録されています。tests/live_check.pyで再度確認できます。

開発

git clone https://github.com/ianderso/familysearch-mcp
cd familysearch-mcp
uv sync --extra dev
uv run pytest                  # mocked with respx; no token, no network
uv run ruff check .
uv run ruff format --check .

uv run python -m tests.live_check は、ライブ API でのみ回答できる質問を FamilySearch に再度問い合わせます。トークンは環境ファイルから取得します。変更に求められる内容については、CONTRIBUTING.md を参照してください。

ライセンス

MIT。