mcp-server-datahub

DataHub MCP 服务

为 DataHub 实现的 模型上下文协议 服务。

什么是 DataHub？

DataHub 是一个开源上下文平台，让组织能够一站式查看整个数据供应链。DataHub 将数据发现、治理和可观测性整合在一起，覆盖每张表、每一列、每个仪表板、数据管道、文档和机器学习模型。

DataHub 提供强大的数据分析、数据质量监控、数据血缘、数据所有权和数据分类功能，将技术和组织上下文汇集在一起，帮助团队查找、创建、使用和维护可信数据。

使用场景

DataHub MCP 服务使 AI Agent 能够：

• 查找可信数据：使用自然语言搜索整个数据版图，找到能回答最关键问题的表、列、仪表板和指标。利用数据热度、质量、血缘和查询历史等可信度信号，确保每次都能找到正确的数据。

• 探索数据血缘并规划数据变更：通过丰富的资产级和列级数据血缘，在重要数据变更影响下游用户_之前_了解其影响。

• 了解业务：浏览业务术语表、数据域、数据产品_以及_数据资产等重要组织上下文。了解关键指标、业务流程和数据之间的关联。

• 解释并生成 SQL 查询：借助数据文档、数据血缘和组织内的热门查询等关键上下文，生成准确的 SQL 查询，回答最重要的问题。

为什么选择 DataHub MCP 服务？

借助 DataHub MCP 服务，您可以立即让 AI Agent 查看整个数据生态系统。通过自然语言查找并了解存储在数据库、数据湖、数据仓库和 BI 可视化工具中的数据。探索数据血缘，了解用法和使用场景，识别数据专家并生成 SQL。

结合上下文筛选的结构化搜索

通过强大的查询和筛选语法，超越关键词匹配：

• 通配符匹配：/q revenue_* 可查找 revenue_kpis、revenue_daily、revenue_forecast
• 字段搜索：/q tag:PII 可查找所有带有 PII 标签的数据
• 布尔逻辑：/q (sales OR revenue) AND quarterly 可执行复杂查询

SQL 智能分析与查询生成

获取热门 SQL 查询，并准确生成新查询：

• 查看分析师如何查询表（非常适合生成 SQL）
• 了解联接模式和常用筛选条件
• 借鉴生产环境中的查询模式

表级和列级血缘

追踪表级和列级的数据流：

• 跟踪 user_id 如何在下游变为 customer_key
• 了解转换逻辑
• 探索上游和下游（1-3+ 跳）
• 处理企业规模的血缘图

了解您的数据生态系统

在搜索之前，先了解数据的组织方式：

• 发现相关的数据域、所有者、标签和术语表条目
• 浏览不同的数据平台和环境
• 无需猜测，即可了解数据版图的复杂情况

使用方法

请参阅 DataHub MCP 服务文档中的说明。

本地 stdio 部署

本地 MCP 客户端默认仍使用 stdio 传输：

uvx mcp-server-datahub

stdio 服务会从环境中加载 DATAHUB_GMS_URL 和 DATAHUB_GMS_TOKEN；如果未设置，则会使用由 datahub init 创建的 ~/.datahubenv。这是本地部署模式，无需 HTTP 身份验证。

本地 CLI 也支持在可信的本地网络中使用 SSE。SSE 不提供专用 HTTP 入口使用的逐请求 bearer 身份验证，因此不应将其作为共享网络服务公开。

Docker HTTP 部署

容器在端口 8000 上运行无状态 HTTP 传输。它有意不使用服务级别的 DATAHUB_GMS_TOKEN；每个 MCP 客户端都提供自己的 DataHub 令牌，以便保留每位用户的 DataHub 权限和审计身份。

现有 HTTP 部署的重大变更： HTTP 现在有独立的 mcp-server-datahub-http 入口点。配置了 DATAHUB_GMS_TOKEN 时，该入口点会拒绝启动，并且每个客户端都必须发送自己的 DataHub bearer 令牌。本地 stdio 和 SSE 行为不变。

docker run --rm -p 8000:8000 \
  -e DATAHUB_GMS_URL=https://your-datahub.example \
  acryldata/mcp-server-datahub:latest

同一个隔离的 HTTP 入口点也可在 Docker 外使用：

DATAHUB_GMS_URL=https://your-datahub.example mcp-server-datahub-http

连接到 http://localhost:8000/mcp，并在每个请求中包含令牌：

Authorization: Bearer <datahub-personal-access-token>

令牌只接受通过 Authorization 标头传递；查询字符串令牌（例如 ?access_token=...）会被拒绝。

DataHub 必须设置 METADATA_SERVICE_AUTH_ENABLED=true 才能建立调用方身份。如果上游身份验证已禁用，GMS 可能会为任意 bearer 值返回一个虚构且不存在的主体；MCP 服务无法修正此上游配置。

如需本地构建，请创建包含 DATAHUB_GMS_URL 的 .env 文件，然后运行：

docker compose up --build

镜像和服务会公开未经身份验证的 GET /health 端点，供容器、负载均衡器和 Kubernetes 探针使用。该端点仅报告进程健康状况，不会联系 DataHub。

livenessProbe:
  httpGet:
    path: /health
    port: 8000
readinessProbe:
  httpGet:
    path: /health
    port: 8000

必须保护传输中的 bearer 令牌。在将 HTTP 部署暴露到可信网络之外之前，请在入口或反向代理处终止 TLS 并应用速率限制。速率限制尤为重要，因为每个新的无效令牌都可能触发向 GMS 发送验证请求。

已成功验证的令牌及其 DataHub 客户端会缓存五分钟。如果缓存请求收到 DataHub 返回的 401 或 403，该客户端将被逐出缓存，下一次请求会重新验证令牌。验证失败不会被缓存；并发上游验证次数会受到限制，以保护 DataHub。

演示

观看与 Block 团队合作制作的演示视频。

工具

DataHub MCP 服务提供以下工具：

search

使用结构化关键词搜索（/q 语法）搜索 DataHub，支持布尔逻辑、筛选、分页，以及可选的使用指标排序。

get_lineage

获取任意实体（数据集、列、仪表板等）的上游或下游血缘，支持筛选、血缘范围内查询、分页和跳数控制。

get_dataset_queries

获取引用数据集或列的真实 SQL 查询（手动或系统生成），以了解使用模式、联接、筛选条件和聚合行为。

get_entities

根据 URN 获取一个或多个实体的详细元数据；支持批量检索，以便高效检查搜索结果。

get_aspect_history

获取一个或多个实体/aspect 对的当前值，以及按时间倒序排列、范围有限的保留历史版本分页结果；每个版本都包含摄取和审计溯源信息。

list_schema_fields

列出数据集的 schema 字段，支持关键词筛选和分页；适用于搜索结果截断字段或探索大型 schema 的情况。

get_lineage_paths_between

获取两个资产或列之间的精确血缘路径，包括中间转换和 SQL 查询信息。

修改工具

这些工具可用于修改 DataHub 中的元数据。通过环境变量 TOOLS_IS_MUTATION_ENABLED=true 启用。

add_tags / remove_tags

为实体或架构字段（列）添加或移除标签。支持对多个实体执行批量操作。

add_terms / remove_terms

为实体或架构字段添加或移除术语表术语。适用于应用业务定义和数据分类。

add_owners / remove_owners

为实体添加或移除所有权分配。支持不同的所有权类型（技术负责人、数据负责人等）。

set_domains / remove_domains

为实体分配或移除所属域。每个实体只能属于一个域。

update_description

更新、追加或移除实体或架构字段的描述。支持 Markdown 格式。

add_structured_properties / remove_structured_properties

管理实体上的结构化属性（类型化元数据字段）。支持字符串、数字、URN、日期和富文本值类型。

用户工具

这些工具用于提供已通过身份验证的用户信息。通过 TOOLS_IS_USER_ENABLED=true 启用。

get_me

获取当前已通过身份验证的用户信息，包括个人资料详情和群组成员身份。

文档工具

这些工具可处理存储在 DataHub 中的文档（知识文章、运行手册、常见问题解答）。如果目录中没有文档，文档工具会自动隐藏。

search_documents

使用关键词搜索文档，并可按平台、域、标签、术语表术语和负责人筛选。

grep_documents

使用正则表达式搜索文档内容。适用于跨多个文档查找特定信息。

save_document

将独立文档（见解、决策、常见问题解答、笔记）保存到 DataHub 知识库。文档会整理到可配置的父文件夹下。

配置

环境变量

变量	默认值	描述
DATAHUB_GMS_URL	无	DataHub 服务 URL。HTTP 模式下必需；stdio 模式也可从 ~/.datahubenv 加载。
DATAHUB_GMS_TOKEN	无	旧版 stdio/SSE 凭据。设置此共享凭据时，HTTP 模式会拒绝启动。
FASTMCP_HOST	FastMCP 默认值（127.0.0.1）；镜像默认值（0.0.0.0）	HTTP/SSE 绑定地址。
FASTMCP_PORT	8000	HTTP/SSE 监听端口；也用于镜像健康检查。
TOOLS_IS_MUTATION_ENABLED	false	启用修改工具（添加/移除标签、负责人等）
TOOLS_IS_USER_ENABLED	false	启用用户工具（get_me）
DATAHUB_MCP_DOCUMENT_TOOLS_DISABLED	false	完全禁用文档工具
SAVE_DOCUMENT_TOOL_ENABLED	true	启用或禁用 save_document。仅当 TOOLS_IS_MUTATION_ENABLED=true 时才会注册此工具。
SAVE_DOCUMENT_PARENT_TITLE	Shared	已保存文档的父文件夹标题
SAVE_DOCUMENT_ORGANIZE_BY_USER	false	按用户整理已保存的文档
SAVE_DOCUMENT_RESTRICT_UPDATES	true	仅允许更新共享文件夹中的文档
TOOL_RESPONSE_TOKEN_LIMIT	80000	工具响应的最大 token 数
QUERY_LENGTH_LIMIT	5000	工具响应中 SQL 查询语句和视图定义的最大字符数
ENTITY_SCHEMA_TOKEN_BUDGET	16000	每个实体的架构字段 token 预算
DESCRIPTION_LENGTH_LIMIT	5000	实体级描述的最大字符数
FIELD_DESCRIPTION_LENGTH_LIMIT	120	架构字段的描述、编辑后的描述和弃用说明的最大字符数
DISABLE_NEWER_GMS_FIELD_DETECTION	false	禁用自适应 GMS 字段检测
DATAHUB_MCP_DISABLE_DEFAULT_VIEW	false	禁用自动应用默认视图
SEMANTIC_SEARCH_ENABLED	false	启用语义搜索（由 AI 驱动）

示例：数据发现与理解流程（供使用 DataHub 工具的 Agent 参考）

本示例展示 AI Agent 如何协调调用 DataHub MCP 工具，回答用户的数据问题。示例演示了决策流程、调用的工具，以及如何使用响应。

1. 用户提出问题

示例：

“如何查出上个月有多少只宠物被领养？”

Agent 会将其识别为数据发现 → 查询构建工作流。它需要：(a) 查找相关数据集，(b) 检查元数据，(c) 构建正确的 SQL 查询。

2. 搜索相关数据集

Agent 首先使用 search 工具（根据配置选择语义搜索或关键词搜索）。

工具： search
输入： 自然语言查询

调用示例：

{
  "query": "pet adoptions"
}

用途： 查找 adoptions、pet_profiles、pet_details 等数据集。

3. 检查候选数据集

对于搜索返回的每个数据集，Agent 都可以获取其元数据。

3.1 列出架构字段

工具： list_schema_fields
输入： 数据集的 URN
用途： 了解架构、数据类型以及可用于查询的候选字段。

示例：

{
  "urn": "urn:li:dataset:(urn:li:dataPlatform:snowflake,mydb.public.adoptions,PROD)"
}

list_schema_fields 支持分页。首次响应成功并不一定表示已获取完整架构：如果 remainingCount 大于零，就应继续获取。应按实际返回的字段数递增偏移量，而不是按请求的上限递增，因为响应令牌预算可能会缩短页面：

offset = 0
all_fields = []

do:
    page = list_schema_fields(urn=dataset_urn, limit=100, offset=offset)
    all_fields.extend(page.fields)
    offset = page.offset + page.returned
while page.remainingCount > 0

如果偏移量已超出最后一个字段，此模式也能安全终止：工具会返回空页面，并将 remainingCount 设为 0。

3.2 获取沿袭信息（可选）

工具： get_lineage
用途： 判断数据集是派生数据集还是权威数据集。

3.3 获取示例查询

工具： get_dataset_queries
用途： 了解该数据集的典型用法和查询模板。

4. 了解实体关系

如果问题需要联接数据或导航实体（例如，关联宠物 → 领养记录）：

get_entities

检索与给定 URN 相关的实体，例如上游或下游表。

get_lineage_paths_between

如有需要，计算数据集之间的精确沿袭路径（例如 pet_profiles 与 adoptions 之间的路径）。

5. 构建查询

现在，Agent 已掌握：

• 正确的数据集
• 其架构
• 关键字段
• 示例查询
• 关系与沿袭上下文

Agent 据此构建准确的 SQL 查询。

示例：

SELECT COUNT(*)
FROM mydb.public.adoptions
WHERE adoption_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1' MONTH)
  AND adoption_date < DATE_TRUNC('month', CURRENT_DATE);

6. 返回最终答案

Agent 可以：

• 直接返回 SQL，
• 运行 SQL（如果所处环境允许执行查询），或
• 根据查询结果提供自然语言答案。

使用的工具摘要

工具名称	用途
search	查找与问题相关的数据集。
list_schema_fields	了解数据集结构。
get_lineage	评估数据的权威性和来源。
get_dataset_queries	了解数据集的典型查询方式。
get_entities	获取相关实体以提供上下文。
get_lineage_paths_between	了解数据集之间更深层的关系。

开发

请参阅 DEVELOPING.md。