Clickzetta MCP Server

Clickzetta MCP 服务器

概述

模型上下文协议 (MCP) 服务器实现，提供与Clickzetta Lakehouse的数据库交互。该服务器支持使用工具运行 SQL 查询，并与作为资源呈现的数据洞察备忘录进行交互。

使用 MCP-ClickZetta-Server/Trae 快速开始作为您的 AI 数据工程师

下载并安装 Trae

从 trae.ai 下载并登录以启用 AI。

获取您的 ClickZetta 帐户

获取您的 ClickZetta 帐户

拉取 MCP-ClickZetta-Server Docker 镜像

在 Trae 中添加 MCP 服务器

• 在AI聊天窗口中，单击设置图标> MCP。
• MCP 窗口将会出现。
• 单击 + 添加按钮。
• 您将进入 MCP 服务器市场。
• 点击“手动配置”。系统将弹出“手动配置”窗口。将以下 JSON 配置粘贴到输入框中，添加一个新的 MCP 服务器，然后点击“确认”按钮。该 MCP 服务器将被添加到 MCP 列表中。

• CLICKZETTA 底层的环境参数为必填
• XINFERENCE 开头和相似开头的env参数为可选，支持vector_search和match_all连个工具

使用 MCP-ClickZetta-Server/Zettapark-MCP-Server/Claude Desktop 快速开始作为您的 AI 数据工程师

下载并安装 Claude Desktop

从 claude.ai 下载并登录。

获取您的 ClickZetta 帐户

获取您的 ClickZetta 帐户

启动你的 Jupyter 实验室

从 Docker Compose 开始

• 创建文件夹

• 创建 config.json 文件并设置您的登录信息如下：

注意：使用这种方法，请在 Notebooks 文件夹中设置 config.json 文件。您应该根据自己的目的更改 query_tag，它用于通过标签查找查询。

• 下载docker-compose.yml并启动docker compose

从这里下载docker compose文件

转到 Docker 桌面并检查 docker compose 是否已启动。

• 访问 Jupyter Lab 服务器

http://localhost:8888/

令牌： YOUR_SECURE_TOKEN

然后创建一个新的笔记本，将名称从 Untitled.ipynb 更改为 Notebook.ipynb 。

或者启动本地服务器

在您的 Claude Desktop 中添加 MCP 服务器

• 在 Claude Desktop 中，转到“设置”→“开发人员”→“编辑配置”
• 打开 claude_desktop_config.json 并配置 MCP 服务器

您可以从这里获取有关 Zettapark MCP 服务器的更多详细信息。

成分

资源

服务器公开单个动态资源：

• memo://insights ：持续更新的数据洞察备忘录，汇总分析过程中发现的洞察
  • 通过附加洞察工具发现新见解时自动更新

工具

该服务器提供以下核心工具：

查询工具

read_query

• 描述：执行SELECT查询以从数据库读取数据。
• 输入：
  • query （字符串）：要执行的SELECT SQL 查询。
• 返回：查询结果作为对象数组。

write_query （需要--allow-write标志）

• 描述：执行INSERT 、 UPDATE或DELETE查询来修改数据。
• 输入：
  • query （字符串）：SQL 修改查询。
• 返回： { affected_rows: number } ，表示受影响的行数。

create_table （需要--allow-write标志）

• 描述：在数据库中创建新表。
• 输入：
  • query （字符串）： CREATE TABLE SQL 语句。
• 返回：表创建的确认。

create_table_with_prompt （需要--allow-write标志）

• 描述：通过提示用户输入表名、列及其类型来创建新表。
• 输入：
  • table_name （字符串）：要创建的表的名称。
  • columns （字符串）：列及其类型，格式为column1:type1,column2:type2 。
• 返回：表创建的确认。

架构工具

list_tables

• 描述：获取数据库中所有表的列表。
• 输入：无需输入。
• 返回：表名数组。

describe_table

• 描述：查看特定表的列信息。
• 输入：
  • table_name （字符串）：要描述的表的名称（可以完全限定）。
• 返回：具有名称和类型的列定义数组。

show_object_list

• 描述：获取当前工作区中特定对象类型的列表，例如目录、模式、表等。
• 输入：
  • object_type （字符串）：要显示的对象的类型。
• 返回：对象列表。

desc_object

• 描述：获取有关特定对象（例如目录、模式或表）的详细信息。
• 输入：
  • object_type （字符串）：对象的类型。
  • object_name （字符串）：对象的名称。
• 返回：有关对象的详细信息。

分析工具

append_insight

• 描述：向备忘录资源添加新的数据见解。
• 输入：
  • insight （字符串）：从分析中发现的数据洞察。
• 返回：洞察力增加的确认。
• 触发器：更新memo://insights资源。

数据导入工具

import_data_into_table_from_url

• 描述：从 URL（包括文件路径或 HTTP/HTTPS URL）导入数据到表中。如果目标表不存在，则会自动创建。
• 输入：
  • from_url （字符串）：数据源 URL。
  • dest_table （字符串）：要导入数据的表。
• 返回：数据导入成功确认。

import_data_into_table_from_database

• 描述：连接到数据库，执行查询，并将结果导入 Clickzetta 表。支持 MySQL、PostgreSQL、SQLite 和其他常见数据库类型。
• 输入：
  • db_type (字符串)：数据库的类型（例如， mysql 、 postgresql 、 sqlite ）。
  • host （字符串）：数据库服务器的主机名或 IP 地址（SQLite 不需要）。
  • port （整数）：数据库服务器的端口号（SQLite 不需要）。
  • database （字符串）：要连接的数据库的名称（对于 SQLite，这是数据库文件的文件路径）。
  • username （字符串）：用于身份验证的用户名（SQLite 不需要）。
  • password （字符串）：用于身份验证的密码（SQLite 不需要）。
  • source_table （字符串）：源表名称。
  • dest_table （字符串）：目标表名称。
• 返回：数据导入成功确认。

类似的搜索工具

vector_search

• 描述：使用问题对表执行向量搜索并返回前 5 个最接近的答案。
• 输入：
  • table_name （字符串）：表名。
  • content_column_name （字符串）：存储内容的列。
  • embedding_column_name （字符串）：存储嵌入的列。
  • partition_scope （字符串）：将分区范围定义为WHERE条件的一部分的 SQL 代码。
  • question （字符串）：要搜索的问题。
• 返回：搜索结果。

match_all

• 描述：使用“全部匹配”功能对包含问题的表格执行搜索并返回前 5 个答案。
• 输入：
  • table_name （字符串）：表名。
  • content_column_name （字符串）：存储内容的列。
  • partition_scope （字符串）：将分区范围定义为WHERE条件的一部分的 SQL 代码。
  • question （字符串）：要搜索的问题。
• 返回：搜索结果。

知识搜索工具

get_knowledge_about_how_to_do_something

• 描述：提供有关如何执行特定任务的指导，例如分析慢查询、创建表或管理存储连接。
• 输入：
  • to_do_something (字符串)：要执行的任务。支持的任务包括：
    • analyze_slow_query
    • analyze_table_with_small_file
    • create_table_syntax
    • how_to_create_vcluster
    • how_to_create_index
    • how_to_alter_table_and_column
    • how_to_create_storage_connection
    • how_to_create_external_volume
• 返回：有关指定任务的详细指导。

使用说明

• 确保使用修改数据的工具（例如write_query 、 create_table ）时启用--allow-write标志。
• 按照上述说明为每个工具提供正确的输入参数。

与 Claude Desktop 一起使用

安装为本地 MCP 服务器（此方式已在 MacOS 上测试验证）

克隆此存储库：

安装软件包：

配置凭证

使用您的 Clickzetta Lakehouse 凭证根据 .env.example 创建 .env 文件：

用法

用紫外线运行

安装软件包后，您可以直接使用以下命令运行服务器：

如果这是您第一次运行服务器，您可以运行以下命令来加速软件包安装：

这将启动基于 stdio 的 MCP 服务器，该服务器可以连接到 Claude Desktop 或任何支持 stdio 通信的 MCP 客户端。

您应该看到类似以下内容的输出：

Claude 桌面集成

MCP 服务器（在 Docker 中运行）从 MCP 客户端配置（例如claude_desktop_config.json ）传递的环境变量中读取其配置。关键变量：

• 在 Claude Desktop 中，前往“设置”→“MCP 服务器”
• 添加一个具有 uv 可执行文件完整路径的新服务器：

• 您可以在终端中运行 which uv 来找到您的 uv 路径
• 保存服务器配置

示例查询

与 Claude 一起使用时，您可以提出以下问题：

• “您能列出我的 Clickzetta 帐户中的所有模式吗？”
• “列出 PUBLIC 模式中的所有视图”
• “描述 SALES 模式中 CUSTOMER_ANALYTICS 视图的结构”
• “显示 FINANCE 模式中 REVENUE_BY_REGION 视图的示例数据”
• “运行此 SQL 查询：SELECT customer_id, SUM(order_total) as total_spend FROM SALES.ORDERS GROUP BY customer_id ORDER BY total_spend DESC LIMIT 10”
• “查询 MARKETING 数据库，按转化率找出表现最好的 5 个营销活动”
• “帮助我从Clickzetta中读取数据，在公共这个schema下github_users表里每个公司的用户数据进行分析。请用中文返回结果，公开结果进行数据可视化实验”
• “帮我从Clickzetta中读取数据，分析下在公共这个schema下github_event_issues事件表里有多少条记录？”

示例结果

• '帮我从Clickzetta数据源中读取数据，先分析基于public这个schema下github_users表里的数据可以做哪些分析？包括指标、统计、趋势、以及各种经典的用户分析模型比如用户价值分析、用户生命周期分析、用户细分等，然后根据这些分析内容生成一个分析报告的仪表盘'

• “帮我从Clickzetta中读取数据，分析下在公共这个schema下github_users表里每个公司的用户数据。请用中文返回结果，公开结果进行数据可视化”的结果：

• “帮我从Clickzetta中读取数据，分析下在公共这个schema下github_users表里每个位置的用户数。请用中文返回结果，可视化结果进行数据可视化显示”的结果：

安全注意事项

该服务器：

• 强制执行只读操作（仅允许 SELECT 语句）
• 自动添加 LIMIT 子句以防止结果集过大
• 使用服务帐户身份验证实现安全连接
• 验证输入以防止 SQL 注入
• ⚠️ 重要提示：请确保你的 .env 文件安全，切勿将其提交到版本控制中。.gitignore 文件已配置为将其排除。

通过 Smithery 安装（此方式有待测试和验证）

要通过Smithery自动为 Claude Desktop 安装 Clickzetta 服务器：

通过UVX安装（此方式有待测试和验证）