census-mcp-server

---

概述

美国人口普查局的人口、经济和住房数据。查找数据集和变量，将地名或地址解析为 FIPS 代码，并查询或排列任意一组地理区域的估算值。

工具

工具	描述
census_list_datasets	浏览可用的 Census Bureau 数据集（ACS5 和 ACS1 及其概况表、主题表和比较表、ACS 补充估算和选定人口概况、人口估算、十年一次人口普查、县级商业模式、经济普查、非雇主统计），以及其版本年份和数据集代码。
census_list_geographies	列出数据集和年份支持的地理级别、所需的上级地理级别以及 FIPS 示例值。
census_search_variables	按关键词搜索变量标签和概念组，或按变量代码或表格代码查找。在 ACS 中，会同时返回估算值和误差范围代码。
census_get_variable	获取一个或多个变量代码的完整元数据——标签、概念、谓词类型、总体范围、对应的 MOE 变量——包括数据工具接受的注释列和标记列。
census_list_predicate_values	列出筛选维度接受的代码（EMPSZES、LFO、POPGROUP、NAICS2017…），来源为数据集字典或实时通配符枚举。
census_resolve_geography	通过 TIGERweb 和 Census Geocoder，将地点名称（例如“King County, WA”）、邮政编码或街道地址转换为 Census FIPS 标识符。
census_query_data	查询特定地理位置的 Census 数据集变量。返回带有 MOE 的估算值、已转换为其公布含义的 Census 哨兵值和被抑制的商业数据值，以及用于商业数据集的谓词筛选。
census_compare_geographies	对多个地理位置的变量进行排序和比较——例如一个州内的所有县、全国所有州，或指定的一组地理位置。输出排序后的表格，并支持相同的谓词筛选。

---

功能参考

census_list_datasets _工具

• 返回数据集代码、名称、描述和可用版本年份，并支持可选的关键词筛选。涵盖 ACS5 和 ACS1（数据概况、主题表、比较概况和 acs/acs1/spp）、acs/acsse、人口估算、2020 年十年一次人口普查文件（重新划区（P.L. 94-171）、dec/dhc、dec/dp、dec/sdhc、dec/ddhca、dec/ddhcb）、cbp、ecnbasic 和 nonemp
• 每条描述都会列出数据集所需的筛选谓词，以及该数据集发布数据时采用的地理级别
• 数据集代码（例如 acs/acs5）是其他工具使用的代码。不区分大小写；两段式代码可仅使用最后一段（acs5、pl）；三段式代码（例如 acs/acs5/profile）必须完整提供
• available_years 列出了所有可用年份：使用其他年份会报错 year_not_available，并列出可用年份

---

census_list_geographies _工具

• 每个地理级别及其上级层级各返回一行：geography_level、是否需要上级地理级别、required_parent_levels 和 FIPS 示例值。totalLevels 统计各级别的数量，每个级别只计一次
• geography_level 的值是 census_query_data 和 census_compare_geographies 的准确输入；year 默认为最新版本年份
• 出错时返回 dataset_not_found 或 year_not_available（并列出可用年份）

---

census_search_variables _工具

• 在标签和概念中进行全词搜索：查询中的每个词都必须匹配，否则会返回最接近的匹配项并附上提示。变量或表代码不区分大小写，匹配时会优先返回该变量，或按代码顺序返回整张表（B19013 会先返回 B19013_001E，再返回 B19013_001M）
• 如果数据集未发布某个代码，会附上提示，指出包含该代码的关联数据集（acs/acs5 中的 S1701 会指向 acs/acs5/subject）；对于 B19013_001EA 这类属性列，则提示使用 census_get_variable
• 对于 ACS 数据集，估算值（E 后缀）和误差范围（M 后缀）代码会一起返回；比较概况和其他类别不发布误差范围。也可通过关键词（naics）或代码（cbp 中的 NAICS2017）查找谓词代码
• limit 是介于 1 到 100 之间的整数（默认为 20）；超出范围时会拒绝请求，而不是将其限制在范围内；totalMatches 统计限制前的匹配数。每个数据集和年份对应的 variables.json 会被缓存（默认 TTL 为 24h）

---

census_get_variable _工具

• 接受一个或多个变量代码（不区分大小写），并按给定顺序返回标签、概念、谓词类型和表的总体范围。如果无法获取 groups.json，则返回的变量不包含总体范围，并附上提示，建议重试
• 可解析 B19013_001EA 和 EMP_F 等注释列及标志列；attribute_of 会标明其所属列，attribute_type 会标明其类型（ANNOTATION、FLAG、MARGIN_OF_ERROR）。对于 ACS 数据集，还会返回 estimate_code/moe_code 关联代码
• 确认谓词维度代码（NAICS2017、SEX）是否存在于数据集中；census_list_predicate_values 会列出其取值。dataset 默认为 acs/acs5，year 默认为最新年份
• 如果某个代码未定义，则返回 variable_not_found；若找到发布该代码的关联数据集，会指出该数据集（acs/acs5 中的 DP03_0062E 会指向 acs/acs5/profile）

---

census_list_predicate_values _工具

• 列出筛选维度可接受的代码：若数据集词典中发布了代码列表，则从词典读取；否则实时枚举。NAICS* 和 POPGROUP 的列表很长（包含数千个代码；可使用 query 缩小范围）；EMPSZES、LFO、RCPSZES、TAXSTAT 和 TYPOP 仅支持实时枚举
• 词典中的列表会与数据集实际发布的行进行核对，并剔除未发布的代码；source 会说明是否进行了核对，提示则会给出剔除的数量
• query 会匹配代码和标签；结果按代码排序，并会说明结果是否被截断（limit 是介于 1 到 500 之间的整数，默认为 50；totalCount 统计匹配数）。在 ecnbasic 中，within_naics 可将 TAXSTAT 和 TYPOP 限定为某个行业

census_resolve_geography _工具

• 命名地点（例如“King County, WA”）通过 TIGERweb 解析；街道地址通过 Census Geocoder 解析到普查区级别，并返回 block_group_fips 和 place_fips。5 位 ZIP（或 ZIP+4）会解析为其 ZIP Code Tabulation Area（zip code tabulation area）
• 自动检测州、县、地点、普查区和 ZIP 的 geography_type。大都市／小都市统计区、联合统计区、合并城市和经济地点需要显式指定 geography_type；economic place 会返回 8 位 ecnbasic 代码（西雅图为 03363000）
• 地点级别包括人口普查指定地点；仅当没有完全匹配的建制地点或县时，才会仅凭名称匹配此类地点；使用完整名称（“Arlington CDP, VA”）或 geography_type: "place" 即可找到此类地点。可选的 county_fips 用于限定县和普查区的解析范围（对于其他任何级别或地址，会返回 county_scope_unsupported）
• 匹配时忽略大小写，接受州缩写或全名，并能容忍 Saint/St. 和重音符号的差异。纽约市各行政区会解析为对应的县（“Brooklyn, NY” → Kings County 047），并附带 notice
• 如果某个名称匹配多个地理区域，则返回 ambiguous_name，其中包含每个候选项的 FIPS 代码和州。结果包含 state_fips（→ parent_fips）和 fips_summary（→ geography_fips），供下一个工具使用；统计区和 ZCTA 不包含 state_fips

---

census_query_data _工具

• 需要 FIPS 代码（地点名称请使用 census_resolve_geography）。geography_fips: "*" 会返回父级范围内该级别的所有地理区域；每行包含 geography_fips 和全国唯一的 geography_geoid。通配符查询最多返回 limit 行（默认值为 50，最大值为 500），按 GEOID 排序；可使用 offset 分页，其余结果通过 totalCount 和 truncated 表示
• 每次调用最多接受 49 个变量代码；对于会添加标签或记录列的数据集，可接受的数量更少（too_many_variables 会说明上限）。未知代码会导致 variable_not_found；级别或父级问题会导致 parent_required 或 parent_not_accepted。可选的 tract_fips（6 位，且需提供具体的 county_fips）可将街区组或十年一次人口普查街区查询限定在一个普查区内
• 可选的 predicates 映射可筛选 business、pep 和 dec 数据集，以及 acs/acs1/spp（例如 {"NAICS2017": "5112"}）。未设置的维度采用 Census 默认值，并会在每行的 applied_filters 中回显；"*" 会为每个类别返回一行，并在 record 中标注。pep/charv 会为每个地理区域返回多行，因此请指定一个值（例如 {"MONTH": "7"}）
• ACS 哨兵值会转换为其已发布的含义；开放区间的中位数会标记为 open_ended。在 cbp、ecnbasic 和 nonemp 中，受抑制的值会以 suppressed 状态报告，并附上该标记的含义。estimate 为 null 表示该值已被抑制、属于文本单元格（通过 value 返回）或为空
• 在 dec/ddhca 和 dec/ddhcb 中，某个地理区域的 POPGROUP 组只会出现在同一系列的一个表中；no_data 提示或通知会指出相关的同系列表。需要 CENSUS_API_KEY

---

census_compare_geographies _工具

• 对某个级别的所有地理区域，或命名的 geographies GEOID／不带前缀的级别代码列表进行排名；within／within_county 用于限定州／县范围，进行全国比较时省略
• 根据一个变量排名：sort_by（默认为第一个代码；必须是请求的代码，否则返回 sort_by_not_requested）、sort_dir（默认为 desc）和 limit（1 到 500，默认为 50）；totalCount 统计的是限制条数前的地理区域数量。按计数排名依据的是规模而非比率；如需按比率排名，请使用已发布的百分比（acs/acs5/subject 中的 S1701_C03_001E，或 acs/acs5/profile 中的 DP04_0047PE）
• 接受与 census_query_data 相同的 predicates、变量数量限制、验证规则和 applied_filters；多记录数据集（pep/charv）或 "*" 谓词会返回 ambiguous_rows，除非 predicates 指定了单条记录。受抑制的值会根据相同原因排在最后，并会说明文本值不能用于排名。需要 CENSUS_API_KEY

---

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及带可选 OpenTelemetry 跟踪的结构化日志记录。

Census 专属功能：

• 进程内变量缓存，TTL 可配置 — 每个数据集和年份仅获取一次 variables.json，并在客户端进行搜索
• 三个 API 后端：Census Data API 用于数据查询，TIGERweb 用于命名地点解析，Census Geocoder 用于将地址转换为普查区
• 对所有外部 API 调用自动重试，并使用退避策略
• FIPS 格式化辅助工具 — 州、县和普查区代码均带有前导零，可直接传递给其他工具

便于 Agent 使用的输出：

• 面向工作流的工具界面 — fips_summary 和 state_fips 返回的值可直接作为 geography_fips 和 parent_fips 传递给下一个工具
• 解码抑制代码 — Census 负哨兵值（例如 -666666666）和商业数据集的保留标记（例如 D）会显示其已发布的含义，而非原始数字或错误的零值
• 错误提供恢复提示 — 模糊的地理区域名称会附带候选列表；缺少 API 密钥的错误会附带注册链接

---

开始使用

公共托管实例

公共实例位于 https://census.caseyjhand.com/mcp — 无需安装。它提供 Streamable HTTP；每个客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http census-mcp-server https://census.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "census-mcp-server": {
      "type": "streamableHttp",
      "url": "https://census.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "census-mcp-server": {
      "url": "https://census.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在“设置” → “连接器”下添加远程服务。

自托管／本地运行

API 密钥： 在 api.census.gov/data/key_signup.html 注册即可免费获取密钥。变量搜索和地理区域解析无需密钥；数据查询（census_query_data、census_compare_geographies）则需要密钥。

将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "census-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/census-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CENSUS_API_KEY": "your-census-api-key"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "census-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/census-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CENSUS_API_KEY": "your-census-api-key"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "census-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "CENSUS_API_KEY=your-census-api-key",
        "ghcr.io/cyanheads/census-mcp-server:latest"
      ]
    }
  }
}

使用 Streamable HTTP 时，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CENSUS_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• Census API 密钥 — 在 api.census.gov/data/key_signup.html 免费注册。census_query_data 和 census_compare_geographies 需要密钥；其他工具无需密钥即可使用。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/census-mcp-server.git

2. 进入目录：

cd census-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set CENSUS_API_KEY

---

配置

变量	描述	默认值
CENSUS_API_KEY	数据查询必需。 在 api.census.gov/data/key_signup.html 免费注册。	—
CENSUS_DEFAULT_YEAR	未指定年份时使用的默认数据年份。	2024
CENSUS_VARIABLE_CACHE_TTL_HOURS	在内存中按数据集和年份缓存 variables.json 的小时数。	24
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_SESSION_MODE	HTTP 会话模式：stateful、stateless 或 auto。	stateless
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）。	info
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果；按键名脱敏，并限制为 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES 指定的大小（默认 16384）。自由格式值中的机密不会被脱敏。	false
OTEL_ENABLED	启用 OpenTelemetry 插桩。	false

请参阅 .env.example，了解完整的可选覆盖项列表。

---

运行服务

本地开发

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

运行检查和测试：

bun run devcheck   # Lint, format, typecheck, security audit
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t census-mcp-server .
docker run --rm -e CENSUS_API_KEY=your-key -p 3010:3010 census-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/census-mcp-server。默认会安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

---

项目结构

路径	用途
src/index.ts	createApp() 入口点——注册工具并初始化服务。
src/config/server-config.ts	使用 Zod 解析和验证 Census 专用环境变量。
src/mcp-server/tools/definitions/	工具定义（*.tool.ts）。
src/services/census-api/	Census Data API 客户端——数据查询、抑制代码映射和重试逻辑。
src/services/geography/	地理位置解析——TIGERweb 命名地点查询和 Census Geocoder 地址到普查区块组的转换。
src/services/variable-cache/	进程内 variables.json 缓存，支持 TTL 和关键词搜索。
tests/	与 src/ 结构对应的 Vitest 测试。

---

开发指南

请参阅 CLAUDE.md，了解开发指南和架构规则。简要来说：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求级日志记录，使用 ctx.state 进行租户级存储
• 通过 src/mcp-server/tools/definitions/index.ts 中的汇总文件注册新工具
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache-2.0——详情请参阅 LICENSE。