Lakehouse MCP Server 介绍以及快速部署

简介：

MCP（Model Context Protocol）Server 是一种标准化的接口协议，允许 AI 助手（如 Claude）与外部系统和工具进行安全、可控的交互。通过 MCP Server，AI 助手可以直接访问和操作各种数据源、执行复杂的数据分析任务，并提供更加智能和高效的服务。

Lakehouse MCP Server 是专为 Lakehouse 平台设计的 MCP 服务器，它将云器 Lakehouse 强大的数据湖仓能力与 AI 助手无缝集成，让用户能够通过自然语言与数据湖仓进行交互。

核心特性

  • 协议支持：支持 HTTP (Streamable)、SSE、Stdio 三种传输协议
  • 标准兼容：完全遵循 MCP 官方规范，提供标准 /mcp 端点
  • 广泛兼容：支持 Claude Desktop、Dify、n8n、Cursor 等主流平台

部署环境要求

系统要求

  • 操作系统：MacOS、Windows、Linux
  • Docker：20.10+ 版本
  • 内存：最低 2GB，推荐 8GB
  • CPU：最低 2 核，推荐 4 核
  • 存储：最低 10GB 可用空间

快速开始

本示例介绍采用 HTTP (Streamable) 协议方式部署（推荐），同时 Claude Desktop (MCP 客户端) 和 MCP 服务器都运行在同一台本地计算机（localhost）上（该架构同样支持分布式部署，即客户端、服务器和 Lakehouse 平台可以分别位于不同的远程主机上）。

步骤0：MCP Server 端配置准备

Docker 环境准备：访问 https://www.docker.com/products/docker-desktop/ 下载 Docker Desktop for Mac。

  1. 验证安装 Docker Desktop （MacOS 环境）保证 Docker 版本20.10+
docker --version
  1. 配置 Docker Desktop：
  • 分配至少 4GB 内存给 Docker
  • 启用文件共享功能

步骤1：MCP Server 端：拉取最新云器的 MCP Server 镜像

docker pull czqiliang/mcp-clickzetta-server:latest

步骤2：MCP Server 端：创建工作目录（如果不存在）

  • macOS:

    mkdir -p ~/.clickzetta/lakehouse_connection

  • Windows PowerShell:

    New-Item -ItemType Directory -Path "$env:USERPROFILE\.clickzetta/lakehouse_connection" -Force

在上述路径下，新建名称为 connections.json 的配置文件并添加 Lakehouse 实例的连接信息，配置模板如下（如果连接两个 Lakehouse 实例，用逗号分隔）：

{
  "connections": [
    {
      "is_default": true,
      "service": "cn-shanghai-alicloud.api.clickzetta.com",
      "username": "__your_name__",
      "password": "__your_password__",
      "instance": "__your_instanceid__",
      "workspace": "__your_workspacename__",
      "schema": "public",
      "vcluster": "default_ap",
      "description": "UAT environment for testing",
      "hints": {
        "sdk.job.timeout": 300,
        "query_tag": "mcp_uat"
      },
      "name": "Shanghai production env",
      "is_active": false,
      "last_test_time": "2025-06-30T19:55:51.839166",
      "last_test_result": "success"
    }
  ]
}

参数说明：

参数名说明示例值
is_default是否为默认连接配置true
service服务端点地址请参考文档上海阿里云：cn-shanghai-alicloud.api.clickzetta.com 北京腾讯云：ap-beijing-tencentcloud.api.clickzetta.com 北京 AWS ：cn-north-1-aws.api.clickzetta.com 广州腾讯云：ap-guangzhou-tencentcloud.api.clickzetta.com 新加坡阿里云：ap-southeast-1-alicloud.api.singdata.com 新加坡 AWS：ap-southeast-1-aws.api.singdata.com
username用户名，用于身份验证"your_name"
password密码，用于身份验证"your_password"
instance实例ID，标识特定的Lakehouse实例"your_instanceid"
workspace工作空间名称，用于数据隔离和组织"your_workspacename"
schema数据库模式名称"public"
vcluster虚拟集群名称，用于计算资源管理"default_ap"
description连接配置的描述信息"UAT environment for testing"
hints性能优化和标识配置对象{...}
hints.sdk.job.timeoutSDK作业超时时间（秒）300
hints.query_tag查询标签，用于查询追踪和标识"mcp_uat"
name连接配置的名称标识"Shanghai production env"
is_active连接是否处于活跃状态false
last_test_time最后一次连接测试的时间戳（ISO格式）"2025-06-30T19:55:51.839166"
last_test_result最后一次连接测试的结果状态"success"

步骤3：MCP Server 端：启动 MCP Server 镜像

创建 docker-compose.yml 文件，拷贝内容到文件中（文件内容详见附录）

在包含该文件的目录下打开终端或命令行，并执行以下命令。

docker compose up -d

预期输出：

bash-3.2$ docker compose up -d
[+] Running 4/4
 ✔ Network mcp_docker_clickzetta-net  Created       0.0s 
   ✔ Container clickzetta-sse           Started       0.2s 
   ✔ Container clickzetta-http          Started       0.2s 
   ✔ Container clickzetta-webui         Started       0.2s

校验状态，使用 docker compose ps --format "table {{.Name}}\t{{.Service}}\t{{.Status}}" 命令，预期输出如下(忽略 WARNING 信息)：

bash-3.2$ docker compose ps --format "table {{.Name}}\t{{.Service}}\t{{.Status}}"

NAME               SERVICE            STATUS
clickzetta-http    clickzetta-http    Up 5 hours (unhealthy)
clickzetta-sse     clickzetta-sse     Up 5 hours (unhealthy)
clickzetta-webui   clickzetta-webui   Up 5 hours (unhealthy)

步骤4：配置 Claude Desktop

本示例选择的 MCP 客户端工具是 Claude Desktop，主机与 MCP Server 端位于同一台主机

找到并打开 Claude Desktop 配置文件：

macOS 操作步骤：

  • 打开 Finder
  • 按 Cmd+Shift+G
  • 粘贴路径：~/Library/Application Support/Claude
  • 双击打开 claude_desktop_config.json（用文本编辑器）

Windows 操作步骤：

  • 按 Win+R 打开运行对话框
  • 输入 %APPDATA%\Claude 并回车
  • 右键点击 claude_desktop_config.json
  • 选择"编辑"或"用记事本打开"

2. 将以下内容复制到配置文件（替换原有内容或添加到 mcpServers 中）：

请输入 MCP Server 的地址：如果服务器与客户端运行在同一台机器上，请填写 localhost；否则，请填写服务器的 IP 地址。

{
  "mcpServers": {
    "clickzetta-http": {
      "command": "npx", 
      "args": [
        "-y", "mcp-remote",
        "http://<YOUR_SERVER_IP>:8002/mcp",
        "--allow-http",
        "--transport", "http"
      ]
    }
  }
}

配置完成！

另外：Claude Desktop 支持通过多种方式连接后端的 MCP Server，以适应不同的部署环境和性能需求。上面的示例介绍了 HTTP (Streamable) 协议连接方式，如果想利用 SSE 或者 STDIO 协议连接，配置也很简单：

SSE 连接方式（远程服务）

SSE (Server-Sent Events) 是一种基于 HTTP 的长连接技术，允许服务器向客户端单向推送消息。相比于传统的轮询方式，SSE 能够以更低的延迟实现实时通信。

  • 适用场景：需要从服务器实时接收数据流或更新通知的场景。
  • Docker Server 配置参考：此方式对应启动容器中的 clickzetta-sse 的服务，该服务在 8003 端口上提供服务。
  • 配置示例： 在 Claude Desktop 的 claude_desktop_config.json 配置文件中更新如下信息，连接到远程 SSE 端点。

{
  "mcpServers": {
    "clickzetta-remote-sse": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://localhost:8003/sse",
        "--allow-http",
        "--transport", "sse"
      ]
    }
  }
}

说明：

  • 请将 <YOUR_SERVER_IP> 替换为 MCP Server 实际的 IP 地址或域名。
  • 目标端口为 8003，端点路径为 /sse。
  • --transport sse 参数指明了使用 SSE 通信协议。

STDIO 连接方式（本地进程）

此方式主要用于本地开发和调试。Claude Desktop 会将 MCP Server 作为一个子进程直接在本地启动，并通过标准输入/输出（STDIO）进行通信。这种方式延迟最低，但不适用于远程连接。

  • 适用场景：本地开发、单机部署。
  • Docker Server 配置参考：此方式对应启动容器中的 clickzetta-stdio 的服务，该容器镜像会随着 Claude Desktop 的开启和关闭，自动操作容器镜像拉起和停止。
  • 配置示例：在 Claude Desktop 的 claude_desktop_config.json 配置文件中更新如下信息，直接指定启动本地 Server 的命令。

注意：

  1. 配置文件中 -v 后的路径中 USERNAME 请根据系统的实际路径进行修改。
  2. 请使用 docker compose down 关闭创建的相关容器，因为此种方式下，Claude Desktop 会随着自身的开启和关闭，自动操作容器镜像拉起和停止。
{
  "mcpServers": {
    "clickzetta-stdio": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--stop-timeout", "60",
        "-p", "8502:8501",
        "-v", "/Users/derekmeng/.clickzetta:/app/.clickzetta",
        "czqiliang/mcp-clickzetta-server:latest"
      ]
    }
  }
}

说明：

  • command 和 args 直接定义了如何在本地启动 MCP Server。
  • 无需指定 IP 地址和端口。
  • --transport stdio 参数指明了使用 STDIO 通信协议。

开始使用：

部署验证

1. 打开 Claude Desktop ，在输入框中，发送以下指令：

列出所有 Clickzetta Lakehouse 可用的 MCP工具

 如果连接成功，您将看到一个包含 50+ 个工具的列表（注意：随着版本更新，工具的具体数量可能会有变化）

2. 验证 WebUI 界面

  • 在您的浏览器中访问以下地址： http://localhost:8503, 预期可以展示以下页面：

如果以上两个步骤都顺利完成，恭喜您，您的应用已成功安装！

第二步：配置您的第一个数据源 (Lakehouse)

接下来，让我们配置一个 Lakehouse 连接，以便 Claude 可以访问您的数据。

  1. 打开连接管理器

    访问 WebUI 界面 http://localhost:8503，然后在左侧菜单中选择「连接管理」。

  2. 添加并填写连接信息

    点击「添加新连接」按钮，并根据提示准确填写您的 Lakehouse 连接信息（如主机、端口、凭证等）

测试并保存

  1. 填写完毕后，点击「测试连接」按钮，确保所有配置信息无误且网络通畅。
  2. 测试通过后，点击「保存」完成配置。

第三步：开始您的第一个查询

现在一切准备就绪！您可以开始与您的数据进行交互了。尝试在 Claude Desktop 中提问：

高级配置：配置云器产品文档知识库

这个步骤会将云器 Lakehouse 产品知识库表集成进来，构建一个智能问答知识库。配置完成后，您将能够在 MCP Client（如 Claude Desktop）中，通过自然语言提问的方式，快速获得关于 Lakehouse 操作的官方指导和答案

该功能的核心是利用嵌入服务 (Embedding) 和向量搜索 (Vector Search) 技术，将非结构化的文档转化为可供机器理解和检索的知识库。

第一步：配置嵌入服务

此步骤的目的是告诉 MCP 系统如何将用户的“问题”也转换成向量，以便在知识库中进行匹配。

  1. 在 MCP Server 管理界面，从左侧导航栏进入「系统配置」。

  2. 在主配置区，选择 「嵌入服务」 标签页。

  3. 找到并填写 DashScope 配置（默认）部分：

    • API Key：粘贴您的阿里云百炼平台的 API 密钥。这是调用模型的身份凭证，请妥善保管。
    • 向量维度 (Vector Dimension)：输入您选择的嵌入模型所输出的向量维度。此值必须与知识库文档向量化时使用的维度完全一致。例如，截图中 text-embedding-v4 模型的维度是 1024。
    • 嵌入模型 (Embedding Model)：选择或填写用于将文本转换为向量的模型名称，例如 text-embedding-v4。
    • 最大文本长度 (Max Text Length)：设置模型一次可以处理的文本单元（Token）的最大数量。如果问题过长，超出部分将被忽略。

  4. 点击 保存嵌入服务配置 按钮。

第二步：配置向量搜索

此步骤的目的是告诉 MCP 系统去哪里、以及如何搜索已经存储好的文档知识库。

  1. 在 系统配置 页面，切换到 「向量搜索」 标签页。

  2. 填写 向量表配置 部分：

    • 向量表名称 (Vector Table Name)：准确填写存储了文档向量的完整表名。格式通常为 数据库名.模式名.表名，例如 clickzetta_sample_data.clickzetta_doc.kb_dashscope_clickzetta_elements。
    • 嵌入列 (Embedding Column)：填写该表中用于存储文本向量的列名，例如 embeddings。
    • 内容列 (Content Column)：填写该表中用于存储原始文本内容的列名，例如 text。当系统找到相关答案时，这里的内容会作为主要参考。
    • 其他列 (Other Columns)：可选。填写您希望一并检索出的元数据列，如 file_directory, filename，这有助于用户追溯信息的原始出处。

  3. 配置 搜索参数：保持默认即可，如果想进行修改，请参考下面的说明

    • 距离阈值 (Distance Threshold)：设置一个相似度匹配的严格程度。系统会计算问题向量与文档向量之间的“距离”，只有距离小于此值的文档才会被视为相关。值越小，代表匹配要求越严格。通常建议从 0.80 开始尝试。
    • 返回结果数 (Number of Results to Return)：定义单次查询从数据库中检索出的最相关文档的数量。例如，设置为 5 表示每次找出 5 个最相关的文档片段。
    • 启用重排序 (Enable Reranking)：勾选此项后，系统会对初步检索出的结果进行二次智能排序，以提高最准确答案出现在最前面的概率。

  4. 点击 保存向量搜索配置 按钮。

其他典型使用场景

请参考公众号文章：MCP Server 如何助力 Lakehouse 实现 AI 驱动的 6 大数据应用场景

我们期待与您一起探索 AI 驱动的数据分析新时代！

附录：

创建 docker-compose.yml 文件内容：

version: '3.8'
services:
  # HTTP协议服务
  clickzetta-http:
    image: czqiliang/mcp-clickzetta-server:latest
    container_name: clickzetta-http
    restart: unless-stopped
    ports:
      - "8002:8002"  # HTTP协议端口
    volumes:
      - ~/.clickzetta:/app/.clickzetta  # 配置文件挂载
    # 完全绕过uv，直接使用虚拟环境Python
    entrypoint: []
    command: ["/app/.venv/bin/python", "-m", "mcp_clickzetta_server","--transport","http", "--host", "0.0.0.0", "--port", "8002"]
    environment:
      - LOG_LEVEL=INFO
      - PYTHONUNBUFFERED=1
      - TZ=Asia/Shanghai  # 时区设置
    deploy:
      resources:
        limits:
          memory: 8G
          cpus: '4'
        reservations:
          memory: 512M
          cpus: '0.5'
    healthcheck:
      test: ["CMD", "curl", "-s", "http://localhost:8002/mcp"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s  # 增加到60秒，给HTTP预热5秒 + FastMCP启动时间
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"
    networks:
      - clickzetta-net
  # SSE协议服务
  clickzetta-sse:
    image: czqiliang/mcp-clickzetta-server:latest
    container_name: clickzetta-sse
    restart: unless-stopped
    ports:
      - "8003:8003"  # SSE协议端口
    volumes:
      - ~/.clickzetta:/app/.clickzetta  # 配置文件挂载
    # 完全绕过uv，直接使用虚拟环境Python
    entrypoint: []
    command: ["/app/.venv/bin/python", "-m", "mcp_clickzetta_server","--transport","sse", "--host", "0.0.0.0", "--port", "8003"]
    environment:
      - LOG_LEVEL=INFO
      - PYTHONUNBUFFERED=1
      - TZ=Asia/Shanghai  # 时区设置
    deploy:
      resources:
        limits:
          memory: 8G
          cpus: '4'
        reservations:
          memory: 512M
          cpus: '0.5'
    healthcheck:
      test: ["CMD", "curl", "-s", "http://localhost:8003/sse"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 120s  # 增加到120秒，给SSE更多启动时间
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"
    networks:
      - clickzetta-net
  
  # WebUI服务
  clickzetta-webui:
    image: czqiliang/mcp-clickzetta-server:latest
    container_name: clickzetta-webui
    restart: unless-stopped
    ports:
      - "8503:8501"  # WebUI端口
    volumes:
      - ~/.clickzetta:/app/.clickzetta  # 配置文件挂载
    # 直接启动Streamlit WebUI，绕过所有包装脚本
    entrypoint: []
    command: ["/bin/bash", "-c", "cd /app/streamlit_webui && /app/.venv/bin/python -m streamlit run app.py --server.port=8501 --server.address=0.0.0.0 --server.headless=true --browser.gatherUsageStats=false"]
    environment:
      - LOG_LEVEL=INFO
      - PYTHONUNBUFFERED=1
      - TZ=Asia/Shanghai  # 时区设置
      - PYTHONPATH=/app/src:/app/streamlit_webui/src
    working_dir: /app/streamlit_webui
    deploy:
      resources:
        limits:
          memory: 8G
          cpus: '4'
        reservations:
          memory: 512M
          cpus: '0.5'
    healthcheck:
      test: ["CMD", "curl", "-s", "http://localhost:8501"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"
    networks:
      - clickzetta-net

networks:
  clickzetta-net:
    driver: bridge
Lakehouse MCP Server
Dify中集成Lakehouse MCP Server
Yunqi © 2024 Yunqi, Inc. All Rights Reserved.

联系我们
预约咨询
微信咨询
电话咨询