Open Census MCP Server

免责声明 <a name="免责声明"></a>

这是一个独立的开源实验。
它不与美国人口普查局或商务部有任何关联、认可或赞助关系。

通过本项目获取的数据仍然受原始数据提供者条款的约束（例如，Census API服务条款）。

稳定性

容器构建2.0相当稳定，但结果质量方面仍存在问题。

随身携带的人口普查数据专家 📱

将任何AI助手变成你的个人人口普查数据专家。用简单的英语提问，获得准确的人口统计数据，并附带适当的解释和上下文。

之前： "我需要FIPS代码24510的ACS表B19013以及误差计算..."
之后： "巴尔的摩的中位收入与马里兰州相比如何？"

🚀 快速开始 - 即刻可用！

选项1：预构建容器（推荐）

# 运行人口普查MCP服务器（一个命令 - 包含一切！）
docker run -e CENSUS_API_KEY=your_key ghcr.io/brockwebb/census-mcp-server:latest

# 或者不使用API密钥（仍然有效，只是速率限制较慢）
docker run ghcr.io/brockwebb/census-mcp-server:latest

Claude桌面配置

添加到你的claude_desktop_config.json：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "census-mcp": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "CENSUS_API_KEY=your_census_key", "ghcr.io/brockwebb/census-mcp-server:latest"]
    }
  }
}

就这样！ 重启Claude桌面，你会看到一个🔨锤子图标，表示人口普查工具已就绪。

获取人口普查API密钥（可选但推荐）

1. 访问：https://api.census.gov/data/key_signup.html
2. 注册免费API密钥（提高速率限制）
3. 添加到你的Docker命令或Claude桌面配置中

尝试一下

向Claude提问如下问题：

• "德克萨斯州奥斯汀的人口是多少？"
• "比较加利福尼亚州和德克萨斯州的中位收入"
• "农村县的贫困率是多少？"
• "各州教师薪资差异如何？"（它会正确引导你到BLS数据！）

存在的问题

美国人口普查数据极其有价值，但对于非专业人士来说学习曲线非常陡峭。即使是经验丰富的研究人员也难以应对地理层次、变量命名约定、误差计算以及哪些数据组合实际上可行等问题。根据我们的经验，进行人口统计分析的最大障碍往往是首先弄清楚如何获取正确的数据。

愿景：普及美国的数据

今天： 人口普查数据影响数十亿美元的政府支出和政策决策，但有效地访问它需要专门知识，这为许多潜在用户设置了障碍。

机会： 自然语言到人口普查变量代码的语义匹配是真正新颖的，对于目前不得不手动导航数千个晦涩变量名称的研究人员来说，这可能是变革性的。每个人都应该能够通过世界级的AI助手访问高质量的人口普查数据。

明天： 市议会成员在会议期间实时核查事实。记者在撰写故事时获得人口统计背景。非营利组织了解他们的社区而无需聘请统计学家。研究人员花费时间进行分析而不是与API斗争。

目标： 让美国最有价值的公共数据集像提问一样容易使用。

工作原理

graph LR
    A["用户问题：农村县的贫困率？"] --> B["AI助手（Claude，ChatGPT等）"]
    B --> C["人口普查MCP服务器（领域专业知识层）"]
    C --> D["tidycensus R包（地理与变量解析）"]
    C --> H["知识库（R文档+Census方法论）"]
    D --> E["人口普查局API（官方数据源）"]
    H --> C
    E --> D
    D --> C
    C --> F["解释的结果+上下文+注意事项"]
    F --> B
    B --> G["用户得到准确的答案并附有适当解释"]
    
    style C fill:#e1f5fe
    style F fill:#f3e5f5

容器中包含的内容

🏗️ 完整自包含系统：

• 带有tidycensus、dplyr和地理空间库的R环境
• 带有MCP服务器和向量数据库的Python环境
• 预构建的知识库（85MB），包括人口普查方法论和R文档
• 所有依赖项和配置均已准备好

📚 内置智能：

• 语义查询层： 自然语言 → 统计概念（“教师薪资” → BLS指导，“贫困” → 正确的人口普查变量）
• 145+预先映射的人口统计变量，具有模糊匹配和概念扩展
• 向量数据库中的专家知识，来自人口普查方法论、R文档和统计最佳实践
• 智能地理解析（处理“奥斯汀，TX” → 正确的地理代码，主要城市消歧）
• 统计指导（何时使用中位数而非平均数，误差解释，调查限制）
• 幂律优化： 核心变量（<100ms）+全面的tidycensus后备

🔄 无需设置：

• 不需要安装R
• 不需要配置Python环境
• 不需要构建知识库
• 不需要与API斗争

示例用例

• 基本人口统计： “迈阿密-戴德县的人口”
• 比较分析： “底特律和匹兹堡之间的失业率比较”
• 住房统计： “凤凰城有多少租户单位？”
• 地理模式： “东南部农村地区的贫困率”
• 智能路由： 提问关于教师薪资 → 引导你到BLS数据而不是混淆的人口普查类别

架构

该系统由五层组成：

1. AI客户端层： Claude桌面、Cursor或其他兼容MCP的助手
2. MCP服务器（此项目）： 领域专业知识、查询翻译、结果解释
3. 知识库： 向量数据库，包含R文档和人口普查方法论
4. 数据检索： tidycensus R包处理API通信和地理解析
5. 数据源层： 美国人口普查局官方API

每一层都负责其专业功能，创建了一个可以随着AI工具和人口普查数据基础设施的变化而演进的维护系统。

当前范围：美国社区调查重点

现在可行：

• 美国社区调查（ACS）五年估计值
• 人口统计学、经济学、住房、社会特征
• 地理分辨率从国家到地方级别
• 正确的统计解释，包括误差范围

未来扩展： 其他调查、地理可视化、多机构整合

技术细节

基于： AI工具集成的模型上下文协议（MCP）
核心引擎： Kyle Walker的tidycensus R包
知识库： 使用句子转换器的ChromaDB向量数据库
容器： 包含所有依赖项的约4GB Docker镜像
速率限制： 内置节流和缓存策略

开发设置（高级用户）

如果你想要修改或扩展系统：

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

# 从源代码构建（需要R、Python和大量设置）
./build.sh

# 或使用预构建的容器并按需修改
docker run -v $(pwd):/workspace ghcr.io/brockwebb/census-mcp-server:latest

致谢

本项目建立在以下杰出工作的基础上：

• Kyle Walker 和 tidycensus R包 - 处理复杂地理和API细节的黄金标准，我们依赖于此
• Anthropic 的模型上下文协议，使无缝的AI工具集成成为可能
• 美国人口普查局的敬业团队 收集和维护这些重要的公共数据
• MCP社区 建立了使这种集成成为可能的生态系统

特别感谢Kyle Walker，他的tidycensus文档和方法论构成了我们知识库的基础。这个项目基本上是在tidycensus的基础上增加了自然语言智能 - 所有的统计和地理难题都是由tidycensus团队解决的。

贡献

本项目旨在普及公共数据的访问。我们欢迎以下方面的贡献：

• 领域专业知识改进（特别是来自人口普查数据的老手）
• 额外的地理解析和消歧
• 统计方法实施
• 额外的数据源集成
• 文档和示例
• 使用真实案例进行测试

发展路线图

• 第一阶段： ACS五年估计值与自然语言查询翻译
• 第二阶段： 带有预构建知识库的容器化部署
• 第二阶段.5： 语义智能层 - 变量概念映射、统计路由、增强响应
• 第三阶段： 性能优化 - 用于<100ms常见查询的语义索引，增强地理消歧
• 第四阶段： 额外的人口普查调查（经济普查、SIPP、PEP）
• 第五阶段： 多机构数据集成（BLS就业、BEA经济数据）

---

<pre> RPC DCE RDF ↓ ↓ ↓ CORBA DCOM OWL ↓ ↓ ↓ └─→ SOAP ←┘ SPARQL ↓ ↓ REST 知识图谱 ↓ ↓ GraphQL ↓ ↓ ↓ MCP ←─────────────→ LLMs </pre>

"模式永远不会真正消失，它们只是获得了更好的用户体验"