You need to enable JavaScript to run this app.
导航
ByteHouse云数仓版
  • 文档首页
    • /ByteHouse云数仓版/最佳实践/ByteHouse + MCP + LLM 搭建数据分析 Agent
ByteHouse + MCP + LLM 搭建数据分析 Agent
最近更新时间：2025.06.11 11:25:11首次发布时间：2025.06.10 14:00:17
我的收藏
有用
有用
无用
无用

ByteHouse 已对接 MCP 协议，用于构建数据源、多步骤分解实现数据分析。同时，由于 ByteHouse 具备高性能数据分析的能力，可以快速输出数据结果，极大简化分析人员的分析流程，提高分析效率。

背景信息

在数据分析领域，大模型（LLM）具备强大语言理解能力，NL2SQL 等各类智能化工具也极大提升了数据分析人员的分析效率，但仍旧面临不少挑战：

  • LLM 缺乏实时数据接入能力：LLM 无法获取实时数仓数据，动态调用专业工具链，上下文记忆链路短，数据分析经过多步骤分解后逐渐出现幻觉。
  • 跨数据源分析困难：数据分布在不同系统，例如在线数据平台、本地 CSV/Excel 等文件，跨系统数据整合需大量准备时间，取数仍然需要大量依赖取数工程师和取数平台。

MCP（模型上下文协议）通过标准化接口架构，将 AI 模型的决策逻辑与外部资源解耦，形成 "智能中枢 + ByteHouse" 的协同模式，旨在解决大模型与外部工具、数据源的集成难题。LLM 通过 MCP 接入各种数据分析工具或者数据仓库能力时，即可构建数据分析 Agent。

应用场景

ByteHouse 基于 MCP 协议实现 ByteHouse MCP Server，赋能 LLM 实时数仓分析能力。当 LLM 接入ByteHouse MCP Server 时，可实现如下场景：

  • 实时数据中枢：通过 MCP 管道实现 ByteHouse与 API / 数据库等数据毫秒级接入。同时，ByteHouse 作为高性能实时数仓，在 Agent 的逐步分解分析时，输出结果更快。
  • 对话式分析引擎：LLM 直接调用 ByteHouse 数据接口，支持自然语言提问生成动态解读报告。
  • 资源隔离与降本：ByteHouse 支持秒级扩缩容，Agent 数据分析资源可以与数据生产系统隔离，降低分析成本。

功能概述

ByteHouse MCP Server 是大语言模型和 ByteHouse 实例的沟通桥梁，能高效传递信息，实现二者无缝对接与协同。它还为 ByteHouse 数据开发、查询优化、集群运维提供全生命周期智能化服务。数据开发时，提供精准指引与建议，提升效率和质量；查询优化方面，支持分析语句、优化性能；集群运维环节，提供监测状态、预警风险、自动诊断修复，保障系统高效运转。
您可以通过火山方舟通过云部署模式或本地部署模式的方式部署 ByteHouse MCP Server。MCP Client 可以支持火山方舟平台、Trae 、Cusrsor、Python 等多种方式接入。

工具能力

工具名称

说明

list_databases

在 ByteHouse 服务器获取指定集群下所有数据库。

list_tables

在 ByteHouse 服务器获取指定数据库下所有数据表。

run_dml_ddl_query

在 ByteHouse 服务器上执行一个 SELECT SQL 查询。

get_bytehouse_table_engine_doc

获取 ByteHouse 表引擎使用文档，目前有以下几种表引擎文档：

  • cnch_merge_tree
  • cnch_unique_merge_tree

输入对应的表引擎名，返回对应的文档，请参考文档描述，按照需求选择对应的表引擎。

云部署

火山引擎已为您准备好 ByteHouse MCP 服务的云部署条件。您只需开通并单击 “云部署”，该服务即可由函数服务（veFaaS）和 API 网关以 serverless 方式全托管，支持自动扩缩容，无需手动运维。费用按实际调用时长和次数收取，更多计费详情可查函数服务和API网关计费说明。

操作步骤

  1. 在火山引擎 大模型生态广场 -> 搜索 ByteHouse MCP。
    Image

  2. 打开后如下图，单击云部署。
    Image

  3. 输入Bytehouse 连接地址、端口、用户名称、密码、选择网关实例后单击开始部署。
    Image
    环境变量获取说明

    产品名称

    环境变量

    说明

    ByteHouse 云数仓版（CDW)

    BYTEHOUSE_HOST

    ByteHouse 连接网关地址，可登录 ByteHouse 控制台，在租户管理 -> 基本信息 -> 网络信息中查看：
    Image

    BYTEHOUSE_PORT

    • 在参数 BYTEHOUSE_SECURE 设置为 true 时， 设置为 8443
    • 在参数 BYTEHOUSE_SECURE 设置为 fase 时， 设置为 8123

    BYTEHOUSE_USER

    设置为火山引擎平台当前登录用户账号名称。

    BYTEHOUSE_PASSWORD

    您可通过租户管理 -> 连接信息 -> API Key 获取用户密码。
    Image

    BYTEHOUSE_SECURE

    启用/禁用 HTTPS 连接，默认设置为 true。

    BYTEHOUSE_VERIFY

    启用/禁用 SSL 证书验证模式：

    • 默认设置为 true
    • 设置为 false 禁用证书验证（不建议用于生产）

    BYTEHOUSE_CONNECT_TIMEOUT

    连接超时（以秒为单位），如果遇到连接超时，请增加此值。

    BYTEHOUSE_SEND_RECEIVE_TIMEOUT

    发送/接收超时（以秒为单位） 默认 30s，对于长时间运行的查询，请增加此值。

  4. 等待部署完成后， 系统将生成 ByteHouse MCP Server 的连接地址。
    Image

快速体验

当您完成 ByteHouse + MCP + LLM 的 Agent 搭建之后，您可快速体验数据分析 Agent。
以下演示以 Trae 为例说明，需要提前安装 Trae。您也可以通过 VS Code客户端 / Cursor 并安装 Cline 扩展程序搭建。


步骤一： 配置 ByteHouse MCP 服务器地址

将在云部署模式说明中获取的 ByteHouse MCP Server 连接地址填入配置框，单击确认。
Image

步骤二： 创建 ByteHouse Agent

自定义 Agent 名称，并配置提示词，选择工具后，单击保存。

说明

提示词可以参考如下内容：
你是一位资深ByteHouse OLAP数据库专家，有如下功能
数据库管理功能，包括库、表、索引、分区、视图、存储格式、存储引擎、权限管理等功能
数据查询功能，包括SQL查询、数据导入、数据导出、数据备份、数据恢复等功能
数据管理功能，包括数据清理、数据压缩、数据备份、数据恢复等功能
数据监控功能，包括数据监控、数据报警、数据诊断等功能
数据安全功能，包括数据加密、数据脱敏、数据权限管理等功能
数据治理功能，包括数据质量监控、数据一致性检查、数据一致性修复等功能

Image

步骤三： 开始体验

配置完成后，即可开始体验 ByteHouseAgent。
Image
如下是最容易被唤起的 Prompt 示例，您可使用以下示例体验。

list_database
我想要查询当前所使用的集群环境中，都存在哪些数据库。具体来说，希望获取该集群内所有已创建数据库的名称等相关信息，以便进一步对这些数据库进行管理、分析或者使用等操作。 
list_tables
我想要查询数据库名为 {database name} 的这个数据库中具体包含了哪些数据表。 
run_select_query
帮忙查询一下集群存储目前的水位情况，包括各个存储节点当前的使用容量、剩余容量以及占总容量的百分比等详细信息。 
get_bytehouse_table_engine_doc
帮我详细查询一下Bytehouse表引擎的使用文档。为了能更直观地了解其操作方式，希望能给出一些具体的执行实例，包括示例代码、操作步骤、输入输出的详细描述等内容，以便我可以更好地学习和实践Bytehouse表引擎的相关应用。

本地部署

您也可以选择在本地运行 Bytehouse MCP Server，按照如下模版配置在 Cursor，Visual Studio Code，Trae 等客户端。环境变量获取方式可参考操作步骤中步骤三中的说明。
Image

{
  "mcpServers": {
    "mcp_server_bytehouse": {
      "command": "uvx",
      "serverName": "mcp-bytehouse",
      "args": [
        "--from",
        "git+https://github.com/volcengine/mcp-server@main#subdirectory=server/mcp_server_bytehouse",
        "mcp_bytehouse"
      ],
      "env": {
        "BYTEHOUSE_HOST": "<ByteHouse-host>",
        "BYTEHOUSE_PORT": "<ByteHouse-port>",
        "BYTEHOUSE_USER": "<ByteHouse-user>",
        "BYTEHOUSE_PASSWORD": "<ByteHouse-password>",
        "BYTEHOUSE_SECURE": "true",
        "BYTEHOUSE_VERIFY": "true",
        "BYTEHOUSE_CONNECT_TIMEOUT": "30",
        "BYTEHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "UV_NO_CACHE": "1"
      }
    }
  }
}