ClickHouse MCP服务器
](https://pypi.org/project/mcp-clickhouse)
ClickHouse的MCP服务器。
特性
ClickHouse工具
run_select_query
- 在ClickHouse集群上执行SQL查询。 - 输入： sql （string）：要执行的SQL查询。 - 所有ClickHouse查询都使用 readonly = 1 以确保它们的安全。
list_databases
- 列出ClickHouse集群上的所有数据库。
list_tables
- 列出数据库中的所有表。 - 输入： database （string）：数据库的名称。
chDB工具
run_chdb_select_query
- 使用chDB的嵌入式OLAP引擎执行SQL查询。 - 输入： sql （string）：要执行的SQL查询。 - 直接从各种来源（文件、URL、数据库）查询数据，无需ETL过程。
健康检查端点
当使用HTTP或SSE传输运行时，可以在以下位置使用健康检查端点 /health。此端点：
- 退货
200 OK如果服务器运行正常并且可以连接到ClickHouse，则使用ClickHouse版本 - 退货
503 Service Unavailable如果服务器无法连接到ClickHouse
例子：
curl http://localhost:8000/health
# Response: OK - Connected to ClickHouse 24.3.1配置
此MCP服务器支持ClickHouse和chDB。您可以根据需要启用其中之一或两者。
- 打开位于以下位置的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.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "",
"CLICKHOUSE_PORT": "",
"CLICKHOUSE_USER": "",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
}
}
}
}更新环境变量以指向您自己的ClickHouse服务。
或者，如果你想试试 ClickHouse SQL游乐场，您可以使用以下配置：
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"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"
}
}
}
}对于chDB（嵌入式OLAP引擎），添加以下配置：
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CHDB_ENABLED": "true",
"CLICKHOUSE_ENABLED": "false",
"CHDB_DATA_PATH": "/path/to/chdb/data"
}
}
}
}您还可以同时启用ClickHouse和chDB：
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "",
"CLICKHOUSE_PORT": "",
"CLICKHOUSE_USER": "",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
"CHDB_ENABLED": "true",
"CHDB_DATA_PATH": "/path/to/chdb/data"
}
}
}
}- 找到以下命令项
uv并将其替换为指向的绝对路径uv可执行。这确保了正确的版本uv启动服务器时使用。在mac上，您可以使用以下命令找到此路径which uv.
- 重新启动Claude Desktop以应用更改。
在没有uv的情况下运行（使用Python系统）
如果你更喜欢使用Python系统安装而不是uv，你可以从PyPI安装包并直接运行它：
- 使用pip安装软件包：
python3 -m pip install mcp-clickhouse要升级到最新版本：
python3 -m pip install --upgrade mcp-clickhouse- 更新您的Claude Desktop配置以直接使用Python：
{
"mcpServers": {
"mcp-clickhouse": {
"command": "python3",
"args": [
"-m",
"mcp_clickhouse.main"
],
"env": {
"CLICKHOUSE_HOST": "",
"CLICKHOUSE_PORT": "",
"CLICKHOUSE_USER": "",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
}
}
}
}或者，您可以直接使用已安装的脚本：
{
"mcpServers": {
"mcp-clickhouse": {
"command": "mcp-clickhouse",
"env": {
"CLICKHOUSE_HOST": "",
"CLICKHOUSE_PORT": "",
"CLICKHOUSE_USER": "",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30",
"CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
}
}
}
}注意：确保使用Python可执行文件的完整路径或 mcp-clickhouse 如果它们不在您的系统PATH中，则执行脚本。您可以通过以下方式找到路径：
which python3对于Python可执行文件which mcp-clickhouse对于已安装的脚本
发展
- 在……里面
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检查器进行测试，请运行
fastmcp dev mcp_clickhouse/mcp_server.py启动MCP服务器。
- 要使用HTTP传输和健康检查端点进行测试，请执行以下操作：
# Using default port 8000
CLICKHOUSE_MCP_SERVER_TRANSPORT=http python -m mcp_clickhouse.main
# Or with a custom port
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_BIND_PORT=4200 python -m mcp_clickhouse.main
# Then in another terminal:
curl http://localhost:8000/health # or http://localhost:4200/health for custom port环境变量
以下环境变量用于配置ClickHouse和chDB连接：
ClickHouse变量
必需变量
CLICKHOUSE_HOST：ClickHouse服务器的主机名CLICKHOUSE_USER：用于身份验证的用户名CLICKHOUSE_PASSWORD：身份验证密码
\[！小心\] 将MCP数据库用户视为连接到数据库的任何外部客户端，只授予其操作所需的最低权限，这一点很重要。应始终严格避免使用默认用户或管理用户。
可选变量
CLICKHOUSE_PORT：ClickHouse服务器的端口号
- 违约： 8443 如果启用了HTTPS， 8123 如果禁用 - 通常不需要设置，除非使用非标准端口
CLICKHOUSE_SECURE：启用/禁用HTTPS连接
- 违约： "true" - 吃起来 "false" 用于非安全连接
CLICKHOUSE_VERIFY：启用/禁用SSL证书验证
- 违约： "true" - 吃起来 "false" 禁用证书验证（不建议用于生产）
CLICKHOUSE_CONNECT_TIMEOUT：连接超时（秒）
- 违约： "30" - 如果遇到连接超时，请增加此值
CLICKHOUSE_SEND_RECEIVE_TIMEOUT：发送/接收超时（秒）
- 违约： "300" - 为长时间运行的查询增加此值
CLICKHOUSE_DATABASE：要使用的默认数据库
- 默认值：无（使用服务器默认值） - 将其设置为自动连接到特定数据库
CLICKHOUSE_MCP_SERVER_TRANSPORT：设置MCP服务器的传输方法。
- 违约： "stdio" - 有效选项： "stdio", "http", "sse"这对于使用MCP Inspector等工具进行本地开发非常有用。
CLICKHOUSE_MCP_BIND_HOST：使用HTTP或SSE传输时将MCP服务器绑定到的主机
- 违约： "127.0.0.1" - 吃起来 "0.0.0.0" 绑定到所有网络接口（对Docker或远程访问有用） - 仅在运输时使用 "http" 或 "sse"
CLICKHOUSE_MCP_BIND_PORT：使用HTTP或SSE传输时绑定MCP服务器的端口
- 违约： "8000" - 仅在运输时使用 "http" 或 "sse"
CLICKHOUSE_ENABLED：启用/禁用ClickHouse功能
- 违约： "true" - 吃起来 "false" 仅使用chDB时禁用ClickHouse工具
chDB变量
CHDB_ENABLED：启用/禁用chDB功能
- 违约： "false" - 吃起来 "true" 启用chDB工具
CHDB_DATA_PATH：chDB数据目录的路径
- 违约： ":memory:" （内存数据库） - 使用 :memory: 用于内存数据库 - 使用文件路径进行持久存储（例如。， /path/to/chdb/data)
示例配置
使用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游乐场：
CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)仅适用于chDB（内存中）：
# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH defaults to :memory:对于具有持久存储的chDB：
# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
CHDB_DATA_PATH=/path/to/chdb/data对于MCP检查器或使用HTTP传输的远程访问：
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0 # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200 # Custom port (default: 8000)使用HTTP传输时，服务器将在配置的端口（默认8000）上运行。例如，在上述配置中：
- MCP端点：
http://localhost:4200/mcp - 健康检查：
http://localhost:4200/health
您可以在环境中设置这些变量 .env 或者在Claude Desktop配置中：
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "",
"CLICKHOUSE_USER": "",
"CLICKHOUSE_PASSWORD": "",
"CLICKHOUSE_DATABASE": "",
"CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
"CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
"CLICKHOUSE_MCP_BIND_PORT": "8000"
}
}
}
}注意：绑定主机和端口设置仅在传输设置为“http”或“sse”时使用。
运行测试
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 -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
uv run pytest -v tests/test_chdb_tool.py # chDB onlyYouTube概述
