ClickHouse

官方

查询您的ClickHouse数据库服务器。

GitHub

839

你可以用 Click House MCP 做什么？

运行只读SQL查询 — 让助手使用 run_query 对您的 ClickHouse 集群执行任意 SELECT 查询。
列出数据库和表 — 通过 list_databases 列出所有数据库，或使用 list_tables 分页查看特定数据库中的表，从而探索您的架构。
通过 chDB 直接查询文件和URL — 使用 run_chdb_select_query 对本地文件或远程数据源运行SQL，无需先将数据加载到 ClickHouse 中。
控制写入和破坏性操作 — 启用 CLICKHOUSE_ALLOW_WRITE_ACCESS 以允许 DDL/DML 操作，并可选择启用 CLICKHOUSE_ALLOW_DROP 以允许在 AI 辅助会话期间执行 DROP 或 TRUNCATE 语句。

文档

ClickHouse MCP 服务器

一个用于 ClickHouse 的 MCP 服务器。

功能特性

ClickHouse 工具

run_query
- 在您的 ClickHouse 集群上执行 SQL 查询。
- 输入：query（字符串）：要执行的 SQL 查询。
- 查询默认以只读模式运行（CLICKHOUSE_ALLOW_WRITE_ACCESS=false），但如果需要，可以显式启用写入操作。
list_databases
- 列出 ClickHouse 集群上的所有数据库。
list_tables
- 分页列出数据库中的表。
- 必需输入：database（字符串）。
- 可选输入：
  - like / not_like（字符串）：对表名应用 LIKE 或 NOT LIKE 过滤。
  - page_token（字符串）：上一次调用返回的令牌，用于获取下一页。
  - page_size（整数，默认 50）：每页返回的表数量。
  - include_detailed_columns（布尔值，默认 true）：当为 false 时，省略列元数据以减轻响应负载，同时保留完整的 create_table_query。
- 响应结构：
  - tables：当前页的表对象数组。
  - next_page_token：传递此值以获取下一页，当没有更多表时为 null。
  - total_tables：匹配所提供过滤器的表的总数。

chDB 工具

run_chdb_select_query
- 使用 chDB 的内嵌 ClickHouse 引擎执行 SQL 查询。
- 输入：query（字符串）：要执行的 SQL 查询。
- 直接从各种来源（文件、URL、数据库）查询数据，无需 ETL 过程。
- 需要可选的 chdb 额外项：pip install 'mcp-clickhouse[chdb]'

健康检查端点

当使用 HTTP 或 SSE 传输运行时，健康检查端点位于 /health。此端点：

如果服务器健康且可以连接到 ClickHouse，则返回 200 OK（响应体：OK）
如果服务器无法连接到 ClickHouse，则返回 503 Service Unavailable 并附带通用错误消息

该端点有意不进行身份验证，以便编排探针（例如 Kubernetes 存活/就绪探针、负载均衡器）无需凭据即可访问。响应体有意保持最小化，以避免泄露后端版本字符串或错误详情；通过服务器日志调试故障。

示例：

curl http://localhost:8000/health
# Response: OK

安全性

HTTP/SSE 传输的身份验证

当使用 HTTP 或 SSE 传输时，默认需要身份验证。stdio 传输（默认）不需要身份验证，因为它仅通过标准输入/输出进行通信。

支持三种身份验证模式。请选择一种：

模式	使用场景	环境变量
静态持有者令牌	简单部署、内部服务	`CLICKHOUSE_MCP_AUTH_TOKEN`
OAuth / OIDC（通过 FastMCP）	Azure Entra、Google、GitHub、WorkOS 等	`FASTMCP_SERVER_AUTH=<provider-class-path>`（+ 提供商特定的 `FASTMCP_SERVER_AUTH_*` 变量）
已禁用	仅限本地开发	`CLICKHOUSE_MCP_AUTH_DISABLED=true`

如果对于 HTTP/SSE 传输未配置以上任何一项，启动将失败。

设置身份验证

生成一个安全令牌（可以是任意随机字符串）：

# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

使用令牌配置服务器：

export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

配置您的 MCP 客户端以在请求中包含令牌：

对于使用 HTTP/SSE 传输的 Claude Desktop：
```
{
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}
```
注意：/health 端点有意不进行身份验证（参见上文的健康检查端点）。要验证持有者令牌身份验证确实拒绝了未经身份验证的请求，请直接访问 MCP 端点本身，例如使用 MCP Inspector，或者通过向 /mcp 发送带有和不带有 Authorization 头的 JSON-RPC 请求，并确认未经身份验证的调用返回 401。

通过 FastMCP 的 OAuth / OIDC

对于使用身份提供商（Azure Entra、Google、GitHub、WorkOS 等）的生产部署，请将身份验证委托给 FastMCP 的内置身份验证提供程序，而不是使用静态令牌。将 FASTMCP_SERVER_AUTH 设置为 FastMCP 身份验证提供程序的完整类路径，以及提供商特定的 FASTMCP_SERVER_AUTH_* 变量，并保持 CLICKHOUSE_MCP_AUTH_TOKEN 未设置。

示例（Azure Entra）：

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"

有关提供程序的完整列表及其所需的环境变量，请参阅 FastMCP 文档。

开发模式（禁用身份验证）

仅限本地开发和测试，您可以通过以下设置禁用身份验证：

export CLICKHOUSE_MCP_AUTH_DISABLED=true

警告： 仅将此用于本地开发。当服务器暴露于任何网络时，请勿禁用身份验证。

配置

此 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-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_ROLE": "<clickhouse-role>",
        "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.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（内嵌 ClickHouse 引擎），添加以下配置：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--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[chdb]",
        "--python",
        "3.10",
        "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",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

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

可选写入访问

默认情况下，此 MCP 强制执行只读查询，以便在探索期间不会发生意外变更。要允许 DDL 或 INSERT/UPDATE 语句，请将 CLICKHOUSE_ALLOW_WRITE_ACCESS 环境变量设置为 true。如果 ClickHouse 实例本身不允许写入，服务器将继续强制执行只读模式。

破坏性操作保护

即使启用了写入访问（CLICKHOUSE_ALLOW_WRITE_ACCESS=true），破坏性操作（DROP TABLE、DROP DATABASE、DROP VIEW、DROP DICTIONARY、TRUNCATE TABLE）也需要额外的显式选择加入标志以确保安全。这可以防止在 AI 探索期间意外删除数据。

要启用破坏性操作，请设置两个标志：

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}

这种双层方法确保意外删除非常困难：

写入操作（INSERT、UPDATE、CREATE）需要 CLICKHOUSE_ALLOW_WRITE_ACCESS=true
破坏性操作（DROP、TRUNCATE）额外需要 CLICKHOUSE_ALLOW_DROP=true

不使用 uv 运行（使用系统 Python）

如果您更喜欢使用系统 Python 安装而不是 uv，可以从 PyPI 安装软件包并直接运行：

使用 pip 安装软件包：

python3 -m pip install mcp-clickhouse

同时安装 chDB 支持：

python3 -m pip install 'mcp-clickhouse[chdb]'

升级到最新版本：

python3 -m pip install --upgrade mcp-clickhouse

更新您的 Claude Desktop 配置以直接使用 Python：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "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"
      }
    }
  }
}

或者，您可以直接使用已安装的脚本：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "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"
      }
    }
  }
}

注意：如果 Python 可执行文件或 mcp-clickhouse 脚本不在您的系统 PATH 中，请确保使用其完整路径。您可以使用以下命令找到路径：

which python3 用于 Python 可执行文件
which mcp-clickhouse 用于已安装的脚本

自定义中间件

您可以在不修改源代码的情况下向 MCP 服务器添加自定义中间件。FastMCP 提供了一个中间件系统，允许您拦截和处理 MCP 协议消息（工具调用、资源读取、提示等）。

如何使用

创建一个 Python 模块，其中包含扩展 Middleware 的中间件类和一个 setup_middleware(mcp) 函数：

# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())

将 MCP_MIDDLEWARE_MODULE 环境变量设置为模块名称（不带 .py 扩展名）：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}

确保您的中间件模块位于 Python 的导入路径中（例如，与 MCP 服务器运行在同一目录中，或作为软件包安装）。

示例中间件

example_middleware.py 中提供了一个示例中间件模块，展示了常见模式：

记录所有 MCP 请求
专门记录工具调用
测量请求处理时间

要使用该示例：

"env": {
  "MCP_MIDDLEWARE_MODULE": "example_middleware"
}

中间件功能

Middleware 基类为不同的 MCP 操作提供了钩子：

on_message(context, call_next) - 对所有消息调用
on_request(context, call_next) - 对所有请求调用
on_notification(context, call_next) - 对所有通知调用
on_call_tool(context, call_next) - 执行工具时调用
on_read_resource(context, call_next) - 读取资源时调用
on_get_prompt(context, call_next) - 检索提示时调用
on_list_tools(context, call_next) - 列出工具时调用
on_list_resources(context, call_next) - 列出资源时调用
on_list_resource_templates(context, call_next) - 列出资源模板时调用
on_list_prompts(context, call_next) - 列出提示时调用

每个钩子接收一个包含消息和元数据的 MiddlewareContext 对象，以及一个用于继续管道的 call_next 函数。

通过上下文状态进行动态客户端配置

中间件可以使用 CLIENT_CONFIG_OVERRIDES_KEY 上下文状态键，在每个请求的基础上覆盖 ClickHouse 客户端配置。服务器会将这些覆盖项与来自环境变量的基本配置合并。

from fastmcp.server.dependencies import get_context
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

这支持高级用例，例如动态超时调整、租户特定路由或每用户连接设置。

开发

在 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 Inspector 轻松测试，请运行 fastmcp dev mcp_clickhouse/mcp_server.py 以启动 MCP 服务器。

使用 HTTP 传输和健康检查端点进行测试：

# For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main

# Or with authentication (generate a token first)
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main

# Then in another terminal:
curl http://localhost:8000/health

环境变量

配置被拆分为独立的组。将它们混淆是导致难以调试的连接故障的常见原因：

组	变量	控制内容
ClickHouse 数据库连接	`CLICKHOUSE_HOST`、`CLICKHOUSE_PORT`、`CLICKHOUSE_SECURE`、`CLICKHOUSE_VERIFY`、…	此 MCP 服务器如何通过 HTTP 接口连接到您的 ClickHouse 集群
MCP 服务器 / 传输	`CLICKHOUSE_MCP_`、`FASTMCP_SERVER_AUTH`、`FASTMCP_SERVER_AUTH_`	MCP 传输、身份验证和查询工具执行限制
中间件 / chDB	`MCP_MIDDLEWARE_MODULE`、`CHDB_*`	可选扩展

[!IMPORTANT] 诸如 CLICKHOUSE_SECURE、CLICKHOUSE_VERIFY 和 CLICKHOUSE_PORT 等变量仅适用于 ClickHouse 数据库连接。它们不配置 MCP 协议端点的 TLS、端口或身份验证。

示例：如果 MCP 服务器在 Kubernetes 中运行，位于终止 TLS 的入口后面，那是 MCP 传输的问题。保持 CLICKHOUSE_SECURE 与 Pod 访问 ClickHouse 本身的方式一致（HTTPS → true，纯 HTTP → false）。因为 MCP 服务器位于入口后面而设置 CLICKHOUSE_SECURE=false，将使服务器通过 HTTP 拨号到 ClickHouse——通常是对着仅 HTTPS 的端口——并在服务器日志中产生不透明的 HTTP/TLS 错误。

ClickHouse 数据库连接

这些变量用于配置 clickhouse-connect HTTP 客户端以及基于 ClickHouse 的工具（如 run_query、list_databases 和 list_tables）的行为。

必需变量

CLICKHOUSE_HOST：您的 ClickHouse 服务器的主机名（数据库端点，而非 MCP 服务器绑定地址）
CLICKHOUSE_USER：用于 ClickHouse 认证的用户名
CLICKHOUSE_PASSWORD：用于 ClickHouse 认证的密码

[!CAUTION] 请务必像对待任何连接到数据库的外部客户端一样对待您的 MCP 数据库用户，仅授予其运行所需的最低必要权限。任何时候都应严格避免使用默认用户或管理员用户。

可选变量

CLICKHOUSE_PORT：您的 ClickHouse 服务器的 HTTP 接口端口
- 默认值：如果 CLICKHOUSE_SECURE=true，则为 8443；如果 CLICKHOUSE_SECURE=false，则为 8123
- 除非使用非标准端口，否则通常无需设置
- 必须是 HTTP 接口端口，而非 clickhouse-client 使用的原生 TCP 协议端口
- 常见值：
  - HTTP：8123（明文）/ 8443（TLS）—— 此服务器和 ClickHouse Cloud HTTPS 使用
  - 原生 TCP（此处不支持）：9000（明文）/ 9440（TLS）—— clickhouse-client 使用
- 如果服务器响应 Port 9000 is for clickhouse-client program，说明您指向的是原生协议；请切换到 HTTP 端口（8123/8443 或您部署的 HTTP 映射）
CLICKHOUSE_ROLE：用于认证的 ClickHouse 角色
- 默认值：无
- 如果您的用户需要特定角色，请设置此项
CLICKHOUSE_SECURE：为 ClickHouse 数据库连接启用 HTTPS（而非为 MCP 客户端）
- 默认值："true"
- 仅当 MCP 服务器通过明文 HTTP 访问 ClickHouse 时（例如本地 Docker Compose 在端口 8123 上），才设置为 "false"
- 对于 ClickHouse Cloud 和任何 HTTPS 数据库端点，请保留 "true"——即使 MCP 服务器本身通过 HTTP、stdio 或单独终止 TLS 的入口暴露
- 将此标志与数据库端口不匹配（例如，针对端口 8443 使用 CLICKHOUSE_SECURE=false）是常见的设置错误，通常表现为令人困惑的 HTTP 客户端错误，而非明确的“方案错误”消息
CLICKHOUSE_VERIFY：启用/禁用 ClickHouse HTTPS 连接的 SSL 证书验证
- 默认值："true"
- 设置为 "false" 以禁用证书验证（不推荐用于生产环境）
- TLS 证书：该软件包通过 truststore 使用您操作系统的信任存储区进行 TLS 证书验证。我们在启动时调用 truststore.inject_into_ssl() 以确保正确的证书处理。仅当发生意外错误时，才使用 Python 的默认 SSL 行为作为后备。
CLICKHOUSE_SERVER_HOST_NAME：用于 ClickHouse 连接的 SNI 覆盖和证书验证的服务器主机名
- 默认值：无（使用连接主机名）
- 当通过代理或负载均衡器连接，且证书主机名与连接主机名不同时，此选项很有用。设置后，此主机名将用于 TLS 握手期间的 SNI（服务器名称指示）和证书主机名验证。
CLICKHOUSE_PROXY_PATH：ClickHouse HTTP 端点的 URL 路径前缀
- 默认值：无
- 当 ClickHouse HTTP 接口通过反向代理以路径前缀暴露时设置此项（例如，/clickhouse）
CLICKHOUSE_CONNECT_TIMEOUT：ClickHouse 客户端的连接超时时间（秒）
- 默认值："30"
- 如果遇到连接超时，请增加此值
CLICKHOUSE_SEND_RECEIVE_TIMEOUT：ClickHouse 客户端的发送/接收超时时间（秒）
- 默认值："300"
- 对于长时间运行的查询，请增加此值
CLICKHOUSE_DATABASE：要使用的默认 ClickHouse 数据库
- 默认值：无（使用服务器默认值）
- 设置此项以自动连接到特定数据库
CLICKHOUSE_ENABLED：启用/禁用 ClickHouse 数据库工具
- 默认值："true"
- 设置为 "false" 以在仅使用 chDB 时禁用 ClickHouse 工具
CLICKHOUSE_ALLOW_WRITE_ACCESS：允许对 ClickHouse 进行写操作（DDL 和 DML）
- 默认值："false"
- 设置为 "true" 以允许 DDL（CREATE、ALTER、DROP）和 DML（INSERT、UPDATE、DELETE）操作
- 禁用时（默认），查询将使用 readonly=1 设置运行，以防止数据修改
CLICKHOUSE_ALLOW_DROP：允许破坏性操作（DROP TABLE、DROP DATABASE、DROP VIEW、DROP DICTIONARY、TRUNCATE TABLE）
- 默认值："false"
- 仅在同时设置了 CLICKHOUSE_ALLOW_WRITE_ACCESS=true 时生效
- 设置为 "true" 以明确允许破坏性的 DROP 和 TRUNCATE 操作
- 这是一项安全功能，旨在防止 AI 探索期间意外删除数据

MCP 服务器与传输

这些变量控制 MCP 进程本身，包括传输、认证和查询工具执行限制。它们独立于上述 ClickHouse 数据库设置。另请参阅 HTTP/SSE 传输的认证。

CLICKHOUSE_MCP_SERVER_TRANSPORT：设置 MCP 服务器的传输方法
- 默认值："stdio"
- 有效选项："stdio"、"http"、"sse"。这对于使用 MCP Inspector 等工具进行本地开发很有用。
- stdio 通常用于 Claude Desktop；http/sse 会暴露一个网络监听器（绑定主机/端口如下）
CLICKHOUSE_MCP_BIND_HOST：使用 HTTP 或 SSE 传输时，MCP 服务器绑定的主机
- 默认值："127.0.0.1"
- 设置为 "0.0.0.0" 以绑定到所有网络接口（适用于 Docker 或远程访问）
- 仅在传输方式为 "http" 或 "sse" 时使用——与 CLICKHOUSE_HOST 无关
CLICKHOUSE_MCP_BIND_PORT：使用 HTTP 或 SSE 传输时，MCP 服务器绑定的端口
- 默认值："8000"
- 仅在传输方式为 "http" 或 "sse" 时使用——与 CLICKHOUSE_PORT 无关
CLICKHOUSE_MCP_QUERY_TIMEOUT：查询工具的超时时间（秒）
- 默认值："30"
- 如果对于繁重查询出现 Query timed out after ... 错误，请增加此值
CLICKHOUSE_MCP_AUTH_TOKEN：用于 HTTP/SSE 传输的静态持有者令牌
- 默认值：无
- 对于 HTTP/SSE 传输，必须设置 CLICKHOUSE_MCP_AUTH_TOKEN、FASTMCP_SERVER_AUTH 或 CLICKHOUSE_MCP_AUTH_DISABLED=true 之一
- 使用 uuidgen 或 openssl rand -hex 32 生成
- 客户端必须在 Authorization: Bearer <token> 标头中发送此令牌
FASTMCP_SERVER_AUTH：将认证委托给 FastMCP 认证提供程序
- 默认值：无
- 值是 AuthProvider 子类的完整类路径，例如 fastmcp.server.auth.providers.azure.AzureProvider 或 fastmcp.server.auth.providers.google.GoogleProvider
- 设置后，FastMCP 会从其自身的 FASTMCP_SERVER_AUTH_* 环境变量中自动加载提供程序；在此模式下，请勿设置 CLICKHOUSE_MCP_AUTH_TOKEN
CLICKHOUSE_MCP_AUTH_DISABLED：为 HTTP/SSE 传输禁用认证
- 默认值："false"（认证已启用）
- 设置为 "true" 以仅在本地开发/测试时禁用认证
- 警告： 仅用于本地开发。暴露于网络时请勿禁用

中间件变量

MCP_MIDDLEWARE_MODULE：包含要注入到 MCP 服务器的自定义中间件的 Python 模块名称
- 默认值：无（不加载中间件）
- 设置为您的中间件模块的模块名称（不带 .py 扩展名）
- 该模块必须提供一个 setup_middleware(mcp) 函数
- 有关详细信息和示例，请参阅自定义中间件

chDB 变量

CHDB_ENABLED：启用/禁用 chDB 功能
- 默认值："false"
- 设置为 "true" 以启用 chDB 工具
- 需要安装可选附加项：mcp-clickhouse[chdb]
CHDB_DATA_PATH：chDB 数据目录的路径
- 默认值：":memory:"（内存数据库）
- 使用 :memory: 作为内存数据库
- 使用文件路径进行持久存储（例如，/path/to/chdb/data）

常见配置陷阱

CLICKHOUSE_SECURE 与 MCP / 入口 TLS —— 因为 MCP 服务器位于 Kubernetes 入口、反向代理之后或通过明文 HTTP 访问而关闭 CLICKHOUSE_SECURE，并不会禁用数据库 TLS；它只会更改此进程连接到 ClickHouse 的方式。请将入口 TLS 与数据库客户端设置分开配置。
原生协议端口 —— CLICKHOUSE_PORT 必须指向 ClickHouse 的 HTTP 接口（默认为 8123/8443）。端口 9000/9440 用于原生 TCP 协议（clickhouse-client），无法与此服务器配合使用。
主机混淆 —— CLICKHOUSE_HOST 是数据库主机名。CLICKHOUSE_MCP_BIND_HOST 仅是 MCP HTTP/SSE 服务器监听的地址。

配置示例

使用 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)

仅使用 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

使用 HTTP 传输进行 MCP Inspector 或远程访问：

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)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)

使用 HTTP 传输进行本地开发（认证已禁用）：

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!

使用 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-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-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
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only