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 流程获取的 Bearer 令牌。
FS_ENV_FILE	用于读取这些设置以及重新读取已刷新的令牌的环境变量文件。默认值：从工作目录向上查找最近的 .env 文件。
FS_CLIENT_ID	你注册的应用的客户端 ID，可通过 auth_status 查看。
FS_ENVIRONMENT	production（默认）或 FamilySearch 沙盒环境 integration。
FS_TIMEOUT	HTTP 超时秒数。默认值为 60。

.env.example 列出了这些变量，并附有注释。

工具

共 28 个工具。所有工具都只读取数据；download_image 还会将其获取的页面写入本地文件。

地点

FamilySearch 的 Places API 支持匿名访问。

工具	需要令牌	用途
search_places	否	将地名解析为完整的行政区划名称和坐标。
search_places_at_date	否	按指定年份解析当时的地点。记录中记载的县如今可能已不复存在，这很常见；将其归入现代县名之下会造成难以察觉的错误。
get_place	否	读取某个地点的信息：行政区划链、类型、坐标，以及该行政区划的存续日期。
get_place_jurisdictions	否	沿包含关系向上遍历行政区划链——例如，了解如何将“Kaskaskia”解析为“Kaskaskia, Randolph, Illinois, United States”。
get_place_children	否	查询某个行政区划直接包含的地点，即向下遍历。

记录和合集

工具	需要令牌	用途
search_records	是	按姓名、人生事件、父母、配偶、记录类型或合集搜索历史记录。每个条件都会进行筛选，结果会说明 FamilySearch 对每项条件是精确匹配、放宽处理还是忽略。每条记录返回一个命中项，并列出记录上的其他人物。
get_record	是	完整读取一条已编入索引的记录：记录上的每个人，以及每个人对应的带标签字段。
get_record_image	是	查找记录对应的文档图像；如果未发布图像，则返回胶片编号。
get_records_on_image	是	获取从一张图像编入索引的所有记录。人口普查页上可能有 40 个人。
fulltext_search	是	在页面图像的手写识别文本中搜索姓名或短语，文本主要来自契约、遗嘱、遗产认证和法庭档案。机器识读内容仅作线索：请打开图像并引用图像。
search_collections	否	按合集标题中的词语查找记录合集，并查看其覆盖范围，以及缓存目录的规模和年代。
get_collection	否	查看某个合集：它的覆盖范围和所含内容。
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	是	一次调用即可获取父母、配偶、子女和兄弟姐妹。
get_person_sources	是	查看家谱树附加了哪些来源，以及每个来源支持哪些事实。这是离开家谱树最快的途径。
get_ancestry	是	向上追溯家谱，最多 8 代，并按安恩塔费尔编号法编号。
get_descendancy	是	向下追溯家谱，最多 4 代。
get_person_memories	是	查看附加的照片、文档和故事。
get_person_changes	是	查看更改日志：谁在何时以及为何编辑了此个人资料。
get_matches	是	查看 FamilySearch 自行识别的重复项和记录匹配候选项。
compare_person	是	将你自己记录的已故人士信息与其个人资料进行比较：哪些内容一致、个人资料缺少哪些信息、哪些内容不同，并为每个数据包提供一项建议更改，供你手动完成。

设置

工具	需要令牌	用途
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 会读取网站目录页面所读取的条目，使用方式与记录搜索相同。对于每卷胶片，它会报告 DGS 编号，供 get_film_image 和 fulltext_search 使用；它还会向图像存储服务查询你的账户是否可以查看该胶片，以及其中有多少张图像。DGS 不是缩微胶片编号；胶片可能受到访问限制，也可能从未数字化；目录描述只是编目员的摘要，因此请查阅并引用图像。
• 搜索条件会进行筛选，但除非使用 exact，匹配范围较宽。 FamilySearch 会将搜索词视为排序提示，除非另有指定，因此在姓名搜索中加入死亡年份只会改变结果排序。此服务则要求每项条件都匹配；loose=True 会改回排序提示。即使设为必需，条件也只会排除与其矛盾的记录：没有出生年份的记录仍符合“生于 1850 年”，年份前后相差五年也算匹配。exact=True 会要求每项条件都存在且匹配，并将地点限制在指定的县或州。每条结果的 filters 都会说明各项条件的应用方式，因此可以据此判断零结果是否确实代表没有符合条件的记录。
• 令牌会过期，刷新后的令牌会自动读取。 令牌的有效期约为一小时。遇到 401 时，服务会从 env 文件重新读取 FS_ACCESS_TOKEN 并重试一次，因此只需刷新该文件即可。令牌未被接受时，auth_status 会报告 token_accepted: false。
• 限流时会重试一次。 如果 429 要求等待不超过 15 秒，服务会等待后重试。等待时间更长或再次遇到 429 时，会返回 rate_limited 和服务提供的 Retry-After。
• 不接受未知参数。 拼写错误或凭空捏造的参数会触发错误，并列出该工具支持的参数。参数不会被静默丢弃，否则带筛选条件的搜索可能悄悄返回未筛选的结果。
• 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 会使用环境文件中的令牌，再次向 FamilySearch 提问只有实时 API 才能回答的问题。有关变更应包含哪些内容，请参阅 CONTRIBUTING.md。

许可证

MIT。