项目简介 Altinity ClickHouse MCP服务器是一个功能强大的后端服务，专为集成ClickHouse数据库与大型语言模型（LLM）应用而设计。它实现了Model Context Protocol (MCP)，允许LLM客户端以标准化的方式访问ClickHouse数据、执行SQL操作，并通过动态工具和资源管理简化数据交互。

主要功能点

多协议支持: 支持STDIO、HTTP和Server-Sent Events (SSE) 等多种传输协议，灵活适应不同的部署和集成场景。
安全认证: 提供可选的JWE (JSON Web Encryption) 认证机制和TLS加密支持，确保数据库访问和数据传输的安全性。
丰富的数据库工具: 内置查询执行、表信息列表、模式描述等工具，简化对ClickHouse数据库的操作。
动态工具生成: 能够自动从ClickHouse视图生成MCP工具，实现高度可定制和扩展的功能。
数据库资源发现: 自动发现并提供ClickHouse数据库的模式信息和详细表结构资源。
配置灵活与热加载: 支持通过配置文件、环境变量和CLI参数进行灵活配置，并支持运行时热加载配置，无需重启服务。
OpenAPI集成: 暴露OpenAPI兼容的端点，便于与OpenAI GPTs等AI平台无缝集成。

安装步骤 以下是一些常见的安装和部署方式。请根据您的环境选择最合适的方式。

使用Docker (推荐):

docker run -it --rm ghcr.io/altinity/altinity-mcp:latest --clickhouse-host your_clickhouse_host --clickhouse-port 8123

注意: 替换 'your_clickhouse_host' 为您的ClickHouse服务器地址。

使用Helm (Kubernetes): 从OCI Helm注册表安装（推荐）：

helm install altinity-mcp oci://ghcr.io/altinity/altinity-mcp/helm/altinity-mcp \
  --set config.clickhouse.host=your_clickhouse_host \
  --set config.clickhouse.database=default \
  --set config.clickhouse.limit=5000

注意: 替换 'your_clickhouse_host' 为您的ClickHouse服务器地址。

从源代码构建:

git clone https://github.com/altinity/altinity-mcp.git
cd altinity-mcp
go build -o altinity-mcp ./cmd/altinity-mcp
./altinity-mcp --clickhouse-host your_clickhouse_host --clickhouse-port 8123

注意: 替换 'your_clickhouse_host' 为您的ClickHouse服务器地址。

MCP客户端配置示例 MCP客户端需要配置与MCP服务器通信的启动命令和参数。以下是一个使用CLI参数启动HTTP传输协议的MCP服务器的配置信息。

{
  "server_name": "Altinity ClickHouse MCP Server",
  "command": "altinity-mcp",
  "args": [
    "--transport", "http",
    "--address", "0.0.0.0",
    "--port", "8080",
    "--clickhouse-host", "your_clickhouse_host",
    "--clickhouse-port", "8123",
    "--clickhouse-database", "default",
    "--clickhouse-username", "default",
    "--clickhouse-password", "your_clickhouse_password",
    "--openapi", "http"
  ],
  "comment": "启动Altinity ClickHouse MCP服务器，使用HTTP传输协议，并暴露OpenAPI接口。",
  "parameters_comment": {
    "--transport": "指定MCP服务器使用的传输协议（stdio, http, sse）。此示例中使用http。",
    "--address": "服务器监听的IP地址。",
    "--port": "服务器监听的端口。",
    "--clickhouse-host": "您的ClickHouse数据库主机名或IP地址。",
    "--clickhouse-port": "您的ClickHouse数据库端口。",
    "--clickhouse-database": "连接的默认ClickHouse数据库名称。",
    "--clickhouse-username": "连接ClickHouse数据库的用户名。",
    "--clickhouse-password": "连接ClickHouse数据库的密码。",
    "--openapi": "启用OpenAPI端点，支持http或https。此示例中使用http。"
  }
}

提示:

'your_clickhouse_host' 和 'your_clickhouse_password' 需要替换为实际的ClickHouse连接信息。
如果启用了JWE认证，MCP客户端在调用工具或资源时，需要在请求中包含有效的JWE token。
更复杂的配置可以通过配置文件（YAML或JSON）指定，并通过 '--config' 参数加载。

基本使用方法

启动服务器: 按照上述安装步骤选择一种方式启动MCP服务器，并确保它能连接到您的ClickHouse实例。

（可选）生成JWE Token: 如果服务器配置为启用JWE认证，可以使用内置的JWE Token生成器来创建带有ClickHouse连接凭据的加密令牌：

go run ./cmd/jwe_auth/jwe_token_generator.go \
  --jwe-secret-key "your-jwe-encryption-secret" \
  --jwt-secret-key "your-jwt-signing-secret" \
  --host "clickhouse.example.com" \
  --port 8123 \
  --database "analytics" \
  --username "user123" \
  --password "password123" \
  --expiry 86400

然后将生成的JWE Token用于后续的MCP客户端请求。

MCP客户端交互: 使用任何兼容MCP协议的客户端（如LLM助手），连接到MCP服务器的端点。客户端可以：
- 调用工具: 例如，调用 'execute_query' 工具来执行SQL查询，如 'execute_query(query="SELECT * FROM my_table LIMIT 10")'。
- 读取资源: 读取 'clickhouse://schema' 获取整个数据库的模式信息，或读取 'clickhouse://table/my_db/my_table' 获取特定表的详细结构。
- 利用动态工具: 如果配置了动态工具规则，客户端可以发现并调用对应ClickHouse视图生成的工具。
OpenAPI集成 (适用于OpenAI GPTs): 如果服务器启用了OpenAPI，可以将其OpenAPI schema（例如 'http://localhost:8080/openapi'）导入到OpenAI GPTs中，使GPTs能够直接通过定义的Action与ClickHouse数据库交互。

关键词

信息