US Places, Then

us-places-mcp

一个记录过去地点归属的 MCP 服务。记录遵循事件发生日期当天对某地拥有管辖权的辖区，而非今天的辖区：一份 1795 年的农场契约，如今该农场位于宾夕法尼亚州格林县，但契约存放在华盛顿县的档案中，因为格林县是次年才划分出来的。这个服务可以回答决定该联系哪个办公室的问题：

• 在那一天，这个地点属于哪个县？ 数据来自 Newberry 图书馆的 美国历史县界地图集，记录了 1629 年至 2000 年间美国每个县的设立和边界变化，精确到日期，并注明相关法案。OpenHistoricalMap 导入了这套地图集并免费提供数据（CC0）；本服务会查询它。
• 这段土地描述对应地面上的哪里？ 根据土地管理局的全国公共土地测量数据，"E½NE Sec. 18, T84N R39W, 5th P.M." 可转换为中心点、边界框和 BLM 标识符；反过来，地图图钉也能转换为土地描述。
• 这份土地专利背后的案件档案在哪里？ 土地专利是整个流程的终点。国家档案馆中的档案保存着申请材料；对于宅地申请，还包括多年的居住证明、证人证词和公民身份文件。本服务会指出对应的档案及系列，并构建搜索内容。
• Mount Hope Cemetery 或 Hines Corners 曾在哪里？ USGS 的地名信息系统（GNIS）为其所知的每个地理要素命名并标注位置，包括标注为“(historical)”的消失城镇。2021 年，该系统移除了墓地、教堂、学校、邮局和其他人工设施；本服务还会搜索 USGS 留存的 2021 年 8 月档案，并说明是哪个数据源提供了结果。
• 这里曾有哪些邮局，存在于何时？ Richard Helbock 汇编了 1639 年至 2000 年间所有美国邮局的列表，由 Cameron Blevins 进行地理编码：共 166,140 个邮局，并附有开办和停办年份。邮局往往是小村庄唯一留下的踪迹。
• 有哪些旧地图显示这个地点？ 列出自 1884 年以来覆盖该点的所有 USGS 地形图，按年代从早到晚排序，并附上扫描件链接。

本服务不会向任何地方写入数据，也不会保存家谱。它可以与 nara-catalog-mcp 配合使用，后者能执行本服务构建的档案搜索；也可以与 familysearch-mcp 和 snac-archives-mcp 搭配使用。

这是一个独立项目，与 Newberry 图书馆、OpenHistoricalMap、土地管理局、美国地质调查局、Harvard Dataverse、数据集作者或国家档案馆均无关联，也未获得其认可或支持。

工具

该服务发布 12 个只读工具，并为客户端提供了注释。其中 5 个完全不会发起网络请求。

指定日期的管辖权

工具	用途
county_at	查询某个点在某个日期（某一天、某个月或某一年）属于哪个县（或哪些县）。返回管辖方、相关日期、设立该管辖权的事件和法规、该地点所属县的完整沿革、某一年内的变更（请手动核查这些变更），以及是否有两个政府对此存在争议。
county_history	查询某个县的所有版本：何时设立、由何处划出，以及之后的每次变更和相关法规。

联邦土地

工具	用途
parse_legal_description	解析各种写法的土地描述（E½NE、E2NE、E 1/2 NE 1/4、“the east half of the northeast quarter”、GLO 补零格式 0840N、地块、多个地段），提取各个部分，包括四分之一地块，并对任何推测结果发出警告。离线运行。
plss_locate	在地图上定位一段土地描述：返回质心、边界框、面积和 BLM 的 ID，精确到镇区、地段、四分之一地块或小地块。
plss_from_point	查询某个点所在的测量地段：镇区、范围、地段和四分之一地块。
public_land_state	判断某个州是否属于联邦土地；若不属于，则查询谁首次授予了土地所有权及相关记录所在位置；若属于，则查询其子午线和特殊情况。离线运行。

消失的地点与旧地图

工具	用途
find_place_name	查询 GNIS 中的地名：位置点、类别、州和县。搜索实时 GNIS；指定州后，还会搜索 2021 年 8 月的档案，其中保留了 GNIS 当年删除的墓地、教堂、学校、邮局和建筑；并说明哪个来源提供了结果。
post_offices	查询 1639 至 2000 年间存在过的美国邮局：可按名称、州和现今所属县查询，也可按某个点附近和指定年份查询。每个结果都包含其运营年份、是否持续运营，以及已进行地理编码时的位置信息。
historical_topo_maps	查询覆盖某个点的所有 USGS 地形图，按年代从早到晚排列：包括日期、比例尺和分幅，以及 GeoPDF、GeoTIFF 和 JPEG 预览链接，还有可查看 JPEG 和 KMZ 的 TopoView 链接。

从土地专利到案件档案

工具	用途
find_land_entry_file	根据土地专利的 Authority 查询：土地申请类型、档案内容、对应的 National Archives 系列、可直接用于 nara-catalog-mcp search_records_advanced 的搜索词，以及档案未在线时的订档方式。离线运行。
glo_links	提供指向 BLM General Land Office Records 网站上搜索结果或单条记录的链接，供你打开。离线运行。
cache_status	查看本次会话中的实时调用和缓存命中情况，以及已下载的数据集。离线运行。

设置

你需要 Python 3.11 或更高版本，以及 uv。无需申请密钥。

uvx us-places-mcp

或者从克隆的仓库开始：

git clone https://github.com/ianderso/us-places-mcp
cd us-places-mcp
uv sync
uv run us-places-mcp   # stdio server, usually launched by the client

Claude Desktop

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

如果服务因找不到 uvx 而无法启动，请将 which uvx 输出的完整路径填入 command。

Claude Code

claude mcp add places -- uvx us-places-mcp

配置

无需任何配置。服务器启动目录中的 .env 文件可提供环境中缺少的内容；服务器只会读取该目录。

变量	含义
US_PLACES_OVERPASS_URL	OpenHistoricalMap 的 Overpass 端点。默认值为 https://overpass-api.openhistoricalmap.org/api/interpreter。
US_PLACES_PLSS_URL	BLM 的全国 PLSS 地图服务。默认值为 https://gis.blm.gov/arcgis/rest/services/Cadastral/BLM_Natl_PLSS_CadNSDI/MapServer。
US_PLACES_GNIS_URL	USGS 的 GNIS 地图服务。默认值为 https://carto.nationalmap.gov/arcgis/rest/services/geonames/MapServer。
US_PLACES_GNIS_ARCHIVE_URL	2021 年 8 月的 GNIS 州级文件目录。默认值为 https://prd-tnm.s3.amazonaws.com/StagedProducts/GeographicNames/Archive/MainDomestic。
US_PLACES_TNM_URL	The National Map 的 TNM Access 产品 API。默认值为 https://tnmaccess.nationalmap.gov/api/v1/products。
US_PLACES_DATAVERSE_URL	存放邮局数据集的 Harvard Dataverse。默认值为 https://dataverse.harvard.edu。
US_PLACES_CACHE_DIR	响应缓存目录；下载的数据集存放在其 data 文件夹中。默认值为 ~/.cache/us-places-mcp。
US_PLACES_TIMEOUT	HTTP 超时时间（秒）。默认值为 60。
US_PLACES_CONTACT	添加到 User-Agent 中的电子邮件地址或 URL，以便服务方联系你。可选，提供该信息也很周到。

所有 URL 都必须使用 https。服务器只会联系这些 URL 的主机，以及 Dataverse 的文件存储服务（dvn-cloud-iqss.s3.amazonaws.com，下载请求会重定向至此）。

友好使用服务

OpenHistoricalMap 的 Overpass 服务由捐赠的算力运行，且未公布速率限制。服务器会依次向每项服务发送请求；请求间隔为：OpenHistoricalMap 2 秒、BLM 半秒、USGS 和 Dataverse 1 秒。它会合并正在进行的相同调用，并将结果缓存到磁盘：县级结果缓存 90 天，GNIS 和地图结果缓存 30 天，测量结果则缓存到你传入 refresh=true 为止。遇到 429 或 5xx 错误时，服务器会采用退避策略重试 3 次，之后报告 rate_limited 或 upstream_error，这绝不等同于“此处没有任何内容”。

已下载的数据

有两个数据源以文件而非服务的形式提供，因此服务器会下载一次并在本地读取。只有工具需要时才会下载；触发下载的结果会说明下载内容、大小、校验方式和保存位置。

数据	时机	大小	校验方式
美国邮局（Blevins 和 Helbock，doi:10.7910/DVN/NUKCNA，CC0）	首次调用 post_offices 时	下载 31 MB，磁盘占用 21 MB	Dataverse 公布的文件 MD5 值
2021 年 8 月 25 日的 GNIS 州级文件（USGS，公有领域）	首次搜索该州的 find_place_name 时	每个州最多 17 MB（宾夕法尼亚州为 9.8 MB）；只保留已删除的类别，宾夕法尼亚州约为 6 MB	USGS 存储桶报告的 ETag（MD5 值，或上传分块的 MD5 值）

两者都以 SQLite 文件形式存储在缓存目录下的 data 文件夹中（默认路径为 ~/.cache/us-places-mcp/data），绝不会存放在代码库中。校验失败的文件会被删除，工具会报告 download_failed。cache_status 会列出已有内容；删除该文件夹即可重新开始。

如何解读返回结果

• 当时的县，而非现在的县。 记录由当日管辖该地点的县保存。新县不会接收其母县较早的记录，因此 Greene County 成立之前的契据仍保存在 Washington County 的档案中。
• 临近变更日期时请核查。 boundary_change_within_a_year 会列出日期附近的变更。法律会在规定日期生效，但办公室需要时间筹备；这些月份的记录可能保存在任一县。
• “隶属于”。 某地区尚未建制为县时，通常会在行政上隶属于邻县，记录也由该邻县保存。county_at 会从地图集的事件文本中读取这一信息。
• 有争议的土地。 1770 年代，宾夕法尼亚州和弗吉尼亚州都管辖 Waynesburg 一带，其他地方也发生过类似争议。"status": "contested" 表示应查阅双方政府的记录。
• 地图集按现今所属州归档县。 Monongalia County 由弗吉尼亚州设立，但归档在西弗吉尼亚州名下；事件文本会注明采取行动的是哪个政府。
• 地图集的数据截至 2000 年，仅包含县：不包括城镇、镇区或作为教会单位的教区。
• 定位到的地块不等于房屋。 一段土地的中心点与其中任意一点最多相距半英里；BLM 的数据是现代汇编，在校正线和水域附近可能与原始地块图不同。分块地段（位于镇区北部和西部边缘，或沿水域的地段）包含小块地，而普通地段则包含四分之一地段。
• 解析结果是对已有解读的再次解读。 parse_legal_description 会保留原文，并说明它的推测内容：例如，没有“Sec.”的地段编号，或根据州推定的子午线。
• 专利契据证明的是一次产权转让，日期以签署日为准。 记录日期可能早几年：移居者会在最终确认前先在土地上生活五年，而 19 世纪中叶的积压可能导致购买与签署之间相隔多年。《宅地法》于 1863 年生效，因此家族故事中所谓的“1856 年宅地”实际上可能是现金购买、赊购、优先购买权或土地认领权记录。
• 专利契据的受让人可能从未见过那块土地。 军事赠地认领权证会被买卖；退伍军人的名字在认领权证档案中，专利契据的受让人则可能是投机者。
• 实行州有土地制度的州没有联邦专利契据。 十三个殖民地、缅因州、佛蒙特州、肯塔基州、田纳西州、西弗吉尼亚州、德克萨斯州和夏威夷州都自行授予土地。在这些地方搜索结果为空毫无意义；public_land_state 会说明最初产权记录在哪个州。
• 旧版 GLO 链接已失效。 BLM 于 2026 年 7 月重建了 glorecords.blm.gov，旧记录链接现在会跳转到主页。引用专利契据时，请注明其编号、文件编号、州和签署日期。
• GNIS 名称是现今的官方名称， 并非旧记录中的拼写。GNIS 会将 Mount、Fort 和 Saint 写全，并省略所有格撇号（Pikes Peak）；服务端也会对你输入的名称进行同样处理。已消失的地点通常会列为“名称（历史）”。GNIS 中的县是现今的县：请将地点传给 county_at。
• 2021 年档案是冻结的。 墓地、教堂、学校、邮局和建筑的记录，反映的是 GNIS 截至 2021 年 8 月 25 日的数据；USGS 已不再维护这些数据。topo_quad 会标明每项记录所依据的 1:24,000 比例尺地图。
• 地图日期是测绘或修订日期， 并非你关心的那一天实地情况的日期；再版地图仍沿用旧日期。同一四边形区域和日期往往对应多个扫描件：它们可能是同一版图的较晚印次或其他副本。请进行对比。比例尺为 1:62,500 或更大的地图会标出道路、教堂、学校和墓地，通常也会标出房屋；房屋符号不会注明住户姓名。
• 邮局的运营年份以 Helbock 的记录为准。 更名或改为分支机构会结束一条记录，并可能开始另一条记录，因此“停办”可能表示更名。邮局关闭时间不足十年时，会保留为一条记录，并标记 continuous: false。镇内迁址不作记录。
• 邮局所属的县是现今的县。 Helbock 列出的是邮局现址所在的县。如需查询当时保存记录的县，请将邮局的地点和年份传给 county_at。
• 三分之一的邮局没有地点坐标。 Blevins 通过将邮局名称与 GNIS 地物匹配来确定其位置；未能匹配的邮局没有坐标，因此按某个地点搜索时会遗漏它们。也请按县搜索。gnis_match 会显示每个邮局匹配到的对象及匹配程度。
• 邮政局长姓名 可在美国国家档案馆的《邮政局长任命记录》中查到（1789-1832 年为缩微胶卷 M1131，1832-1971 年为 M841）。

刻意不包含的功能

• 搜索 GLO 本身。 重建后的网站没有公开 API。服务会为你生成链接供你打开；它不会抓取该网站。
• 将乡镇和教区作为管辖区。 地图集仅包含县；GNIS 会列出地点名称，但不会说明由谁管辖。
• 在任何地方写入数据。

安全

• 固定的主机集合。 请求钩子会拒绝发往非已配置服务或 Dataverse 文件存储的任何请求，因此模型传入的值无法让服务抓取其他网站。下载内容仅会重定向到这些主机之一。
• 下载内容在保留前都会经过校验， 与发布者声明的校验和进行比对，并且有大小上限。
• 输入会在用于查询前经过验证： 坐标必须是范围内的有限数值，州和 GNIS 类别须与表格匹配，测量编号必须为数字，县名会逐字符转义后放入 Overpass 查询。地名只会作为 find 的搜索文本传给 GNIS，不会出现在 where 子句中；本地搜索使用绑定参数。
• 事件、法规和地名文本都是数据。 这些文本来自数据源，并原样传递给模型；服务的指令会告知模型应将其视为数据，而非指令。

如需报告漏洞，请参阅 SECURITY.md。

开发

uv sync --extra dev
uv run pytest                      # mocked with respx; never touches a service
uv run ruff check .
uv run ruff format --check .
uv run python -m tests.live_check  # a few paced calls to every live service

请参阅 CONTRIBUTING.md、docs/API-NOTES.md，了解对各项服务的观察结果及观察时间；并参阅 docs/DESIGN.md，了解服务采用这种设计的原因。

致谢

县界：Newberry Library 的 Atlas of Historical County Boundaries（编辑：John H. Long），导入至 OpenHistoricalMap，并以 CC0 协议发布。 测量数据：美国土地管理局的 National PLSS（CadNSDI），属于美国政府作品。地名：美国地质调查局的 Geographic Names Information System，属于美国政府作品。地图：通过 The National Map 获取的 USGS Historical Topographic Map Collection。邮局：Cameron Blevins 和 Richard W. Helbock，US Post Offices，Harvard Dataverse，doi:10.7910/DVN/NUKCNA，以 CC0 协议发布。

许可证

MIT。