使用说明

ClickHouse MCP服务器

一种模型上下文协议（MCP）服务器，提供与ClickHouse数据库交互的工具。内置于 xmcp 并且支持HTTP和stdio传输方法。

特性

列出数据库：从ClickHouse服务器检索所有数据库
列表表格：从特定数据库获取表
运行选择查询：安全地执行SELECT、SHOW和DESCRIBE查询
多种运输方式：支持stdio、HTTP和SSE（服务器发送事件）
TLS/SSL支持：用于安全连接的可配置证书处理

安装

来自npm（发布时）

npm install -g clickhouse-mcp-server

来源

git clone https://github.com/ahmedrowaihi/clickhouse-mcp-server.git
cd clickhouse-mcp-server
bun install
bun run build

用法

作为CLI工具（全局安装后）

# Start in stdio mode (for local/subprocess communication)
clickhouse-mcp stdio

# Start in HTTP mode (for remote/network access)
clickhouse-mcp http

# Start in SSE mode (Server-Sent Events over HTTP)
clickhouse-mcp sse

开发模式

# Start development server
bun run dev

# Build for production
bun run build

# Run specific modes
bun run start:stdio
bun run start:http

直接执行（建造后）

# Using the compiled launcher
node dist/launcher.js stdio
node dist/launcher.js http
node dist/launcher.js sse

# Or run server files directly
node dist/stdio.js
node dist/http.js

配置

环境变量

在运行服务器之前设置这些环境变量：

export CLICKHOUSE_HOST_URL=https://your-clickhouse-server.com:8443
export CLICKHOUSE_USER=your-username
export CLICKHOUSE_PASSWORD=your-password
export CLICKHOUSE_DATABASE=your-database

# Optional settings with defaults
export CLICKHOUSE_SECURE=true
export CLICKHOUSE_VERIFY=true
export CLICKHOUSE_CONNECT_TIMEOUT_SEC=10
export CLICKHOUSE_SEND_RECEIVE_TIMEOUT_SEC=60

# Optional TLS certificate path
export CLICKHOUSE_CERT_PATH=/path/to/certificate.pem

或者创建一个 .env 项目根目录中的文件：

# ClickHouse connection settings
CLICKHOUSE_HOST_URL=https://your-clickhouse-server.com:8443
CLICKHOUSE_USER=your-username
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_DATABASE=your-database

# Optional settings with defaults
CLICKHOUSE_SECURE=true
CLICKHOUSE_VERIFY=true
CLICKHOUSE_CONNECT_TIMEOUT_SEC=10
CLICKHOUSE_SEND_RECEIVE_TIMEOUT_SEC=60

# Optional TLS certificate path
CLICKHOUSE_CERT_PATH=/path/to/certificate.pem

MCP客户端配置

克劳德桌面

将此添加到您的Claude Desktop配置文件中：

在 macOS 上: ~/Library/Application Support/Claude/claude_desktop_config.json 在Windows上: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "clickhouse": {
      "command": "clickhouse-mcp",
      "args": ["stdio"],
      "env": {
        "CLICKHOUSE_HOST_URL": "https://your-clickhouse-server.com:8443",
        "CLICKHOUSE_USER": "your-username",
        "CLICKHOUSE_PASSWORD": "your-password",
        "CLICKHOUSE_DATABASE": "your-database",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT_SEC": "10",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT_SEC": "60"
      }
    }
  }
}

与npx一起使用（如果未全局安装）

{
  "mcpServers": {
    "clickhouse": {
      "command": "npx",
      "args": ["clickhouse-mcp-server", "stdio"],
      "env": {
        "CLICKHOUSE_HOST_URL": "https://your-clickhouse-server.com:8443",
        "CLICKHOUSE_USER": "your-username",
        "CLICKHOUSE_PASSWORD": "your-password",
        "CLICKHOUSE_DATABASE": "your-database"
      }
    }
  }
}

HTTP/SSE模式设置

对于基于HTTP的MCP客户端，您需要在HTTP或SSE模式下运行服务器，并将客户端配置为通过URL连接。

步骤1：创建.env文件

创建一个 .env 项目目录中的文件：

CLICKHOUSE_HOST_URL=https://sql-clickhouse.clickhouse.com:8443
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
CLICKHOUSE_DATABASE=default
CLICKHOUSE_SECURE=true

步骤2：启动服务器

# Start in HTTP mode
clickhouse-mcp http

# Or start in SSE mode
clickhouse-mcp sse

服务器将于启动 http://localhost:3001 默认情况下，接受mcp请求 /mcp 路径。

步骤3：配置MCP客户端

对于支持HTTP连接的MCP客户端，请将以下内容添加到您的配置中：

{
  "mcpServers": {
    "clickhouse-playground": {
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

游乐场测试完整示例：

创建 .env 文件：

CLICKHOUSE_HOST_URL=https://sql-clickhouse.clickhouse.com:8443
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
CLICKHOUSE_DATABASE=default
CLICKHOUSE_SECURE=true

启动服务器：
```
clickhouse-mcp sse
```

配置您的MCP客户端：

{
  "mcpServers": {
    "clickhouse-playground": {
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

备注：HTTP/SSE模式非常适合基于web的MCP客户端、远程访问，或者需要多个客户端连接到同一服务器实例时。

ClickHouse游乐场快速入门

要快速测试MCP服务器，您可以使用公共ClickHouse SQL Playground：

游乐场的环境变量

export CLICKHOUSE_HOST_URL=https://sql-clickhouse.clickhouse.com:8443
export CLICKHOUSE_USER=demo
export CLICKHOUSE_PASSWORD=""
export CLICKHOUSE_DATABASE=default
export CLICKHOUSE_SECURE=true

Claude游乐场桌面配置

{
  "mcpServers": {
    "clickhouse-playground": {
      "command": "clickhouse-mcp",
      "args": ["stdio"],
      "env": {
        "CLICKHOUSE_HOST_URL": "https://sql-clickhouse.clickhouse.com:8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_DATABASE": "default",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}

测试命令

配置后，您可以在Claude Desktop中测试这些查询：

列出数据库：“显示所有可用数据库”
列出表格：“默认数据库中有哪些表？”
示例查询：“显示任何表的前10行”

备注ClickHouse Playground是一个公开的演示环境。不要将其用于生产数据或敏感信息。

环境变量

变量	描述	必填	默认
`CLICKHOUSE_HOST_URL`	ClickHouse服务器的完整URL	是	-
`CLICKHOUSE_USER`	身份验证用户名	是	-
`CLICKHOUSE_PASSWORD`	身份验证密码	是	-
`CLICKHOUSE_DATABASE`	要连接的默认数据库	是	-
`CLICKHOUSE_SECURE`	使用HTTPS/TLS连接	否	`true`
`CLICKHOUSE_VERIFY`	验证SSL证书	否	`true`
`CLICKHOUSE_CONNECT_TIMEOUT_SEC`	连接超时（秒）	否	`10`
`CLICKHOUSE_SEND_RECEIVE_TIMEOUT_SEC`	请求超时（秒）	否	`60`
`CLICKHOUSE_CERT_PATH`	自定义SSL证书的路径	否	-

可用工具

1.列出数据库

列出ClickHouse服务器上可用的所有数据库。

MCP客户端中的用法：

{
  "method": "tools/call",
  "params": {
    "name": "list_databases"
  }
}

2.列表

列出指定数据库中的所有表。

参数：

database （string）：数据库的名称

MCP客户端中的用法：

{
  "method": "tools/call",
  "params": {
    "name": "list_tables",
    "arguments": {
      "database": "my_database"
    }
  }
}

3.运行选择查询

在ClickHouse数据库上执行SELECT、SHOW或DESCRIBE查询。

参数：

query （string）：要执行的SQL查询（必须以SELECT、SHOW或DESCRIBE开头）

MCP客户端中的用法：

{
  "method": "tools/call",
  "params": {
    "name": "run_select_query",
    "arguments": {
      "query": "SELECT * FROM my_table LIMIT 10"
    }
  }
}

运输方式

STDIO模式

最适合本地开发和子流程沟通：

clickhouse-mcp stdio

HTTP模式

非常适合远程访问和基于web的客户端：

clickhouse-mcp http

SSE模式

实时应用程序的服务器通过HTTP发送事件：

clickhouse-mcp sse

建筑

# Build everything (xmcp + launcher)
bun run build

# Build only xmcp components
bun run build:xmcp

安全

所有查询均通过以下方式执行 readonly: "1" 安全设置
只允许使用SELECT、SHOW和DESCRIBE查询
TLS/SSL支持安全连接

需求

Node.js>=20.0.0
具有网络访问权限的ClickHouse服务器
有效的ClickHouse凭据

许可证

麻省理工学院

贡献

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
提交拉取请求

链接

GitHub存储库

使用说明

ClickHouse MCP服务器

特性

安装

来自npm（发布时）

来源

用法

作为CLI工具（全局安装后）

开发模式

直接执行（建造后）

配置

环境变量

MCP客户端配置

克劳德桌面

与npx一起使用（如果未全局安装）

HTTP/SSE模式设置

ClickHouse游乐场快速入门

游乐场的环境变量

Claude游乐场桌面配置

测试命令

环境变量

可用工具

1.列出数据库

2.列表

3.运行选择查询

运输方式

STDIO模式

HTTP模式

SSE模式

建筑

安全

需求

许可证

贡献

链接

相关 MCP

MySQL数据库管理工具

MongoDB 数据库 MCP 服务器

PostgreSQL管理服务器

PocketBase 数据库 MCP 服务器

SQLite数据库服务

MySQL数据库操作工具