数据共享MCP服务器
这是一个模型上下文协议（MCP）服务器，用于从以下位置获取公共统计数据 数据共享 实例。
Data Commons是一个开放的知识库，提供跨多个公共数据集和统计数据的统一视图。此服务器允许任何启用MCP的代理或客户端查询数据共享知识图。
特性
- 符合MCP标准： 实现模型上下文协议以实现无缝代理集成。
- 数据共享访问： 从基础datacommons.org知识图中获取公共统计数据和数据。
- 自定义实例支持： 可以配置为使用自定义数据共享实例。
- 灵活服务： 通过可流式传输的HTTP和stdio运行。
- 大数据集处理： 大型观察查询的自动分页和流式处理。
- 多种输出模式： 在屏幕显示、自动CSV导出或强制文件输出之间进行选择。
- 多文件导出： 按地点、地点类型、日期或块大小拆分大型导出。
- 数据谱系： CSV导出包括用于数据来源的全面沿袭标头。
- 进度流： 通过STDIO或SSE传输实时进度更新。
快速入门
先决条件
- 您必须有一个数据共享API密钥；创建一个 apikeys.datacommons.org.
- 安装
uv通过遵循 官方安装说明.
配置
在shell中设置以下必需的环境变量：
export DC_API_KEY=启动服务器
以两种模式之一从命令行运行服务器：
流式HTTP
这将使用Streamable HTTP运行服务器。
# Runs on default port 8080
uvx datacommons-mcp serve http [--port
]服务器将在以下时间可用 http://localhost: /mcp.
标准
此传输模式用于本地集成，并在客户端中以编程方式配置（如Gemini CLI设置），以便通过以下方式进行通信 stdio.
uvx datacommons-mcp serve stdio客户
您可以使用任何启用MCP的代理或客户端连接到正在运行的服务器。例如，请参见 数据共享MCP文档 有关连接的指南：
或者查看您首选客户端的文档，了解如何使用上面列出的命令进行配置。
高级配置
服务器选项
HTTP模式选项
uvx datacommons-mcp serve http [OPTIONS]| 选项 | 默认值 | 描述 |
|---|---|---|
--port | 8080 | 运行HTTP服务器的端口 |
--progress-transport | stdio | 传输进度更新(stdio 或 sse) |
--verbose | false | 启用详细进度日志记录 |
--sse-port | 8081 | SSE进程服务器端口（使用SSE传输时） |
--storage-dir | ./datacommons-data | 导出数据文件的目录 |
stdio模式选项
uvx datacommons-mcp serve stdio [OPTIONS]| 选项 | 默认值 | 描述 |
|---|---|---|
--verbose | false | 启用详细进度日志记录 |
--storage-dir | ./datacommons-data | 导出数据文件的目录 |
大数据集处理
服务器通过基于分页的流和行数阈值自动处理大型数据集：
- 自动模式（默认）： 自动检测大型数据集并将其流式传输到CSV文件。文件模式在以下情况下触发：
- API返回多个页面（检测到分页），或者 - 响应超过行阈值（默认值：500行）
- 屏幕模式： 强制筛选所有结果（对于大型数据集请谨慎使用）。
- 文件模式： 强制将所有结果保存到CSV文件，即使是小数据集。
行阈值可防止大型单页响应淹没上下文窗口。通过配置 DC_SCREEN_ROW_THRESHOLD 环境变量。
输出文件保存到可配置的存储目录（默认： ./datacommons-data)带有时间戳的文件名。通过配置存储目录 --storage-dir CLI选项或 DC_STORAGE_DIR 环境变量。
多文件导出
对于非常大的数据集，您可以使用不同的策略将导出拆分为多个文件：
| 策略 | 描述 |
|---|---|
by_place | 每个唯一位置DCID一个文件 |
by_place_type | 每个地方类型（州、县等）一个文件 |
by_date | 每年一个文件 |
by_chunk | 每个文件的固定行数 |
每个多文件导出都包含一个描述所有导出文件的清单JSON文件。
数据行标题
CSV导出包括全面的沿袭标头作为每个文件顶部的注释：
# ============================================================
# Data Commons MCP Server Export
# ============================================================
# Query:
# variable_dcid: Count_Person
# variable_name: Total Population
# place_dcid: country/USA
# child_place_type: State
# Date Filter:
# date_filter: range
# date_range_start: 2019-01-01
# date_range_end: 2021-12-31
# Source:
# source_id: CensusACS5YearSurvey
# source_url: https://data.census.gov
# Export:
# server_version: 1.2.0
# timestamp: 2024-01-15T10:30:00Z
# total_pages: 5
# ============================================================
#
place_dcid,place_name,place_type,variable_dcid,variable_name,date,value,source_id
...要禁用沿袭标头，请设置 include_lineage=False 在配置中。
进度流
服务器支持在大数据获取期间实时更新进度：
STDIO传输（默认） 进度消息以JSON格式写入stderr，适用于程序化解析。
苏格兰和南方能源公司运输 对于基于web的客户端，可以通过服务器发送事件流式传输进度：
uvx datacommons-mcp serve http --progress-transport sse --sse-port 8081连接到 http://localhost:8081/events 以接收实时进度更新。
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
DC_API_KEY | 是 | 您的数据共享API密钥 |
DC_API_ROOT | 否 | 自定义API根URL |
DC_WEBSITE_ROOT | 否 | 自定义网站根URL |
DC_STORAGE_DIR | 否 | 用于存储导出数据文件的目录（默认： ./datacommons-data) |
DC_OUTPUT_FORMAT | 否 | 文件导出的默认格式： csv 或 json （默认值： csv) |
DC_MAX_PAGES | 否 | 分页请求中可获取的最大页面数（默认值： 100) |
DC_INCLUDE_LINEAGE | 否 | 在CSV导出中包含数据沿袭标头（默认值： true) |
DC_MULTI_FILE_EXPORT | 否 | 使用配套CSV启用多文件导出（默认值： false) |
DC_SCREEN_ROW_THRESHOLD | 否 | 在自动模式下返回屏幕的最大行数；较大的响应将转到文件（默认值： 500) |
使用带有自定义数据共享的MCP工具
跟随 MCP工具与自定义数据共享使用指南 设置自定义配置所需的其他环境变量。
版本历史
v1.2.0版本
- 为大型数据集添加了基于分页的流式传输
- 为多页响应添加了自动CSV导出
- 添加了输出模式选择（自动、屏幕、文件）
- 增加了传输抽象层（STDIO、SSE）
- 添加了用于实时进度流的SSE服务器
- 添加了具有分割策略的多文件导出
- 在CSV导出中添加了全面的数据沿袭标头
v1.1.x
- 具有核心MCP功能的初始版本
- 搜索指标并获取观察工具
- 自定义数据共享支持