Census (ACS by ZIP)

Name: Census (ACS by ZIP)
Author: mcpwright

本地服务

github.com/mcpwright法律与政务010 周前更新

代码仓库

关于 Census (ACS by ZIP)

Census (ACS by ZIP) 是只读 MCP 服务，可按 ZIP Code 查询美国人口普查局 ACS 估算数据。数据批量下载到本地存储，因此完成初始化后可离线查询。

主要功能

01查询收入、人口、住房和教育数据
02按指标比较多个 ZIP Code
03读取已存储的 ACS 变量
04查找位于指定地点的 ZIP Code

适用场景

01比较不同 ZIP Code 的收入
02查看某地区住房或教育估算数据
03查找与某城市或城镇对应的 ZIP Code

MCP 相关

向 MCP 客户端提供 8 种只读人口普查数据工具。ACS 数据一次性下载到本地存储，之后的查询可离线运行。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "mcpwright-census": {
      "command": "uvx",
      "args": [
        "mcpwright-census"
      ],
      "env": {
        "CENSUS_API_KEY": "<CENSUS_API_KEY>"
      }
    }
  }
}

启动命令uvx mcpwright-census

需要配置的环境变量

CENSUS_API_KEY密钥Free Census API key (get one at https://api.census.gov/data/key_signup.html). Required for the one-time bulk download of the ACS dataset.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypimcpwright-census0.1.3stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
zip_code	string	是

详细介绍

census-mcp

**在你的 Agent 中查询美国人口普查局的邮政编码数据。**这是一个 MCP 服务，可让大模型查询任意邮政编码的收入、人口统计、住房和教育数据，基于 Anthropic 官方的 mcp Python SDK。

所有工具均为只读。数据来自美国人口普查局美国社区调查（ACS）5 年期数据——一次性批量下载到本地存储，然后离线提供。首次下载需要免费的 Census API 密钥。

状态：已发布（v0.1.2）——可通过 uvx mcpwright-census（PyPI）运行，并已列入官方 MCP Registry，名称为 io.github.mcpwright/census-mcp。以下 8 个工具均已上线并通过单元测试，且已对照实时 ACS 5 年期数据完成端到端验证（撰写本文时为 2024 版——服务会自动检测最新版本）。属于 mcpwright 套件的一部分。

工具

工具	功能
`lookup_zip(zip_code)`	确认邮政编码是否对应 Census ZCTA；返回名称、总人口和 ACS 版本。
`get_income(zip_code)`	家庭收入中位数、人均收入、家庭总数，以及收入达到 $200k 及以上的家庭占比。
`get_demographics(zip_code)`	总人口和年龄中位数。
`get_housing(zip_code)`	房屋价值中位数、总租金中位数、已入住住宅单元数，以及自有住房占比。
`get_education(zip_code)`	在 25 岁及以上成年人中，拥有学士及以上学位的比例，以及拥有研究生或专业学位的比例。
`compare_zips(zips, metric)`	按一项指标（收入、年龄、房屋价值、学历等）对多个邮政编码排序，最高者排在前面。
`get_acs_variable(zip_code, variable)`	后备工具：按代码或易读名称获取任意已存储 ACS 变量的原始值。
`find_zips(place, state=None)`	反向查询：查找位于某个城市、城镇或 CDP 内的邮政编码，并按各邮政编码落在该地区内的土地面积占比排序。

邮政编码 ≈ ZCTA（邮政编码制图区）：两者大多一致，但约 2% 的邮政编码（仅邮政信箱／非住宅区域）没有对应的 ZCTA，因此会返回错误。所有 ACS 数值均为 5 年期估算值。

find_zips 提供反向查询（地区 → 邮政编码）。结果是近似值：ZCTA 并不完全位于地区范围内，因此一个邮政编码可能跨越多个地区，反之亦然——请查看每个匹配项的 coverage_pct，并传入 state 以区分同名地区（例如，MA 州与 OH 州的 Cambridge）。此功能基于公开的 2020 Census ZCTA-to-Place 关系文件（2020 年地理数据；无需 API 密钥）。

安装

需要 Python 3.12+ 和免费的 Census API 密钥（设置 CENSUS_API_KEY）。PyPI 包名为 mcpwright-census；命令、服务和工具均称为 “census”。

export CENSUS_API_KEY=your-free-key
uvx mcpwright-census setup     # one-time: bulk-download the ACS dataset into a local store

Claude Code

claude mcp add census -e CENSUS_API_KEY=your-free-key -- uvx mcpwright-census

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "census": {
      "command": "uvx",
      "args": ["mcpwright-census"],
      "env": { "CENSUS_API_KEY": "your-free-key" }
    }
  }
}

首次运行会将完整的 ACS 数据集（约 33k 个 ZCTA）下载到操作系统缓存目录下的本地 SQLite 存储中，因此之后的每次查询都能即时完成且无需联网。可提前运行 mcpwright-census setup，也可以让服务在首次使用时按需下载。发布新的 ACS 版本后，运行 mcpwright-census refresh 重新获取数据。使用 CENSUS_MCP_STORE 更改存储位置。

开发

git clone https://github.com/mcpwright/census-mcp && cd census-mcp
uv sync
uv run pytest -v                                     # tests (mocked Census + seeded SQLite)
uv run ruff check src/ && uv run ruff format --check src/   # lint + format
uv run mypy                                          # type checking
uv run mcp dev src/census_mcp/server.py              # poke the tools in the MCP Inspector

路线图

隐私

census-mcp 完全在你的计算机上运行，不会收集、存储或传输任何个人数据——不需要账户、不跟踪、不收集遥测数据。它唯一的外发请求会发送至公开的美国人口普查局，用于下载公开数据：访问 api.census.gov 获取 ACS 数据集（使用你自己的 CENSUS_API_KEY），以及访问 www2.census.gov 获取 find_zips 所用的地点查找文件（无需密钥）。密钥从你的环境中读取，绝不会记录日志或发送到其他地方。这些下载操作会在 setup/refresh 期间执行（或在首次使用时延迟执行）；之后，查询都通过本地存储提供服务，不会再进行网络调用。下载的数据存放在操作系统缓存目录中（仅包含公开参考数据），你可以随时删除。