Сервер Clickzetta MCP

Обзор

Реализация сервера Model Context Protocol (MCP), которая обеспечивает взаимодействие базы данных с Clickzetta Lakehouse . Этот сервер позволяет выполнять SQL-запросы с инструментами и взаимодействовать с меморандумом о данных, представленным в виде ресурса.

Быстрый старт с MCP-ClickZetta-Server/Trae в качестве инженера по обработке данных ИИ

Загрузите и установите Trae

Загрузите с trae.ai и войдите в систему, чтобы включить использование ИИ.

Получите свою учетную запись ClickZetta

Извлечь образ MCP-ClickZetta-Server Docker

docker pull czqiliang/mcp-clickzetta-server

Добавить MCP-сервер в Trae

В окне чата AI нажмите значок «Настройки» > MCP.
Появится окно MCP.
Нажмите кнопку + Добавить.
Вы попадете на рынок серверов MCP.
Нажмите Manual Configuration. Появится окно Manual Configuration. Добавьте совершенно новый сервер MCP, вставив следующую конфигурацию JSON в поле ввода, затем нажмите кнопку Confirm. Сервер MCP будет добавлен в список MCP.

{
   "mcpServers": {
      "clickzetta-mcp-server": {
         "command": "docker",
         "args": [
            "run",
            "-i", 
            "--rm", 
            "-e", "LOG_LEVEL=INFO", 
            "-e", "CLICKZETTA_SERVICE", 
            "-e", "CLICKZETTA_INSTANCE",
            "-e", "CLICKZETTA_WORKSPACE",
            "-e", "CLICKZETTA_SCHEMA",
            "-e", "CLICKZETTA_USERNAME",
            "-e", "CLICKZETTA_PASSWORD",
            "-e", "CLICKZETTA_VCLUSTER",
            "-e", "XINFERENCE_BASE_URL",
            "-e", "XINFERENCE_EMBEDDING_MODEL_512",
            "-e", "Similar_table_name",
            "-e", "Similar_embedding_column_name",
            "-e", "Similar_content_column_name",
            "-e", "Similar_partition_scope",
            "czqiliang/mcp-clickzetta-server:latest" 
         ],
         "env": {
            "CLICKZETTA_SERVICE": "api.clickzetta.com", 
            "CLICKZETTA_INSTANCE": "your clickzetta instance", 
            "CLICKZETTA_WORKSPACE": "your clickzetta workspace" ,
            "CLICKZETTA_SCHEMA": "your clickzetta schema",
            "CLICKZETTA_USERNAME": "your clickzetta usename",
            "CLICKZETTA_PASSWORD": "your clickzetta password",
            "CLICKZETTA_VCLUSTER": "your clickzetta vcluster",
            "Similar_table_name": "clickzegithub_event_issuesevent_embedding.github_event_issuesevent_embedding_512tta_table",
            "Similar_embedding_column_name": "issue_body_embedding",
            "Similar_content_column_name": "issue_body",
            "Similar_partition_scope": "partition_date  >= '2024-01-01' and partition_date  <= '2024-01-15'"
            }
      }
   }
}

CLICKZETTA и env-файлы в формате CLICKZETTA

Быстрый старт с MCP-ClickZetta-Server/Zettapark-MCP-Server/Claude Desktop в качестве инженера по обработке данных ИИ

Загрузите и установите Claude Desktop

Загрузите с claude.ai и войдите в систему.

Получите свою учетную запись ClickZetta

Начните свою лабораторию Jupyter

Начать с Docker Compose

создать папку

mkdir notebooks
cd notebooks

Создайте файл config.json и укажите данные для входа, как показано ниже:

{
    "username": "your clickzetta lakehouse user name",
    "password": "your clickzetta lakehouse password",
    "service": "api.clickzetta.com",
    "instance": "your clickzetta lakehouse instance name",
    "workspace": "your clickzetta lakehouse workspac name",
    "schema": "your clickzetta lakehouse schema",
    "vcluster": "your clickzetta lakehouse vcluster name",
    "sdk_job_timeout": 60,
    "hints": {
      "sdk.job.timeout": 60,
      "query_tag": "test_zettapark_vector_ns227206",
      "cz.storage.parquet.vector.index.read.memory.cache": "true",
      "cz.storage.parquet.vector.index.read.local.cache": "false",
      "cz.sql.table.scan.push.down.filter": "true",
      "cz.sql.table.scan.enable.ensure.filter": "true",
      "cz.storage.always.prefetch.internal": "true",
      "cz.optimizer.generate.columns.always.valid": "true",
      "cz.sql.index.prewhere.enabled": "true",
      "cz.storage.parquet.enable.io.prefetch": "false"
    }
  }

Примечание: Таким образом, пожалуйста, установите файл config.json в папке notebooks. Вам следует изменить query_tag для ваших целей, и он будет использоваться для поиска запроса по тегу.

Загрузите docker-compose.yml и запустите docker compose

Загрузите файл docker compose отсюда

docker compose up -d

Перейдите на рабочий стол Docker и проверьте, запущен ли Docker Compose.

Доступ к серверу Jupyter Lab

http://localhost:8888/

Токен: YOUR_SECURE_TOKEN

Затем создайте новый блокнот, измените имя с Untitled.ipynb на notebook.ipynb.

Или запустить локальный сервер

# Create a clean environment (Python 3.10 worked during debugging)
conda create -n jupyter_mcp_env python=3.10 -y

# Activate the environment
conda activate jupyter_mcp_env

# Use 'python -m pip' to ensure correct pip in the activated env
python -m pip install jupyterlab ipykernel

# Install the required v2.0.1
python -m pip install "jupyter_collaboration==2.0.1"

# Uninstall potentially conflicting versions
python -m pip uninstall -y pycrdt datalayer_pycrdt

# Install the required version
python -m pip install datalayer_pycrdt

jupyter server extension enable jupyter_collaboration --py --sys-prefix

# Start JupyterLab, please keep token as YOUR_SECURE_TOKEN
jupyter lab --port 8888 --IdentityProvider.token YOUR_SECURE_TOKEN --ip 0.0.0.0

Добавьте MCP-сервер в свой Claude Desktop

В Claude Desktop перейдите в Настройки → Разработчик → Изменить конфигурацию.
Откройте claude_desktop_config.json и настройте серверы MCP.

{
   "mcpServers": {

      "jupyter": {
         "command": "docker",
      "args": [
        "run",
        "-i", 
        "--rm", 
        "-e", "SERVER_URL", 
        "-e", "TOKEN",
        "-e", "NOTEBOOK_PATH",
        "-e", "LOG_LEVEL=INFO", 
        "czqiliang/jupyter-mcp-server:latest" 
      ],
      "env": {
        "SERVER_URL": "http://host.docker.internal:8888", 
        "TOKEN": "YOUR_SECURE_TOKEN", 
        "NOTEBOOK_PATH": "notebook.ipynb" 
         }
      },
      "clickzetta-mcp-server": {
         "command": "docker",
         "args": [
            "run",
            "-i", 
            "--rm", 
            "-e", "LOG_LEVEL=INFO", 
            "-e", "CLICKZETTA_SERVICE", 
            "-e", "CLICKZETTA_INSTANCE",
            "-e", "CLICKZETTA_WORKSPACE",
            "-e", "CLICKZETTA_SCHEMA",
            "-e", "CLICKZETTA_USERNAME",
            "-e", "CLICKZETTA_PASSWORD",
            "-e", "CLICKZETTA_VCLUSTER",
            "-e", "Similar_table_name",
            "-e", "Similar_embedding_column_name",
            "-e", "Similar_content_column_name",
            "-e", "Similar_partition_scope",
            "czqiliang/mcp-clickzetta-server:latest" 
         ],
         "env": {
            "CLICKZETTA_SERVICE": "api.clickzetta.com", 
            "CLICKZETTA_INSTANCE": "your clickzetta instance", 
            "CLICKZETTA_WORKSPACE": "your clickzetta workspace" ,
            "CLICKZETTA_SCHEMA": "your clickzetta schema",
            "CLICKZETTA_USERNAME": "your clickzetta usename",
            "CLICKZETTA_PASSWORD": "your clickzetta password",
            "CLICKZETTA_VCLUSTER": "your clickzetta vcluster",
            "Similar_table_name": "clickzegithub_event_issuesevent_embedding.github_event_issuesevent_embedding_512tta_table",
            "Similar_embedding_column_name": "issue_body_embedding",
            "Similar_content_column_name": "issue_body",
            "Similar_partition_scope": "partition_date  >= '2024-01-01' and partition_date  <= '2024-01-15'"
            }
      }
   }
}

Более подробную информацию о Zettapark MCP Server вы можете получить здесь .

Компоненты

Ресурсы

Сервер предоставляет один динамический ресурс:

memo://insights : постоянно обновляемая записка с аналитическими данными, которая объединяет обнаруженные аналитические данные в ходе анализа.
- Автоматические обновления по мере обнаружения новых аналитических данных с помощью инструмента append-insight

Инструменты

Сервер предлагает следующие основные инструменты:

Инструменты запроса

`read_query`

Описание : Выполнение запросов SELECT для чтения данных из базы данных.
Вход :
- query (строка): SQL-запрос SELECT для выполнения.
Возвращает : результаты запроса в виде массива объектов.

`write_query` (требуется флаг `--allow-write` )

Описание : Выполнение запросов INSERT , UPDATE или DELETE для изменения данных.
Вход :
- query (строка): запрос на модификацию SQL.
Возвращает : { affected_rows: number } , что указывает количество затронутых строк.

`create_table` (требуется флаг `--allow-write` )

Описание : Создание новых таблиц в базе данных.
Вход :
- query (строка): SQL-оператор CREATE TABLE .
Возврат : Подтверждение создания таблицы.

`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`

Описание : Добавьте новые аналитические данные в ресурс Memo.
Вход :
- 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 (строка): Имя целевой таблицы.
Возврат : Подтверждение успешного импорта данных.

Инструменты поиска знаний

`get_knowledge_about_how_to_do_something`

Описание : Дайте рекомендации по выполнению определенных задач, таких как анализ медленных запросов, создание таблиц или управление подключениями к хранилищу.
Вход :
- to_do_something (string): Задача для выполнения. Поддерживаемые задачи включают:
  - 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)

Клонируйте этот репозиторий:

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

Установите пакет:

uv pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple/

Конфигурация учетных данных

Создайте файл .env на основе .env.example с вашими учетными данными Clickzetta Lakehouse:

CLICKZETTA_USERNAME = ""
CLICKZETTA_PASSWORD = ""
CLICKZETTA_SERVICE = "api.clickzetta.com"
CLICKZETTA_INSTANCE = ""
CLICKZETTA_WORKSPACE = ""
CLICKZETTA_SCHEMA = ""
CLICKZETTA_VCLUSTER = ""
Similar_table_name = "github_event_issuesevent_embedding.github_event_issuesevent_embedding_512"
Similar_embedding_column_name = "issue_body_embedding"
Similar_content_column_name = "issue_body"
Similar_partition_scope = "partition_date  >= '2024-01-01' and partition_date  <= '2024-01-15'"

Использование

Работает с уф

После установки пакета вы можете запустить сервер напрямую с помощью:

uv run mcp_clickzetta_server

Если вы запускаете сервер впервые, вы можете выполнить следующую команду, чтобы ускорить установку пакета:

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

Это запустит сервер MCP на базе stdio, который можно подключить к Claude Desktop или любому клиенту MCP, поддерживающему связь stdio.

Вы должны увидеть примерно такой вывод:

uv run mcp_clickzetta_server --no-prefetch

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

Интеграция рабочего стола Клода

команда:докер

Сервер MCP (работающий в Docker) считывает свою конфигурацию из переменных среды, переданных через конфигурацию клиента MCP (например, claude_desktop_config.json ). Ключевые переменные:

{
   "clickzetta-mcp-server": {
         "command": "docker",
         "args": [
            "run",
            "-i", 
            "--rm", 
            "-e", "LOG_LEVEL=INFO", 
            "-e", "CLICKZETTA_SERVICE", 
            "-e", "CLICKZETTA_INSTANCE",
            "-e", "CLICKZETTA_WORKSPACE",
            "-e", "CLICKZETTA_SCHEMA",
            "-e", "CLICKZETTA_USERNAME",
            "-e", "CLICKZETTA_PASSWORD",
            "-e", "CLICKZETTA_VCLUSTER",
            "-e", "Similar_table_name",
            "-e", "Similar_embedding_column_name",
            "-e", "Similar_content_column_name",
            "-e", "Similar_partition_scope",
            "czqiliang/mcp-clickzetta-server:latest" 
         ],
         "env": {
            "CLICKZETTA_SERVICE": "api.clickzetta.com", 
            "CLICKZETTA_INSTANCE": "your clickzetta instance", 
            "CLICKZETTA_WORKSPACE": "your clickzetta workspace" ,
            "CLICKZETTA_SCHEMA": "your clickzetta schema",
            "CLICKZETTA_USERNAME": "your clickzetta usename",
            "CLICKZETTA_PASSWORD": "your clickzetta password",
            "CLICKZETTA_VCLUSTER": "your clickzetta vcluster",
            "Similar_table_name": "clickzegithub_event_issuesevent_embedding.github_event_issuesevent_embedding_512tta_table",
            "Similar_embedding_column_name": "issue_body_embedding",
            "Similar_content_column_name": "issue_body",
            "Similar_partition_scope": "partition_date  >= '2024-01-01' and partition_date  <= '2024-01-15'"
            }
      }
}

команда:uv

В Claude Desktop перейдите в Настройки → Серверы MCP.
Добавьте новый сервер с полным путем к исполняемому файлу uv:

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

Вы можете узнать свой UV-путь, запустив which uv в терминале.
Сохраните конфигурацию сервера

Примеры запросов

При использовании Клода вы можете задавать такие вопросы:

«Можете ли вы перечислить все схемы в моем аккаунте Clickzetta?»
«Список всех представлений в схеме PUBLIC»
«Опишите структуру представления CUSTOMER_ANALYTICS в схеме SALES»
«Покажите мне пример данных из представления REVENUE_BY_REGION в схеме FINANCE»
"Выполните этот SQL-запрос: SELECT customer_id, SUM(order_total) as total_spend FROM SALES.ORDERS GROUP BY customer_id ORDER BY total_spend DESC LIMIT 10"
«Сделать запрос к базе данных МАРКЕТИНГА, чтобы найти 5 самых эффективных кампаний по коэффициенту конверсии»
"帮我从Clickzetta中读取数据，分析下在public这个schema下git Hub_users может использовать только один из них, например, в режиме Hub_users.
"帮我从Clickzetta中读取数据，分析下在public这个schema下github_event_issuesevent表里有多少条记录？"

Пример результата

'帮我从Clickzetta数据源中读取数据，先分析基于public 个s chema下github_users 表里的数据可以做哪些分析？包括指标、统计、趋势、以及各种经典的用户分析模型比如用户价值分析、用户生命周期分析、用户сегментная 等, 然后根据这些分析内容生成一个分析报告的dashboard'

Результат "帮我从Clickzetta中读取数据，分析下在public这个schema下gith ub_users использует функцию ub_users, которая позволяет установить пользовательский интерфейс, установить пользовательский интерфейс":

Результат «帮我从Clickzetta中读取数据，分析下在public这个schema下github_users表里每个位置的用户数。请用中文返回结果，并对结果进行数据可视化展现":

Соображения безопасности

Этот сервер:

Обеспечивает выполнение операций только для чтения (разрешены только операторы SELECT)
Автоматически добавляет предложения LIMIT для предотвращения больших наборов результатов
Использует аутентификацию учетной записи службы для безопасных соединений
Проверяет входные данные для предотвращения SQL-инъекций
⚠️ Важно: храните файл .env в безопасности и никогда не передавайте его в систему контроля версий. Файл .gitignore настроен на его исключение.

Установка через Smithery (Этот способ должен быть протестирован и проверен)

Чтобы автоматически установить Clickzetta Server для Claude Desktop через Smithery :

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}"]
      ]
  }
}

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Сервер Model Context Protocol, который обеспечивает взаимодействие базы данных с Clickzetta, позволяя пользователям выполнять SQL-запросы, управлять таблицами и поддерживать динамически обновляемую памятку по анализу данных.

Related MCP Servers

MySQL-MCP
zajTools
-
security
F
license
-
quality
A Model Context Protocol server that enables SQL query execution, database management, and business intelligence capabilities through MySQL connections.
Last updated -
JavaScript
SQLite MCP Server
jacksteamdev
A
security
A
license
A
quality
A Model Context Protocol server that provides database interaction capabilities through SQLite, enabling users to run SQL queries, analyze business data, and automatically generate business insight memos.
Last updated -
6
9
TypeScript
MIT License
Database MCP Server
georgi-terziyski
-
security
-
license
-
quality
A Model Context Protocol server that provides tools for connecting to and interacting with various database systems (SQLite, PostgreSQL, MySQL/MariaDB, SQL Server) through a unified interface.
Last updated -
Python
SQLite MCP Server
isaacgounton
-
security
F
license
-
quality
A Model Context Protocol server that enables SQL operations (SELECT, INSERT, UPDATE, DELETE) and table management through a standardized interface with SQLite databases.
Last updated -
JavaScript

View all related MCP servers

Appeared in Searches

ClickHouse: A fast open-source columnar database management system