Genealogy research toolkit

genealogy-mcp — 用任意 AI 助手探寻家族历史

俄语版

一个 MCP 服务，可让 Claude、ChatGPT、Cursor 或任何支持 MCP 的助手化身细致严谨的家谱研究者。它知道祖先的记录在哪里（俄罗斯、前苏联、欧洲、不列颠群岛、美国和拉丁美洲的 171 个档案馆和数据库），知道如何检索（姓名变体、转写形式、旧拼法、儒略历），也知道何时找到的确实是你的祖先——因此，助手会提供可用链接和研究计划，而不是自信满满地猜测。

它源自多年真实研究经验，服务于由 gene_archive 支持的开放家族档案：教区登记册、修订名册、第一次和第二次世界大战数据库、镇压档案、移民记录——以及我们一路上遇到的种种陷阱。背后的故事：Habr 上的一篇文章（俄语）。

概览

• 涵盖 55 个国家的 171 个档案馆和数据库，说明每处收藏了哪些资料，以及如何有效检索；还能判断历史省份的记录如今由哪个档案馆收藏（边界曾经变动，答案往往并非显而易见）。
• 31 个工具，满足家谱研究的实际需要：姓名变体和 9 种转写系统、Daitch–Mokotoff、儒略历、希伯来历和法国共和历、教会节日日期、教会斯拉夫数字、三种语言的亲属关系、DNA、证据核查、家谱审计、开放数据库实时搜索、档案查询草稿。
• 直接操作你的家谱，而不是另起一份。 指定 MyHeritage、Ancestry、Gramps 或 RootsMagic 导出的 .ged 文件，它就会原地读取、搜索和修改——只改动有变化的行，其余内容逐字节保持不变，保留副本，并在应用每项更改前先展示给你。也可以连接 gene-archive 家族网站：所有更改都会经过网站的检查，并记录在日志和 git 历史中。
• 它会记住。 保存包含完整引文的来源、待查线索和每次搜索——包括“未找到结果”——避免重复检索同一处资料。
• 设计上秉持诚实。 同名者不等于亲属：只有在姓名之外找到两项独立事实，才会关联某条记录。
• 保护隐私。 在你的电脑上运行；只有在你要求搜索时才会联网，并且只访问你指定的那个网站。
• 支持任意助手： Claude Desktop（一键安装）、Claude Code、ChatGPT、Cursor、VS Code、Windsurf、Cline。
• 提供英语、俄语和乌克兰语指南，主要指南还提供西班牙语、葡萄牙语、波兰语和德语版本。

快速开始

Claude Desktop： 下载最新版本中的 genealogy-mcp-<version>.mcpb 并打开。 Claude Code： claude mcp add genealogy -- uvx genealogy-mcp。 其他客户端： 将 uvx genealogy-mcp 设为服务命令（详情见安装）。

然后只需询问：“帮我寻找我的曾祖父。这是我目前知道的信息……”

你可以询问什么

我的曾祖父 Ivan Kolodin 大约于 1885 年出生在图拉省 Bogoroditsk 附近。我该从哪里查起？

助手会为 1880–1945 年的俄罗斯制定计划，阅读记录指南，整理姓名变体（Колодин / Колодина / Колодинъ / Kolodin / Kołodin…），提供 FamilySearch、Internet Archive 全文以及俄罗斯战争数据库的搜索链接，告诉你教区登记簿由哪个档案馆保管，并起草查询申请。

这份洗礼记录是同一个 Ivan 吗？上面写着 «Іоаннъ, отец Петръ, 1887, Сынково»。

check_match 会结合姓名变体和年龄容差逐项比较事实：除姓名外有两项独立事实相符 → 已确认；一项 → 可能；有矛盾 → 再找第三份文件。

我祖母的表亲的女儿和我是什么关系？И как это по-русски?

kinship → «троюродная сестра… / first cousin once removed»——用俄语、英语和罗马尼亚语说明，并给出预期的 DNA 共享比例。

检查我的家谱。（来自 Ancestry、MyHeritage、Gramps、Geni 等的 GEDCOM……）

audit_tree 会找出不可能的情况（出生日期晚于母亲去世日期、母亲年仅 10 岁、出生前已去世）、可能重复的人物和信息缺漏——为下一次搜索列出待办事项。

登记簿写着他于 1885 年「на Покров」出生，年份写作 ҂аѡ҃пе。

cyrillic_numerals 会读出年份（1885），feast_date 会给出 10 月 1 日（儒略历）＝1885 年 10 月 13 日。

我在 MyHeritage 上和一位匹配对象共享 230 cM。她可能是什么亲属？

dna_match：表亲二代、隔代两代的表亲一代、半血表亲一代……以及为什么只有文件才能确定。

沃伦州的教区登记簿现在在哪里？

where_are_records：日托米尔州档案馆（宗务会档案）、罗夫诺州和沃伦州档案馆——边界曾有变动，因此档案馆不一定位于今天对应的地区。

记住我们查到的内容，下周继续。

在你的电脑上建立研究项目：记录人物、带完整引文的来源、未解决的线索，以及每次搜索的日志——包括“未找到”——这样就不会有人重复搜索同一个地方。支持导入和导出 GEDCOM。

把我们查到的内容写入我的家族网站。

如果你的家族档案是 gene-archive 网站，请将其文件夹路径提供给项目工具：助手会直接读取档案——找出缺失的人物、没有文件佐证的日期——并且对它所做的每项更改，都会经过网站自身的检查，写入更正记录和研究日志，以你的名义提交到 git 并重新构建网站。它会先显示更改，只有在你确认后才会写入。

这是我的家谱——把我们查到的内容加进去。

也可以提供你在 MyHeritage、Ancestry、Gramps、RootsMagic、Family Historian 或 webtrees 中维护的家谱 GEDCOM 文件：助手会读取、搜索并直接修改文件。只会重写有更改的行——你使用的软件自有的标签、照片、备注和文件头都会逐字节保留；写入前会显示这些行，保存一份文件副本，并将搜索日志、线索和更正记录保存在文件旁边。然后将文件重新导入你的软件（Family Historian 和 webtrees 可直接使用 GEDCOM）。非 UTF-8 编码的文件只能读取，不能修改。

为什么使用它

没有它	使用 genealogy-mcp
助手只会列出两三个知名网站	根据国家、年份和记录类型筛选 171 个来源，每个来源都附有“如何有效搜索”
只搜索一种拼写	搜索拼写变体、1918 年以前的拼写、男性／女性形式、9 种转写系统和名字对应形式（Иван = Іоаннъ = Jan = Johann = Juan）
虚构或失效的 URL	使用经过测试的 URL 模板生成即用型搜索链接；每周都会检查每个网站
“这很可能是你的祖先”	明确的证据规则：同名者不等于亲属
照单全收日期	儒略历 ↔ 公历、根据年龄推算出生年份并考虑合理误差，以及将日期规范化为 GEDCOM 格式
泛泛的建议	记录指南：教区登记簿、忏悔名单、修订名册、户籍册、一战／二战记录、镇压档案、乘客名单、人口普查、欧洲民事登记、拉丁美洲记录
你得从头写信给档案馆	为俄罗斯 ZAGS、国家档案馆、军事档案馆和 FSB 档案馆准备申请草稿，也可用英语、西班牙语或葡萄牙语联系任何档案馆
不记得不同聊天之间的内容	研究项目会记住人物、来源、线索和每次搜索
无法操作你的家谱	直接读取和修改你自己的 GEDCOM 文件，不会丢失内容，并会先显示每项改动
无法读取旧式数字和日期	教会斯拉夫数字、教会节日、儒略历、希伯来历和法国共和历
“在 FamilySearch 上搜索你的名字”	实时搜索 Internet Archive 全文、WikiTree、Open Archives 和 Wikidata 的地点历史
DNA 匹配令人困惑	共享 cM → 符合的亲属关系

大多数家谱 MCP 服务只将助手连接到一项服务或一个文件。genealogy-mcp 还提供围绕它们展开的研究方法——去哪儿查、如何搜索、如何解读和评估查到的信息——并且也能操作你自己的家谱文件。它可以与提供你所用服务的 MCP 服务并行运行，例如 FamilySearch 客户端。

所有操作都在你的电脑上进行。只有当助手执行实时搜索（search_online、search_book_pages、place_history）时，服务才会联网，并且只会将该查询发送到对应的网站。

覆盖范围

• 全球： FamilySearch（记录和未编目的图像目录）、Internet Archive 全文、MyHeritage、 Geni、WikiTree、Find a Grave、BillionGraves、Arolsen Archives、Yad Vashem、JewishGen、Matricula、Geneanet、Wikipedia。
• 俄罗斯和苏联： Yandex Archive、档案指南、VGD 论坛、Pamyat Naroda、OBD Memorial、gwar.mil.ru、 Road of Memory、Immortal Regiment、Open List、Immortal Barrack、Returned Names、PSTGU martyrs、NashiPredki、 metricabook.ru、Rodovod、总统图书馆和国家电子图书馆、历史图书馆、古地图、教会历史、RIA-1914、地区档案馆、ZAGS、TsAMO、RGVIA、RGIA、GARF。
• 乌克兰、白俄罗斯、摩尔多瓦、罗马尼亚、波兰、波罗的海国家： 国家档案门户和目录、TsDIAK、 genealogica.ro、比萨拉比亚家谱、deportari.org、Cartea Memoriei、1772—1774 年摩尔达维亚人口普查、 Geneteka、Szukajwarchiwach、epaveldas、Raduraksti、爱沙尼亚档案馆。
• 欧洲： ICRC 一战战俘档案、CWGC、Volksbund、ScotlandsPeople、FreeBMD、爱尔兰民事记录和人口普查记录、Archion、 GenWiki、FranceArchives、Mémoire des hommes、Antenati、PARES、Digitarq、Open Archives（NL）、比利时国家档案馆、 Riksarkivet、Digitalarkivet、Danish Family Search、HisKi、芬兰数字档案馆、Hungaricana、Acta Publica（捷克）、保加利亚国家档案馆、FreeCEN、FreeREG、The National Archives、GRO、威尔士报纸。
• 德国和德语地区： 一战伤亡名单、GEDBAS、Online-OFB、德国数字图书馆、Bundesarchiv、 波罗的海传记词典、黑海德国人（Odessa3）、Poznań Project、Metryki。
• 犹太家谱： JRI-Poland、Gesher Galicia、LitvakSIG、JewishGen、Yad Vashem、Steve Morse One-Step 工具。
• 高加索和中亚： 格鲁吉亚国家档案馆、哈萨克斯坦、乌兹别克斯坦、 吉尔吉斯斯坦、塔吉克斯坦和土库曼斯坦中央国家档案馆。
• 美洲： FamilySearch 拉丁美洲、墨西哥 AGN、巴西国家档案馆和移民博物馆、 Hemeroteca Digital、阿根廷 CEMLA 和 AGN、智利国家档案馆、NARA、埃利斯岛、Chronicling America、 USGenWeb、加拿大图书馆与档案馆、魁北克 BAnQ、Pier 21。
• 澳大利亚和新西兰： Trove、澳大利亚国家档案馆、Papers Past、新西兰 BDM。

提供英文、俄文和乌克兰文档案指南，主要指南还提供西班牙文、葡萄牙文、波兰文和德文版本。

安装

**Claude Desktop，一键安装：**从 最新版本下载 genealogy-mcp-<version>.mcpb 并打开——Claude Desktop 会安装它，并询问你要将研究项目存放在哪里。

其他安装方式需要 uv（它会自行获取 Python 和软件包）。

Claude Desktop，手动安装——依次打开 Settings → Developer → Edit Config，然后添加：

{
  "mcpServers": {
    "genealogy": {
      "command": "uvx",
      "args": ["genealogy-mcp"]
    }
  }
}

Claude Code：

claude mcp add genealogy -- uvx genealogy-mcp

Cursor（~/.cursor/mcp.json）、Windsurf、Cline——使用与 Claude Desktop 相同的 mcpServers 配置块。 VS Code（.vscode/mcp.json）：{"servers": {"genealogy": {"command": "uvx", "args": [ …same… ]}}}。

**Docker：**先运行 docker build -t genealogy-mcp .，再运行 docker run -i --rm genealogy-mcp（stdio），或运行 docker run --rm -p 8000:8000 genealogy-mcp --http --host 0.0.0.0（在 /mcp 提供 HTTP 服务）。

**将你的 gene-archive 站点用作项目：**将此服务与 gene-archive 一起安装—— pip install "genealogy-mcp[site]" 或 uvx --from "genealogy-mcp[site]" genealogy-mcp（gene 命令会在 PATH 中或服务的 Python 所在目录下找到；若在其他位置，请设置 GENE_CMD），然后将文件夹名称填入 GENEALOGY_MCP_SITES（或 Claude Desktop 扩展设置），也可以直接将其路径提供给助手。GENE_AUTHOR 用于设置 git 历史记录中的名称（默认值：git config user.name）。

**将 GEDCOM 文件中的家谱用作项目：**向助手提供 .ged 文件的路径（或将其名称填入 GENEALOGY_MCP_SITES）。副本会保存为 tree.ged.bak（上次更改前）和 tree.before-genealogy-mcp.ged （首次更改前）；日志保存在 tree.ged.research.json 中。

通过 HTTP 连接的客户端（ChatGPT connectors、远程 Agent）：在 HTTPS 后运行 genealogy-mcp --http --host 0.0.0.0 --port 8000，并添加 https://your-host/mcp。 在 HTTP 模式下，audit_tree 只接受 GEDCOM 文本，绝不接受文件路径。

此软件包已发布在 PyPI 和 官方 MCP Registry（io.github.igormel81/genealogy-mcp）中：运行 uvx genealogy-mcp 即可安装并运行。

研究工作流

从 project_view 开始：查看政策、本地来源、当前问题和负责人任务。 从家庭文件和民事登记记录着手，依次查阅现有记录、原始资料，最后再看次级线索。project_policy 用于按项目配置限制和档案申请偏好。每条线索都有后续步骤；来源核查会区分没有结果与网站无法访问。没有 site.json 的自定义档案文件夹无需转换或修改即可读取。请参阅工作流、政策和来源核查。

171 条目录条目是推荐项，并非 171 个实时连接器。有六项服务支持 search_online；Wikidata 提供地点历史信息。其他来源需要通过浏览器访问，或由用户提供文档。Gallica 页面搜索和事件证据详见书籍和事件引用。

工具

工具	功能
plan_research	针对某个国家和时期制定逐步计划：有哪些记录、指南、按顺序查找的来源
find_sources	按国家／地区（europe、latin_america、russian_empire……）、年份和记录类型查找来源
source_details	单个来源：涵盖范围、访问方式、搜索方法
where_are_records	历史省份的记录如今由哪些档案馆保存（俄罗斯帝国、波兰、加利西亚、布科维纳、东普鲁士、波罗的海地区、高加索）；指定年份时，说明当时这片土地归属何方（南比萨拉比亚：1857–1878 年属摩尔达维亚／罗马尼亚，1918–1944 年属罗马尼亚）；指定村庄时，说明其记录由哪座教堂保存
search_links	为姓名及其变体生成可直接使用的搜索 URL
search_online	实时搜索：Internet Archive 全文、Chronicling America、WikiTree、Open Archives、Open List、Gallica OCR 文档搜索
place_history	Wikidata：某村庄历年来的归属、坐标、维基百科条目；如有资料，还包括其所属教堂
name_variants	拼写、旧正字法、性别形式、转写、Daitch–Mokotoff 编码、名字对应形式（包括意第绪语和希伯来语）、父称；摩尔多瓦姓氏的罗马尼亚语、俄语和苏联摩尔多瓦语形式；标记第二姓氏（«Мокану, он же Плеш»）
normalize_date	将 “около 1899”、“9 de octubre de 1899” 转换为 ABT 1899、9 OCT 1899
convert_calendar	儒略历 ↔ 公历、希伯来历、法国共和历
feast_date	将 «на Покров»、«после Петрова поста»、复活节、Wielkanoc……转换为指定年份的日期
cyrillic_numerals	҂аѡ҃п ↔ 1880
birth_year_from_age	根据记录中的年龄推算出生年份范围
estimate_birth_year	根据亲属推算出生年份（长子出生年份 −27、配偶和兄弟姐妹 ±8、父母 +18…+45）以及年龄：以 BET … AND … / ABT … 格式给出，并附上说明；若年龄不可能属于同一个人，则标记为可能的同名者
kinship	以 ru/en/ro 显示亲属关系称谓，并给出预期 DNA 共享比例
dna_match	根据共享 cM 推测符合哪些亲属关系（Shared cM Project 4.0）
check_match	判断找到的记录是否属于目标人物？逐项比对所有事实并给出结论（也包括西班牙语地区的双姓氏）
parent_hypothesis	根据父称提出父母假设：按姓名、村庄和年龄为候选人排序，列出支持与反对的论据（孙辈姓名、教父母、担保人），提示来自其他村庄的同名者，并指出可证实假设的记录——仅为线索，不是关联
audit_tree	检查 GEDCOM 或 family_tree.json 中不可能的事实、重复项和缺失项
project_view、project_save、project_log、project_transfer	在对话之间保存研究项目：人物、家庭、来源、线索、搜索日志、GEDCOM 导入／导出；也可操作基因档案网站文件夹（会记录检查结果和日志），或就地修改你自己的 .ged 文件
search_book_pages	搜索 Gallica 书籍中的 OCR 摘录、扫描序列号和稳定页面链接
project_evidence	按事件检查引文覆盖情况、失效引用和缺失定位信息，并按世代确定优先级
project_policy	本项目的策略：活跃问题数量上限、档案申请草稿、对在世人员的研究以及所有者任务
project_coverage	已阅读内容：教区 → 年份 → 部分 → 胶片和帧 → 完整／部分（截至第……号）／未找到；以及这些村庄和年份中尚未阅读的内容
film_reading_plan	逐页阅读未编目的 FamilySearch 胶片：胶片的阅读顺序、缩略图还是完整帧、低于速率限制的请求额度，以及需要记录的内容
draft_archive_request	给登记处或档案馆的申请信草稿
record_guide	如何阅读和查找某类记录
glossary	旧俄语记录术语释义
资源： genealogy://sources（目录）、`genealogy://guide/research/{en	ru}`（完整研究指南）、
`genealogy://guide/prompts/{en	ru}（每个步骤的现成请求）、genealogy://records/{topic}、genealogy://glossary`。
提示词： 开始研究、核查发现、转录记录、写信给档案馆。

隐私与诚信

• 服务不会自行向任何地方发送数据。实时搜索（search_online、search_book_pages、place_history）会将查询内容——姓名、 年份、地点——发送到所搜索的那个网站。研究项目是你电脑上的文件 （~/Documents/genealogy-mcp 或 GENEALOGY_MCP_HOME）；在共享 HTTP 服务上，这些功能会被关闭。
• 你使用的助手是独立服务，有自己的隐私政策——粘贴在世人士的详细信息前请三思。
• 信件都是草稿：由你检查并发送。
• 助手收到的规则：引用原始资料，保留相互冲突的版本，将猜测标记为“可能”，没有证据时绝不把同名者关联起来。

基准测试

evals/tasks.json 包含 35 个答案可核查的问题：按教会节日、儒略历、希伯来历和共和历计算日期，西里尔数字， Daitch–Mokotoff、摩尔多瓦姓氏、DNA、亲属关系、旧称、历史省份的档案和按年份划分的边界、证据核查、 不可能属于同一人的年龄、记录历史。evals/check_tools.py 在 CI 中运行，并检查工具是否正确回答所有问题。 evals/run.py 使用 Claude 模型，在不使用和使用该服务的情况下分别询问相同问题并评分 （需要 API 密钥；运行需要付费，因此手动运行：Actions → 基准测试）。

参与贡献

有关来源字段和贡献指南，请参阅 CONTRIBUTING.md。 缺少某个来源或链接已变更？编辑 tools/make_sources.py，运行 python3 tools/make_sources.py 和 python3 -m unittest discover tests，然后提交拉取请求。记录指南位于 src/genealogy_mcp/guides.py。

另请参阅

• gene_archive — 一个用于家族档案网站的开源引擎： 家谱树、故事、文档、地图、GEDCOM、在线编辑器和亲属评论。

MIT 许可证。