Servidor MCP de Clickzetta

Descripción general

Una implementación de servidor de Protocolo de Contexto de Modelo (MCP) que permite la interacción con la base de datos de Clickzetta Lakehouse . Este servidor permite ejecutar consultas SQL con herramientas e interactuar con un memorando de información de datos presentado como un recurso.

Inicio rápido con MCP-ClickZetta-Server/Trae como su ingeniero de datos de IA

Descargar e instalar Trae

Descargue desde trae.ai e inicie sesión para habilitar el uso de IA.

Obtenga su cuenta ClickZetta

Extraer la imagen Docker de MCP-ClickZetta-Server

docker pull czqiliang/mcp-clickzetta-server

Agregar servidor MCP en Trae

En la ventana de chat de IA, haga clic en el ícono Configuración > MCP.
Aparecerá la ventana MCP.
Haga clic en el botón + Agregar.
Ingresarás al Marketplace de servidores MCP.
Haga clic en Configuración manual. Aparecerá la ventana Configuración manual. Añada un nuevo servidor MCP pegando la siguiente configuración JSON en el cuadro de entrada y haga clic en el botón Confirmar. El servidor MCP se añadirá a la lista de 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",
            "XINFERENCE_BASE_URL": "http://host.docker.internal:9998",
            "XINFERENCE_EMBEDDING_MODEL_512": "bge-small-zh",
            "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参数为必填
XINFERENCE开头的和Similar开头的env参数为可选，支持vector_search和match_all连个tools

Inicio rápido con MCP-ClickZetta-Server/Zettapark-MCP-Server/Claude Desktop como su ingeniero de datos de IA

Descargue e instale Claude Desktop

Descargue desde claude.ai e inicie sesión.

Obtenga su cuenta ClickZetta

Comience su laboratorio de Jupyter

Empezar por Docker Compose

crear carpeta

mkdir notebooks
cd notebooks

Cree el archivo config.json y configure su información de inicio de sesión como se muestra a continuación:

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

Aviso: De esta manera, configure el archivo config.json en la carpeta notebooks. Debe cambiar "query_tag" según sus necesidades, ya que se usa para buscar consultas por etiqueta.

Descargue docker-compose.yml e inicie Docker Compose

Descargue el archivo Docker Compose desde aquí

docker compose up -d

Vaya al escritorio de Docker y verifique que Docker Compose se haya iniciado.

Acceder al servidor de Jupyter Lab

http://localhost:8888/

Token: SU_TOKEN_SEGURO

Luego crea un nuevo cuaderno y cambia el nombre de Untitled.ipynb a notebook.ipynb.

O iniciar servidor local

# 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

Agregue el servidor MCP en su Claude Desktop

En Claude Desktop, vaya a Configuración → Desarrollador → Editar configuración
Abra claude_desktop_config.json y configure los servidores 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", "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",
            "XINFERENCE_BASE_URL": "http://host.docker.internal:9998",
            "XINFERENCE_EMBEDDING_MODEL_512": "bge-small-zh",
            "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'"
            }
      }
   }
}

Puede obtener información más detallada sobre Zettapark MCP Server desde aquí .

Componentes

Recursos

El servidor expone un único recurso dinámico:

memo://insights : un memorando de información de datos que se actualiza continuamente y que agrega información descubierta durante el análisis
- Se actualiza automáticamente a medida que se descubren nuevos conocimientos a través de la herramienta de anexar conocimientos.

Herramientas

El servidor ofrece las siguientes herramientas principales:

Herramientas de consulta

`read_query`

Descripción : Ejecutar consultas SELECT para leer datos de la base de datos.
Aporte :
- query (cadena): la consulta SQL SELECT que se ejecutará.
Devuelve : los resultados de la consulta como una matriz de objetos.

`write_query` (requiere el indicador `--allow-write` )

Descripción : Ejecuta consultas INSERT , UPDATE o DELETE para modificar datos.
Aporte :
- query (cadena): La consulta de modificación de SQL.
Devuelve : { affected_rows: number } , que indica la cantidad de filas afectadas.

`create_table` (requiere el indicador `--allow-write` )

Descripción : Crea nuevas tablas en la base de datos.
Aporte :
- query (cadena): instrucción SQL CREATE TABLE .
Devuelve : Confirmación de creación de la tabla.

`create_table_with_prompt` (requiere el indicador `--allow-write` )

Descripción : Crea una nueva tabla solicitando al usuario el nombre de la tabla, las columnas y sus tipos.
Aporte :
- table_name (cadena): el nombre de la tabla a crear.
- columns (cadena): Las columnas y sus tipos en el formato column1:type1,column2:type2 .
Devuelve : Confirmación de creación de la tabla.

Herramientas de esquema

`list_tables`

Descripción : Obtenga una lista de todas las tablas de la base de datos.
Entrada : No se requiere entrada.
Devuelve : una matriz de nombres de tablas.

`describe_table`

Descripción : Ver información de la columna de una tabla específica.
Aporte :
- table_name (cadena): Nombre de la tabla a describir (puede ser completo).
Devuelve : una matriz de definiciones de columnas con nombres y tipos.

`show_object_list`

Descripción : Obtenga la lista de tipos de objetos específicos en el espacio de trabajo actual, como catálogos, esquemas, tablas, etc.
Aporte :
- object_type (cadena): el tipo de objeto a mostrar.
Devuelve : Una lista de objetos.

`desc_object`

Descripción : Obtenga información detallada sobre un objeto específico, como un catálogo, un esquema o una tabla.
Aporte :
- object_type (cadena): el tipo del objeto.
- object_name (cadena): El nombre del objeto.
Devuelve : Información detallada sobre el objeto.

Herramientas de análisis

`append_insight`

Descripción : Agregue nuevos conocimientos de datos al recurso de notas.
Aporte :
- insight (cadena): información sobre los datos obtenida a partir del análisis.
Devoluciones : Confirmación de la adición de información.
Desencadenantes : actualiza el recurso memo://insights .

Herramientas de importación de datos

`import_data_into_table_from_url`

Descripción : Importa datos a una tabla desde una URL (incluidas rutas de archivo o URL HTTP/HTTPS). Si la tabla de destino no existe, se creará automáticamente.
Aporte :
- from_url (cadena): La URL de la fuente de datos.
- dest_table (cadena): la tabla a la que se importarán los datos.
Devuelve : Confirmación de importación exitosa de datos.

`import_data_into_table_from_database`

Descripción : Conéctese a una base de datos, ejecute una consulta e importe los resultados a una tabla de Clickzetta. Compatible con MySQL, PostgreSQL, SQLite y otros tipos de bases de datos comunes.
Aporte :
- db_type (cadena): el tipo de base de datos (por ejemplo, mysql , postgresql , sqlite ).
- host (cadena): el nombre de host o la dirección IP del servidor de base de datos (no requerido para SQLite).
- port (entero): el número de puerto del servidor de base de datos (no requerido para SQLite).
- database (cadena): el nombre de la base de datos a la que conectarse (para SQLite, esta es la ruta del archivo de base de datos).
- username (cadena): el nombre de usuario para la autenticación (no requerido para SQLite).
- password (cadena): la contraseña para la autenticación (no requerida para SQLite).
- source_table (cadena): el nombre de la tabla de origen.
- dest_table (cadena): el nombre de la tabla de destino.
Devuelve : Confirmación de importación exitosa de datos.

Herramientas de búsqueda similares

`vector_search`

Descripción : Realice una búsqueda vectorial en una tabla usando una pregunta y devuelva las 5 respuestas más cercanas.
Aporte :
- table_name (cadena): el nombre de la tabla.
- content_column_name (cadena): La columna que almacena el contenido.
- embedding_column_name (cadena): La columna que almacena las incrustaciones.
- partition_scope (cadena): código SQL para definir el alcance de la partición como parte de la condición WHERE .
- question (cadena): La pregunta a buscar.
Devuelve : Resultados de la búsqueda.

`match_all`

Descripción : Realice una búsqueda utilizando la función "coincidir con todos" en una tabla con una pregunta y devuelva las 5 principales respuestas.
Aporte :
- table_name (cadena): el nombre de la tabla.
- content_column_name (cadena): La columna que almacena el contenido.
- partition_scope (cadena): código SQL para definir el alcance de la partición como parte de la condición WHERE .
- question (cadena): La pregunta a buscar.
Devuelve : Resultados de la búsqueda.

Herramientas de búsqueda de conocimiento

`get_knowledge_about_how_to_do_something`

Descripción : Proporciona orientación sobre cómo realizar tareas específicas, como analizar consultas lentas, crear tablas o administrar conexiones de almacenamiento.
Aporte :
- to_do_something (cadena): La tarea a realizar. Las tareas admitidas incluyen:
  - 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
Devoluciones : Guía detallada sobre la tarea especificada.

Notas de uso

Asegúrese de que la marca --allow-write esté habilitada al utilizar herramientas que modifican datos (por ejemplo, write_query , create_table ).
Proporcione los parámetros de entrada correctos para cada herramienta como se describe anteriormente.

Uso con Claude Desktop

Instalación como servidor MCP local (este método ha sido probado y verificado en MacOS)

Clonar este repositorio:

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

Instalar el paquete:

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

Credenciales de configuración

Cree un archivo .env basado en .env.example con sus credenciales de Clickzetta Lakehouse:

CLICKZETTA_USERNAME = ""
CLICKZETTA_PASSWORD = ""
CLICKZETTA_SERVICE = "api.clickzetta.com"
CLICKZETTA_INSTANCE = ""
CLICKZETTA_WORKSPACE = ""
CLICKZETTA_SCHEMA = ""
CLICKZETTA_VCLUSTER = ""
XINFERENCE_BASE_URL = "http://********:9998"
XINFERENCE_EMBEDDING_MODEL_512 = "bge-small-zh"
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'"

Uso

Corriendo con uv

Después de instalar el paquete, puede ejecutar el servidor directamente con:

uv run mcp_clickzetta_server

Si es la primera vez que ejecuta el servidor, puede ejecutar el siguiente comando para acelerar la instalación del paquete:

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

Esto iniciará el servidor MCP basado en stdio, que se puede conectar a Claude Desktop o a cualquier cliente MCP que admita la comunicación stdio.

Debería ver un resultado similar a este:

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

Integración de escritorio de Claude

comando:docker

El servidor MCP (que se ejecuta en Docker) lee su configuración de las variables de entorno transferidas mediante la configuración del cliente MCP (p. ej., claude_desktop_config.json ). Variables clave:

{
   "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",
            "XINFERENCE_BASE_URL": "http://host.docker.internal:9998",
            "XINFERENCE_EMBEDDING_MODEL_512": "bge-small-zh",
            "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'"
            }
      }
}

comando:uv

En Claude Desktop, vaya a Configuración → Servidores MCP
Agregue un nuevo servidor con la ruta completa a su ejecutable uv:

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

Puedes encontrar tu ruta uv ejecutando which uv en tu terminal
Guardar la configuración del servidor

Consultas de ejemplo

Al usar Claude, puedes hacer preguntas como:

"¿Puedes enumerar todos los esquemas en mi cuenta de Clickzetta?"
"Enumerar todas las vistas en el esquema PÚBLICO"
"Describa la estructura de la vista CUSTOMER_ANALYTICS en el esquema SALES"
"Muéstrame datos de muestra de la vista INGRESOS POR REGIÓN en el esquema FINANZAS"
Ejecute esta consulta SQL: SELECT customer_id, SUM(order_total) as total_spend FROM SALES.ORDERS GROUP BY customer_id ORDER BY total_spend DESC LIMIT 10
Consulta la base de datos de MARKETING para encontrar las 5 campañas con mejor rendimiento según su tasa de conversión.
"帮我从Clickzetta中读取数据，分析下在public这个schema下git "hub_users"
"帮我从Clickzetta中读取数据，分析下在public这个schema下github_event_issuesevent表里有多少条记录？"

Ejemplo de resultado

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

El resultado de "帮我从Clickzetta中读取数据，分析下在public这个schema下gith ub_users表里每个公司的用户数。请用中文返回结果，并对结果进行数据可视化展现":

El resultado de "帮我从Clickzetta中读取数据，分析下在public这个schema下github_users表里每个位置"

Consideraciones de seguridad

Este servidor:

Aplica operaciones de solo lectura (solo se permiten declaraciones SELECT)
Agrega automáticamente cláusulas LIMIT para evitar conjuntos de resultados grandes
Utiliza la autenticación de cuenta de servicio para conexiones seguras
Valida las entradas para evitar la inyección de SQL
⚠️ Importante: Mantén tu archivo .env seguro y nunca lo envíes al control de versiones. El archivo .gitignore está configurado para excluirlo.

Instalación mediante Smithery (este método debe probarse y verificarse)

Para instalar Clickzetta Server para Claude Desktop automáticamente a través de Smithery :

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

Instalación mediante UVX (este método debe probarse y verificarse)

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

Integrations