Clickzetta MCP 服务器

概述

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

组件

资源

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

• memo://insights: 一个持续更新的数据洞察备忘录，聚合分析过程中发现的洞察
  • 通过 append-insight 工具发现新洞察时自动更新

工具

服务器提供六个核心工具：

查询工具

• read_query

  • 执行 SELECT 查询以从数据库读取数据
  • 输入：
    • query (string): 要执行的 SELECT SQL 查询
  • 返回：查询结果作为对象数组

• write_query (使用 --allow-write 标志)

  • 执行 INSERT、UPDATE 或 DELETE 查询
  • 输入：
    • query (string): SQL 修改查询
  • 返回：{ affected_rows: number }

• create_table (使用 --allow-write 标志)

  • 在数据库中创建新表
  • 输入：
    • query (string): CREATE TABLE SQL 语句
  • 返回：表创建确认

Schema 工具

• list_tables

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

• describe-table

  • 查看特定表的列信息
  • 输入：
    • table_name (string): 要描述的表的名称（可以是完全限定的）
  • 返回：包含名称和类型的列定义数组

分析工具

• append_insight
  • 将新的数据洞察添加到备忘录资源
  • 输入：
    • insight (string): 从分析中发现的数据洞察
  • 返回：洞察添加确认
  • 触发 memo://insights 资源的更新

与 Claude Desktop 一起使用

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

克隆此存储库：

git clone https://github.com/yunqiqiliang/mcp-clickzetta-server.git
cd mcp-clickzetta-server

安装软件包：

uv pip install -e .

配置凭据

基于 .env.example 创建一个 .env 文件，其中包含您的 Clickzetta Lakehouse 凭据：

CLICKZETTA_USERNAME = ""
CLICKZETTA_PASSWORD = ""
CLICKZETTA_SERVICE = "api.clickzetta.com"
CLICKZETTA_INSTANCE = ""
CLICKZETTA_WORKSPACE = ""
CLICKZETTA_SCHEMA = ""
CLICKZETTA_VCLUSTER = ""

用法

使用 uv 运行

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

uv run mcp_clickzetta_server

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

UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/ uv run mcp_clickzetta_server

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

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

uv run mcp_clickzetta_server

2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Starting Clickzetta MCP Server
2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Allow write operations: False
2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Prefetch table descriptions: True
2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Excluded tools: []
2025-03-25 10:11:20,799 - mcp_clickzetta_server - INFO - Prefetching table descriptions
2025-03-25 10:11:21,726 - clickzetta.zettapark.session - INFO - Zettapark Session information: 
"version" : 0.1.3,
"python.version" : 3.12.2,
"python.connector.version" : 0.8.89.0,
"python.connector.session.id" : dd46bd27-920d-4760-94a6-6f994d31e63e,
"os.name" : Darwin

2025-03-25 10:11:21,728 - clickzetta.connector.v0.client - INFO - clickzetta connector submitting job,  id:2025032510112172821098301
2025-03-25 10:11:23,059 - clickzetta.connector.v0.client - INFO - clickzetta connector submitting job,  id:2025032510112305897947697
2025-03-25 10:11:23,728 - mcp_clickzetta_server - INFO - Allowed tools: ['read_query', 'append_insight']
2025-03-25 10:11:23,732 - mcp_clickzetta_server - INFO - Server running with stdio transport

Claude Desktop 集成

• 在 Claude Desktop 中，转到 Settings → MCP Servers
• 添加一个新服务器，其中包含您的 uv 可执行文件的完整路径：

{
   "mcpServers": {
      "clickzetta-mcp-server" : {
         "command": "/Users/******/anaconda3/bin/uv",
         "args": [
            "--directory",
            "/Users/******/Documents/GitHub/mcp-clickzetta-server",
            "run",
            "mcp_clickzetta_server"
         ]
      }
   }
}

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

示例查询

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

• "Can you list all the schemas in my Clickzetta account?" (你能列出我的 Clickzetta 帐户中的所有 schema 吗？)
• "List all views in the PUBLIC schema" (列出 PUBLIC schema 中的所有视图)
• "Describe the structure of the CUSTOMER_ANALYTICS view in the SALES schema" (描述 SALES schema 中 CUSTOMER_ANALYTICS 视图的结构)
• "Show me sample data from the REVENUE_BY_REGION view in the FINANCE schema" (显示 FINANCE schema 中 REVENUE_BY_REGION 视图的示例数据)
• "Run this SQL query: SELECT customer_id, SUM(order_total) as total_spend FROM SALES.ORDERS GROUP BY customer_id ORDER BY total_spend DESC LIMIT 10" (运行此 SQL 查询：SELECT customer_id, SUM(order_total) as total_spend FROM SALES.ORDERS GROUP BY customer_id ORDER BY total_spend DESC LIMIT 10)
• "Query the MARKETING database to find the top 5 performing campaigns by conversion rate" (查询 MARKETING 数据库以查找转化率最高的 5 个广告系列)
• "帮我从Clickzetta中读取数据，分析下在public这个schema下github_users表里每个公司的用户数。请用中文返回结果，并对结果进行数据可视化展现" (请帮我从 Clickzetta 中读取数据，分析 public schema 下 github_users 表中每个公司的用户数。请用中文返回结果，并对结果进行数据可视化展示)
• "帮我从Clickzetta中读取数据，分析下在public这个schema下github_event_issuesevent表里有多少条记录？" (请帮我从 Clickzetta 中读取数据，分析 public schema 下 github_event_issuesevent 表中有多少条记录？)

示例结果

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

• The result of "帮我从Clickzetta中读取数据，分析下在public这个schema下github_users表里每个公司的用户数。请用中文返回结果，并对结果进行数据可视化展现": (“请帮我从 Clickzetta 中读取数据，分析 public schema 下 github_users 表中每个公司的用户数。请用中文返回结果，并对结果进行数据可视化展示”的结果：)

• The result of "帮我从Clickzetta中读取数据，分析下在public这个schema下github_users表里每个位置 的用户数。请用中文返回结果，并对结果进行数据可视化展现": ( “请帮我从 Clickzetta 中读取数据，分析 public schema 下 github_users 表中每个位置的用户数。请用中文返回结果，并对结果进行数据可视化展示”的结果：)

安全注意事项

此服务器：

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

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

要通过 Smithery 自动为 Claude Desktop 安装 Clickzetta Server：

npx -y @smithery/cli@latest install @yunqiqiliang/mcp-clickzetta-server --client claude --key ******

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

# Add the server to your claude_desktop_config.json
"mcpServers": {
  "clickzetta_pip": {
      "command": "uvx",
      "args": [
          "mcp_clickzetta_server",
          "--service",
          "the_service",
          "--instance",
          "the_instance",
          "--vcluster",
          "the_vcluster",
          "--workspace",
          "the_workspace",
           "--schema",
          "the_schema",
          "--user",
          "the_user",
          "--password",
          "their_password",
          # Optionally: "--allow_write" (but not recommended)
          # Optionally: "--log_dir", "/absolute/path/to/logs"
          # Optionally: "--log_level", "DEBUG"/"INFO"/"WARNING"/"ERROR"/"CRITICAL"
          # Optionally: "--exclude_tools", "{tool name}", ["{other tool name}"]
      ]
  }
}