DataHub Agent Context 接入 Google Gemini CLI在终端中通过 MCP 安全查询企业数据上下文【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本文是一份面向数据工程师与 AI 开发者的实战指南讲解如何将 Google 官方命令行工具 Gemini CLI 接入 DataHub 的 MCPModel Context ProtocolServer让 AI 助手在终端中直接搜索可信数据资产、追踪血缘并查询所有权信息。读完本文你将掌握 DataHub Cloud 托管端点与 DataHub Core 自托管两种接入方式的完整配置、认证方式Bearer Token 与个人访问令牌以及连接验证与故障排查方法。背景为什么要在 Gemini CLI 中接入 DataHubDataHub 将自身的元数据能力以 MCP Server 的形式暴露给 AI Agent使其能够在编码、问答等场景中直接消费企业级数据上下文。官方文档将其定位为 Context Platform for your Data and AI Stack而 Agent Context Kit 总览 明确指出DataHub MCP Server 可以让 Agent 获取业务定义、上下文文档、数据所有权、血缘、质量信号与样例查询等信息。Gemini CLI 是 Google 的命令行 AI 编程助手通过 MCP 协议接入 DataHub 后你可以在终端里用自然语言完成找到可信的数据表、查看列级 Schema、追溯上游/下游血缘、确认数据集负责人并在写作 SQL 时参考真实的使用记录。这与 Cursor 接入指南、Claude 接入指南 同属 Agent Context Kit 的 AI 编程助手阵营。在动手之前你需要先了解 DataHub MCP Server 提供了哪些能力。根据 DataHub MCP Server 指南它主要提供以下工具均带 MCP 标准注解readOnlyHint、destructiveHint、idempotentHint客户端可据此提示哪些工具会修改目录状态并要求确认数据发现与检视search结构化全文检索支持布尔逻辑与通配符、get_entities按 URN 批量获取元数据、list_schema_fields列出 Schema 字段、get_lineage追踪表/列级血缘、get_me查询当前认证用户信息等只读工具SQL 与查询get_dataset_queries获取真实 SQL 查询、find_sql_context、draft_sql_for_tables基于真实使用语境起草 SQL元数据编辑Mutationadd_tags、add_terms、add_owners、set_domains、update_description等需要服务端开启TOOLS_IS_MUTATION_ENABLEDtrue治理与提案list_pending_proposals、propose_create_glossary_term等。接入 Gemini CLI 后上述工具会以 MCP 工具形式自动暴露给终端中的 AI 助手。前提条件在配置 Gemini CLI 之前请确认以下条件Gemini CLI 已安装。本文面向 Google 官方命令行工具gemini-cli安装与升级请遵循其官方发布说明。一个可用的 DataHub 实例二者选其一DataHub Cloud托管版要求 v0.3.12 及以上版本才提供托管 MCP Server 端点详见 MCP Server 指南的托管使用章节DataHub Core / 自托管运行开源 MCP Server详见 MCP Server 指南的自托管章节。一个个人访问令牌Personal Access Token, PAT。关于 PAT 的生成、权限要求与使用方式请参阅 个人访问令牌文档。关于 PAT 有两点值得提前注意生成 PAT 需要 DataHub 中已启用元数据服务认证GMS 开启Metadata Service Authentication且当前用户被授予Generate Personal Access Tokens或Manage All Access Tokens权限通过 DataHub Policy 配置。在界面中依次进入Settings → Access Tokens → Generate Personal Access Token即可创建。PAT 在 HTTP 请求中通过Authorization: Bearer token头发送。令牌默认支持的有效期由 GMS 配置authentication.accessTokens.allowedDurations决定默认PT1H、P1D、P7D、P30D、P90D、P180D、P365D即 1 小时到 365 天不等如需永不过期令牌需设置ACCESS_TOKEN_ALLOW_NO_EXPIRYtrue。接入 DataHub Cloud托管端点Gemini CLI 原生支持streamable HTTP 传输与自定义请求头因此可以直接对接 DataHub Cloud 的托管 MCP 端点无需安装任何额外组件或本地代理。方式一命令行添加 MCP Server执行以下命令将 DataHub Cloud 添加为 Gemini CLI 的 MCP Servergemini mcp add --transport http \ --header Authorization: Bearer token \ datahub-cloud \ https://tenant.acryl.io/integrations/ai/mcp/参数说明--transport http指定使用 streamable HTTP 传输协议。DataHub 的托管 MCP 端点仅支持 streamable HTTP部分老旧客户端只支持已废弃的 SSE 传输此时需借助mcp-remote桥接详见 MCP Server 指南。--header Authorization: Bearer token携带认证头。注意切勿改用?token查询参数——托管端点会对携带token查询参数的请求直接返回400 Bad Request且令牌出现在 URL 中会泄露到代理日志、浏览器历史与Referer头中。datahub-cloud这是你为该 MCP Server 起的名称可自定义后续在会话中通过/mcp命令引用。端点 URL 中的tenant替换为你的 DataHub Cloud 租户名形如https://tenant.acryl.iotoken替换为你的个人访问令牌。若是本地部署的 DataHub Cloudon-premises则将tenant.acryl.io替换为你的 DataHub FQDN例如https://datahub.example.com/integrations/ai/mcp/。方式二直接写入 settings.json也可以将配置直接写入 Gemini CLI 的配置文件。用户级配置位于~/.gemini/settings.json项目级配置位于.gemini/settings.json位于项目根目录下{ mcpServers: { datahub-cloud: { httpUrl: https://tenant.acryl.io/integrations/ai/mcp/, headers: { Authorization: Bearer token } } } }这种方式的优势是配置可随仓库共享项目级或固化在个人环境中用户级适合团队统一维护。注意妥善保管令牌不要将真实令牌提交到版本库。关于 OAuth 的说明对于 v1.0.2 及以上的 DataHub Cloud官方推荐使用OAuth2 Dynamic Client RegistrationDCR作为交互式客户端的首选认证方式——每个用户用自己的登录含 SSO连接令牌自动刷新。统一入口为https://mcp.datahub.com/mcp。但 PAT 认证仍适用于服务账号、无人值守的 Agent 工作流CI/CD、定时任务、低于 v1.0.2 的 DataHub Cloud 以及尚未实现 OAuth 远程 MCP 的客户端。本文场景Gemini CLI 终端以 PAT 方式为准完整对比见 MCP Server 指南。接入 DataHub Core自托管 MCP ServerDataHub Core 用户需要自行运行开源 MCP Servermcp-server-datahub。它与 DataHub Core 和 DataHub Cloud 均兼容可本地为单个用户运行也可作为共享 HTTP 服务供团队使用。安装 uv 并添加 MCP Server首先安装uv一个快速的 Python 包与项目管理工具uvx由其提供curl -LsSf https://astral.sh/uv/install.sh | sh然后执行gemini mcp add \ -e DATAHUB_GMS_URLyour-datahub-url \ -e DATAHUB_GMS_TOKENyour-datahub-token \ datahub \ uvx mcp-server-datahublatest参数说明-e DATAHUB_GMS_URL设置环境变量指向你的 DataHub GMS 端点例如http://localhost:8080或生产环境地址。GMSGeneralized Metadata Service是 DataHub 的元数据服务MCP Server 通过它执行 GraphQL 查询。-e DATAHUB_GMS_TOKEN设置环境变量传入你的个人访问令牌。datahubMCP Server 名称。uvx mcp-server-datahublatestGemini CLI 将通过uvx按需拉取并运行最新版的 DataHub MCP Server本地 stdio 模式由 Gemini CLI 直接拉起子进程。如需固定版本可将latest替换为具体版本号例如mcp-server-datahub0.7.0。认证原理自托管场景下MCP Server 通过两个环境变量完成认证DATAHUB_GMS_URL与DATAHUB_GMS_TOKEN它们在启动时注入mcp-server-datahub进程。这一点在 MCP Server 指南的连接与认证章节 有明确说明也与 Claude 接入指南 中claude mcp add ... -- uvx mcp-server-datahublatest的用法一致——不同客户端只是把同样两个环境变量以各自的方式传给同一个服务器进程。进阶共享 HTTP 部署上述方案是一人一进程。若要为整个团队提供单一部署要求mcp-server-datahubv0.7.0可以改为运行 HTTP 入口每位用户携带自己的DataHub 令牌从而保持权限、搜索结果与审计归属的隔离docker run -p 8000:8000 \ -e DATAHUB_GMS_URLyour-datahub-url \ acryldata/mcp-server-datahub:latest或不使用 DockerDATAHUB_GMS_URLyour-datahub-url FASTMCP_HOST0.0.0.0 \ uvx --from mcp-server-datahub mcp-server-datahub-http重要警告共享部署中绝不能设置DATAHUB_GMS_TOKEN——服务器检测到该变量存在时会拒绝启动因为服务端统一令牌会让所有用户共用同一身份。同时你的 DataHub 实例必须开启METADATA_SERVICE_AUTH_ENABLEDtrue以便服务端识别每个调用者的身份。客户端连接到http://host:8000/mcp并在每次请求中携带各自的令牌Authorization: Bearer your-datahub-token服务器另暴露未认证的GET /health端点供负载均衡与 Kubernetes 探活使用。Gemini CLI 的接入方式与此前一致gemini mcp add --transport http \ --header Authorization: Bearer your-datahub-token \ datahub \ http://host:8000/mcp验证连接是否成功完成上述任一配置后用以下方式确认 DataHub Server 已正确连接在终端运行gemini mcp list检查datahub-cloudCloud 场景或datahubCore 场景是否出现在已连接的服务器列表中在 Gemini CLI 会话内使用/mcp命令确认 DataHub Server 显示为已连接状态。连接成功后即可在会话中向 Gemini 提问例如找到名为 revenue 的表并查看其 ownerAgent 会调用search、get_entities、get_lineage等 MCP 工具完成检索。从源码看 MCP Server 的底层实现仓库中的datahub-agent-context模块包含与 MCP Server 同源的 Python 工具实现可以帮助你理解接入后的实际行为。工具层search 的实现在 search.py 中search工具的实现细节揭示了检索能力的边界查询默认从*全量开始支持/q前缀的结构化语法/q usertransactionAND、/q revenue*通配符、/q tag:PII字段搜索、/q (sales OR revenue) AND quarterly布尔组合num_results上限被硬编码为 50num_results min(num_results, 50)防止过量请求压垮 GMS支持分页offset、按lastOperationTime排序以及零结果仅返回 facet的元数据勘探模式num_results0时仅返回标签、术语、平台、域等 facet便于 Agent 先了解目录里有什么再执行过滤检索。基础设施层GraphQL 执行与兼容性base.py 中的execute_graphql是各工具共同的执行入口体现了对 Cloud / Core 两种部署形态的适配通过graph.frontend_base_url是否存在来启发式判断实例是否为 DataHub Cloud见 _is_datahub_cloud进而对 GraphQL 查询中标记了#[CLOUD]与#[NEWER_GMS]的字段做启用/禁用处理当 GMS 报出字段校验错误FieldUndefined、ValidationError、InvalidSyntax时会禁用更新字段后自动重试并将结果缓存实现新旧 GMS 版本的平滑降级响应清理clean_gql_response会递归移除__typename、空值与 Base64 内嵌图片降低传给 LLM 的 token 开销——这正是 Agent 场景下的工程化细节。检索范围控制Default View 支持base.py 还实现了 Default View 解析通过me查询获取用户的个人默认视图回退到组织的全局默认视图globalViewsSettings.defaultView结果缓存 5 分钟VIEW_CACHE_TTL_SECONDS 300。这意味着 MCP Server 的搜索结果默认会被限制在用户配置的视图范围内可用于将 Agent 的可见性限定到特定域、平台或团队资产——在 Cloud v1.0.0 / Core v1.6.0 中服务账号也支持通过 Default View 收敛搜索范围详见 MCP Server 指南的服务账号章节。故障排查连接不上或工具不出现确认gemini mcp list与/mcp命令显示服务器已连接若未显示检查settings.json的 JSON 语法与httpUrl/headers字段名是否正确若使用 Cloud 端点确认实例版本 ≥ v0.3.12且请求未携带?token参数会导致400 Bad Request。401 UnauthorizedPAT 代表的是创建它的用户如果该用户在 DataHub 中没有对应操作的权限令牌同样会被拒绝见 个人访问令牌 FAQ确认 GMS 已启用元数据服务认证否则 PAT 校验不会生效检查令牌是否过期默认有效期范围PT1H至P365D永不过期需显式开启。spawn uvx ENOENT自托管DataHub Core场景下若 Gemini CLI 报spawn uvx ENOENT说明找不到uvx可执行文件。解决方法是将命令中的uvx替换为which uvx输出的完整路径例如/Users/you/.local/bin/uvx。其他问题关于认证错误、空结果、uvx未找到等更多通用排障指引请参见 MCP Server 指南的故障排查章节。小结把 DataHub MCP Server 接入 Gemini CLI 只需三步准备一个 DataHub 实例与个人访问令牌按 Cloud 或 Core 选择对应的gemini mcp add命令或写入settings.json用gemini mcp list验证连接。Cloud 场景走 streamable HTTP Bearer 头直连托管端点Core 场景则通过uvx拉起自托管服务器并注入DATAHUB_GMS_URL/DATAHUB_GMS_TOKEN两个环境变量。接入后Gemini CLI 即可在终端中安全地消费 DataHub 的数据资产目录从搜索、血缘到所有权查询一气呵成。相关配套文档可继续参阅 DataHub MCP Server 指南 与 Agent Context Kit 总览。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考