ClickHouse MCP 服务器

PyPI - 版本

ClickHouse 的 MCP 服务器。

特征

工具

run_select_query
- 在您的 ClickHouse 集群上执行 SQL 查询。
- 输入： sql （字符串）：要执行的 SQL 查询。
- 所有 ClickHouse 查询均以readonly = 1运行，以确保它们是安全的。
list_databases
- 列出 ClickHouse 集群上的所有数据库。
list_tables
- 列出数据库中的所有表。
- 输入： database （字符串）：数据库的名称。

Related MCP server: MCP Alchemy

配置

打开位于以下位置的 Claude Desktop 配置文件：
- 在 macOS 上： ~/Library/Application Support/Claude/claude_desktop_config.json
- 在 Windows 上： %APPDATA%/Claude/claude_desktop_config.json
添加以下内容：

{ "mcpServers": { "mcp-clickhouse": { "command": "uv", "args": [ "run", "--with", "mcp-clickhouse", "--python", "3.13", "mcp-clickhouse" ], "env": { "CLICKHOUSE_HOST": "<clickhouse-host>", "CLICKHOUSE_PORT": "<clickhouse-port>", "CLICKHOUSE_USER": "<clickhouse-user>", "CLICKHOUSE_PASSWORD": "<clickhouse-password>", "CLICKHOUSE_SECURE": "true", "CLICKHOUSE_VERIFY": "true", "CLICKHOUSE_CONNECT_TIMEOUT": "30", "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30" } } } }

更新环境变量以指向您自己的 ClickHouse 服务。

或者，如果您想使用ClickHouse SQL Playground进行尝试，您可以使用以下配置：

{ "mcpServers": { "mcp-clickhouse": { "command": "uv", "args": [ "run", "--with", "mcp-clickhouse", "--python", "3.13", "mcp-clickhouse" ], "env": { "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com", "CLICKHOUSE_PORT": "8443", "CLICKHOUSE_USER": "demo", "CLICKHOUSE_PASSWORD": "", "CLICKHOUSE_SECURE": "true", "CLICKHOUSE_VERIFY": "true", "CLICKHOUSE_CONNECT_TIMEOUT": "30", "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30" } } } }

找到uv的命令条目，并将其替换为uv可执行文件的绝对路径。这可确保启动服务器时使用正确版本的uv 。在 Mac 上，您可以使用which uv找到此路径。
重新启动 Claude Desktop 以应用更改。

发展

在test-services目录中运行docker compose up -d来启动 ClickHouse 集群。
将以下变量添加到存储库根目录中的.env文件中。

注意：在此上下文中使用

CLICKHOUSE_HOST=localhost CLICKHOUSE_PORT=8123 CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=clickhouse

运行uv sync来安装依赖项。要安装uv ，请按照此处的说明操作。然后执行source .venv/bin/activate 。
为了方便测试，您可以运行mcp dev mcp_clickhouse/mcp_server.py来启动 MCP 服务器。

环境变量

以下环境变量用于配置 ClickHouse 连接：

必需变量

CLICKHOUSE_HOST ：ClickHouse 服务器的主机名
CLICKHOUSE_USER ：用于身份验证的用户名
CLICKHOUSE_PASSWORD ：身份验证的密码

注意：务必像对待连接到数据库的任何外部客户端一样对待 MCP 数据库用户，仅授予其操作所需的最低权限。应始终严格避免使用默认用户或管理用户。

可选变量

CLICKHOUSE_PORT ：ClickHouse 服务器的端口号
- 默认值：如果启用 HTTPS， 8443 ；如果禁用， 8123
- 通常不需要设置，除非使用非标准端口
CLICKHOUSE_SECURE ：启用/禁用 HTTPS 连接
- 默认值： "true"
- 对于非安全连接，设置为"false"
CLICKHOUSE_VERIFY ：启用/禁用 SSL 证书验证
- 默认值： "true"
- 设置为"false"以禁用证书验证（不建议用于生产）
CLICKHOUSE_CONNECT_TIMEOUT ：连接超时（秒）
- 默认值： "30"
- 如果遇到连接超时，请增加此值
CLICKHOUSE_SEND_RECEIVE_TIMEOUT ：发送/接收超时（秒）
- 默认值： "300"
- 对于长时间运行的查询，请增加此值
CLICKHOUSE_DATABASE ：默认使用的数据库
- 默认值：无（使用服务器默认值）
- 将其设置为自动连接到特定数据库

示例配置

对于使用 Docker 进行本地开发：

# Required variables CLICKHOUSE_HOST=localhost CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=clickhouse # Optional: Override defaults for local development CLICKHOUSE_SECURE=false # Uses port 8123 automatically CLICKHOUSE_VERIFY=false

对于 ClickHouse Cloud：

# Required variables CLICKHOUSE_HOST=your-instance.clickhouse.cloud CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD=your-password # Optional: These use secure defaults # CLICKHOUSE_SECURE=true # Uses port 8443 automatically # CLICKHOUSE_DATABASE=your_database

对于 ClickHouse SQL Playground：

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com CLICKHOUSE_USER=demo CLICKHOUSE_PASSWORD= # Uses secure defaults (HTTPS on port 8443)

您可以在您的环境、 .env文件或 Claude Desktop 配置中设置这些变量：

{ "mcpServers": { "mcp-clickhouse": { "command": "uv", "args": [ "run", "--with", "mcp-clickhouse", "--python", "3.13", "mcp-clickhouse" ], "env": { "CLICKHOUSE_HOST": "<clickhouse-host>", "CLICKHOUSE_USER": "<clickhouse-user>", "CLICKHOUSE_PASSWORD": "<clickhouse-password>", "CLICKHOUSE_DATABASE": "<optional-database>" } } } }

运行测试

uv sync --all-extras --dev # install dev dependencies uv run ruff check . # run linting docker compose up -d test_services # start ClickHouse uv run pytest tests

YouTube 概览

YouTube

mcp-clickhouse

ClickHouse MCP 服务器

特征

工具

配置

发展

环境变量

必需变量

可选变量

示例配置

运行测试

YouTube 概览

Resources

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API