mcp-census

---

title: 🏘️ Mcp Census emoji: 🏘️ colorFrom: yellow colorTo: indigo sdk: gradio sdk_version: 5.34.0 python_version: 3.13 app_file: gradio_app.py pinned: false short_description: 利用美国人口普查局工具的 MCP 服务

mcp-census

一个正在开发中的 MCP 服务，利用美国人口普查局工具实现大模型互操作。

虽然我们建议在本地安装此服务，但也提供了已部署的人口普查 MCP 服务：https://abrezey-mcp-census.hf.space/gradio_api/mcp/sse。向此仓库的 main 分支推送内容将通过 GitHub Actions 触发此资源的重新部署。

此仓库最初是为 Gradio/Hugging Face Agents MCP Hackathon 构建的。

快速开始

目前，我们建议将 mcp-census 与运行强大基础模型（如 Claude Desktop 或 Cursor）的 MCP 客户端配合使用。

远程

要将 Claude Desktop 连接到托管在 Hugging Face 上的 mcp-census 服务（需要 Claude Pro 或更高版本）：

本地

要在 Claude Desktop 中直接本地运行 mcp-census（需要 uv），请修改你的 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-census": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/mcp-census/.env",
        "/path/to/mcp-census",
        "mcp-census"
      ]
    }
  }
}

如果你更愿意运行自己的客户端应用和大模型，请参阅本地 Agent 快速开始。

使用示例

明尼苏达州亨内平县 65 岁及以上人口有多少？

https://github.com/user-attachments/assets/73f53b8a-be57-4bdd-a105-3676f84730de

加利福尼亚州约洛县的种族／族裔构成如何？

https://github.com/user-attachments/assets/23c2c9c9-ce79-4fb1-a393-6cd10bdf1eff

查询美国 2020 年十年一次的人口普查数据，并提供一个 CSV，其中包含纽约州所有县的住房单元数量、总人口和年龄中位数。对于包含县标识符的列，请提供由州和县代码拼接而成的完整 FIPS。

https://github.com/user-attachments/assets/8c9fac39-0beb-4f27-97b2-430cb4b20465

本地 MCP 服务开发

我们建议使用 uv 管理依赖项，但你也可以直接从 pyproject.toml file 安装所需的软件包。

Lint 和格式化由 ruff 和 pre-commit 提供。

uv run pre-commit install

mcp 软件包提供了便捷的开发服务，可通过界面测试函数。

npx @modelcontextprotocol/inspector uv run mcp-census

API 密钥

mcp-census 需要 API 密钥，才能从美国人口普查局服务请求数据。

cp .env.example .env

然后填写你的 API 密钥。

要申请人口普查 API 密钥，请访问 https://api.census.gov/data/key_signup.html。要申请 Hugging Face 令牌，请访问 https://huggingface.co/docs/hub/security-tokens。

MCP 服务不需要 Hugging Face 令牌，但在开发 Agent 时会很有用。

Gradio MCP 服务本地开发

uv run --group gradio-deployment python gradio_app.py

假设没有其他 Gradio 应用正在运行，此操作将在 http://localhost:7860/gradio_api/mcp/sse 提供 MCP 服务。

要更新 Gradio 部署的依赖项：

uv export --group gradio-deployment > requirements.txt

注意：目前你必须移除上述命令生成的 -e .。

本地 Agent 快速开始

目前，要使系统正常工作，你需要启动全部三个应用（MCP 服务、Agent、Phoenix）。

Agent（和 MCP 客户端）

uv run --group agent python agent.py

可观测性

调试 Agent 时，可观测性至关重要。当前，Agent 已配置为向 Phoenix 服务发送日志。

uv run python -m phoenix.server.main serve

此服务未运行时，Agent 将无法工作。

MCP 架构

功能路线图

评估

• 创建基准，用于评估宿主应用对 MCP 服务的利用情况
• 通过单元测试提升 MCP 功能的可靠性

MCP 服务

• 美国人口普查局发布了大量文档。通过 RAG 启用语义检索，应能为 Agent 提供信息，帮助其更好地响应用户查询。
• 尝试使用 MCP「提示词」，更好地引导大模型回答问题
  • 这应包含充分的流程引用
• 尝试使用 MCP「引导」，让问答过程更具互动性和引导性。

MCP 分发

• 通过桌面扩展安装 MCP 服务。