mcp-clickhouse

ClickHouse MCP 服务器

ClickHouse 的 MCP 服务器。

特征

工具

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

配置

打开位于以下位置的 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文件中。

注意：在此上下文中使用default用户仅用于本地开发目的。

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 概览

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

ClickHouse 数据库集成了模式检查和查询功能

Related Resources

Reddit Discussion about this server

Related MCP Servers

ClickHouse MCP Server
iskakaushik
A
security
A
license
A
quality
An MCP server for ClickHouse.
Last updated -
3
3
Python
Apache 2.0
ClickHouse MCP Server
ThomAub
-
security
A
license
-
quality
A Model Context Protocol server that enables Large Language Models to seamlessly interact with ClickHouse databases, supporting resource listing, schema retrieval, and query execution.
Last updated -
1
Python
MIT License
clickhouse-mcp-server
burakdirin
-
security
A
license
-
quality
An MCP server implementation that enables Claude AI to interact with Clickhouse databases. Features include secure database connections, query execution, read-only mode support, and multi-query capabilities.
Last updated -
Python
MIT License
ClickHouse MCP Server
dubin555
-
security
-
license
-
quality
A Model Context Protocol server that enables AI assistants to securely interact with ClickHouse databases, supporting table exploration and SQL query execution through a controlled interface.
Last updated -
6
Python
Apache 2.0

View all related MCP servers

mcp-clickhouse

ClickHouse MCP 服务器

特征

工具

配置

发展

环境变量

必需变量

可选变量

示例配置

运行测试

YouTube 概览

Tools

Related Resources

Related MCP Servers

ClickHouse MCP Server

ClickHouse MCP Server

clickhouse-mcp-server

ClickHouse MCP Server

Appeared in Searches

New MCP Servers

MCP directory API