概览

美国人口调查局人口,经济和住房数据. 查找数据集和变量,为 FIPS 代码解析地名或地址,以及查询或排列任何一组地理学的估计数.

工具

能力参考

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(中文(简体) )
• 数据集不公布的代码会收到一个通知,命名持有它的兄弟姐妹数据集(SS1701 内 acs/acs5 指点 acs/acs5/subject)或(或) census_get_variable 用于属性列,例如 B19013_001EA
• 在ACS数据集上,估计(E后缀)和误差(M后缀)代码重合;比较剖面和其他家族发布无差错. 还按关键词找到上游代码(naics)或代码(NAICS2017 内 cbp(中文(简体) )
• limit 是一个从 1 到 100 的整数( 默认 20 ), 在超出范围时被拒绝而不是被夹住. offset 页面完整匹配命令 ; totalMatches 在呼叫前计数匹配, truncated 表示另一个页面存在,并且 nextOffset 说吧 变量.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 当代码没有定义时, 命名在找到时公布代码的兄弟姐妹数据集 (DP03_0062E 内 acs/acs5 指点 acs/acs5/profile(中文(简体) )

census_list_predicate_values _工具

• 列出一个过滤维度接受的代码,在发布列表时从数据集词典中读取,并以其他方式列出. NAICS* 财务报告和审定财务报表 POPGROUP 清单很长(千个代码 query(三); EMPSZES, (中文(简体) ), LFO, (中文(简体) ), RCPSZES, (中文(简体) ), TAXSTAT,以及 TYPOP 仅限直播
• 对照数据集实际公布的行来检查词典清单并删除未公布的代码; source 说明检查结果和通知是否给出了被扣的号码。 字典列表无法在提供的地理级别验证出版物
• 活计数 geography_level (默认) us并呼应这一范围。 代码因级别而异;仅接受其数据集元数据允许未显示通配符的级别
• query 匹配代码和标签;结果在代码之前排序 offset编号 :limit 拨号( n)limit 1至500,默认为50). totalCount 计数所有匹配; truncated 表示另一个页面存在,与 nextOffset 只有那时 打开 ecnbasic, (中文(简体) ), within_naics 范围 TAXSTAT 财务报告和审定财务报表 TYPOP 对一个行业
• 直播路线和字典检查读取了数据端点,所以需要 CENSUS_API_KEY: 没有工作键, 仅靠活的维度会失败 missing_api_key,而字典列表仍然回答,但不加限制,并附有指定密钥的通知

census_resolve_geography _工具

• 命名地点(如"金县,WA")通过TIGERweb解决;街道地址通过Census Geocoder解决到道位 block_group_fips 财务报告和审定财务报表 place_fips5位数的 ZIP (或 ZIP+4) 解决其 ZIP 代码制表区(zip code tabulation area(中文(简体) )
• 自动检测 geography_type 为州,县,地点,道,和ZIP. 都市/微城市统计区、综合统计区、合并城市和经济地点需要明确 geography_type· ; economic place 返回八位数 ecnbasic 代码( 西雅图) 03363000(中文(简体) )
• 地点级别包括人口普查指定地点,只有在没有并入地点或县级完全匹配时才回答姓名;使用全名("Arlington CDP, VA")或 geography_type: "place" 达到一个。 可选 county_fips 范围 县和道分辨率county_scope_unsupported 用于任何其他级别或地址)
• 匹配忽略了大小写,接受州名缩写或全名,并容忍圣/圣和口音差异. 纽约市辖区决定所属县("纽约布鲁克林") – 金斯县 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 gEOID 顺序中的行( 默认为 50, 最大为 500), 有 offset 用于呼叫和 totalCount 用于所有匹配. truncated 只有在另一页存在时才属实; nextOffset 该页的名称
• 以逗号分隔的列表( N)"06,53",或 "033,061" 与 parent_fips: "53")返回按GEOID顺序排列的每列同级编码,并按同一方式进行页面;代码取该等宽度, 不 "*" 成员 父母需要一个代码 通知名称 每一个列出的代码 无一行回来
• 每个呼叫最多49个可变代码,增加标签或记录列的数据集较少(too_many_variables 说明最大值)。 未知代码失败 variable_not_found; 级别和父问题失败 parent_required 或者说 parent_not_accepted可选 tract_fips (6位数字,带混凝土) county_fips将块组或十年一次的块查询瞄准一个道
• 可选 predicates 映射过滤业务, pep,以及 dec 数据集和 acs/acs1/spp (例如, {"NAICS2017": "5112"}) (中文(简体) ). 未设定维度默认为人口普查默认值,每行对应 applied_filters· ; "*" 返回每个类别一行,标签在 record。 。 。 . pep/charv 返回每个地理的数行,所以为 1 (例如, {"MONTH": "7"}(中文(简体) )
• ACS sentinel 值解决其已发布的含义,并标出一个无限制间隔的中位数 open_ended打开 cbp, (中文(简体) ), ecnbasic,以及 nonemp,被扣值报告为与国旗含义相符合的压制值。 无效 estimate 表示被压制的文本单元格(返回到 value),或为空
• 打开 dec/ddhca 财务报告和审定财务报表 dec/ddhcb,一个地理的 POPGROUP 团体只坐在一个家庭的一桌;a no_data 提示或通知列表名称。 要求数 CENSUS_API_KEY
• 缺少地理指导名称 适用的ACS 出版阈值 可能的原因与代码检查, 和配对的更广泛的覆盖数据集 与可变再发现

census_compare_geographies _工具

• 在一个级别或一个名称上排列所有地理 geographies (一) GEOID/平面编码清单; within编号 :within_county 国家/县的范围,省略以作全国比较
• 在一个变量上的排名: sort_by (默认第一个代码;必须是请求的代码,否则 sort_by_not_requested, (中文(简体) ), sort_dir (默认) desc),以及 limit (1至500,默认为50). 平等数值 共享竞争排名1, 2, 2, 4)和由GEOID订购;通知在平局内识别出一页边界. 按大小、而不是比率排列的计数等级,按一个比率排列公布的百分比(S1701_C03_001E 内 acs/acs5/subject, (中文(简体) ), DP04_0047PE 内 acs/acs5/profile(中文(简体) )
• offset 在排序的匹配集中计数行;在呼出前会分配分行. totalCount 计数设置, truncated 表示另一个页面存在,并且 nextOffset 仅出现在当时。 无空 geographies 过滤器也返回 scope_rank 与所有获取的地理学和 scopeCount 该分母
• 取同样的 predicates,变量限制、验证和 applied_filters 作为 census_query_data; 多记录数据集 (pep/charv或一个 "*" 上游失败 ambiguous_rows 除非 predicates 针一. 被被压制的值以同样的原因排序为最后,文本值不能排序(通知中说). 要求数 CENSUS_API_KEY

特征

建造在 @cyanheads/mcp-ts-core: stdio和可流式的 HTTP 传输器,可插接式(none 编号 : jwt 编号 : oauth),可互换存储(in-memory, (中文(简体) ), filesystem, (中文(简体) ), Supabase, (中文(简体) ), Cloudflare KV/R2/D1),结构化记录,可选择的OpenTeleometry tracking.

特定普查:

• 含有可配置 TTL 的流程中可变缓存 — variable.json 在每个数据集+年份获取一次,搜索客户端
• 3-API后端:用于数据查询的人口普查数据API,用于命名地点解析的TIGERweb,用于地址到字节的人口普查地理编码器
• 在所有外部 API 呼叫中自动重试并备份
• 关键工具呼叫共享50秒上游预算,涵盖元数据、数据、复读和可选调查;数据请求在剩余预算内保留40秒上限
• FIPS 格式化帮助器 — 零加法状态、 县和道码, 可以在工具之间传递

方便代理输出 :

• 面向工作流程的工具表面—— fips_summary 财务报告和审定财务报表 state_fips 返回值已准备通过 geography_fips 财务报告和审定财务报表 parent_fips 到下一个工具
• 已解码的禁止编码——人口普查的负哨值(例如:, -666666666)和商务数据集预留旗(例如, D)表面显示为已公布的含义,而不是原始数字或假零
• 关于错误的恢复提示——模糊的地理名称包括候选名单;缺失的API关键错误包括注册 URL

开始

连接到主机实例, 没有安装 :

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

或者在当地运行它:

claude mcp add census-mcp-server -e CENSUS_API_KEY=your-key -- npx -y @cyanheads/census-mcp-server

对于其他客户端,请将此添加到 MCP 配置文件中 :

{
  "mcpServers": {
    "census-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/census-mcp-server"],
      "env": { "CENSUS_API_KEY": "your-key" }
    }
  }
}

注册自由密钥到 api.census.gov/data/key signup.html 页面存档备份,存于互联网档案馆数据查询census_query_data, (中文(简体) ), census_compare_geographies) 要求,正如 census_list_predicate_values 它所列举的维度是活的;可变搜索和地理解析工作是没有活的。 对于 Docker 或源构建,请参见 运行服务器。 。 。 .

配置

见 .env.example 用于完整可选覆盖列表.

运行服务器

地方发展

要求数 Bun v1.4.0 (英语) 或更高(或Node.js v24+).

• 克隆并安装 :

  git clone https://github.com/cyanheads/census-mcp-server.git
  cd census-mcp-server && bun install
  cp .env.example .env   # set CENSUS_API_KEY
  

• 构建和运行 :

  # 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 run --rm -e CENSUS_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/census-mcp-server:latest

图像默认为 HTTP 传输、 无国籍会话模式和日志到 /var/log/census-mcp-server运行到一个 MCP 客户端的 stdio,使用 "command": "docker" 与 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "CENSUS_API_KEY=your-key", "ghcr.io/cyanheads/census-mcp-server:latest"]为了在当地建设, docker build -t census-mcp-server .; OpenTeleometry 端点依赖性默认安装——用 --build-arg OTEL_ENABLED=false 以略去它们.

项目结构

发展指南

见 CLAUDE.md 发展准则和建筑规则。 简本:

• 搬运工投掷,框架渔获量——否 try/catch 在工具逻辑中
• 使用 ctx.log 请求范围伐木, ctx.state 租户范围储存
• 通过枪管登记新工具 src/mcp-server/tools/definitions/index.ts
• 环绕外部 API 调用: 验证 生 → 规范到域类型 → 返回输出计划; 永远不要编织缺失的字段

捐款

问题值得欢迎。 提交前进行检查和测试:

bun run devcheck
bun run test

许可证

阿帕奇-2.0 — 见 自由主义 详细情况.