ClickHouse MCP Server

一个用于 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 查询。

  • 无需 ETL 流程，直接从各种来源（文件、URL、数据库）查询数据。

  • 需要可选的 chdb 附加组件：pip install 'mcp-clickhouse[chdb]'

健康检查端点

当使用 HTTP 或 SSE 传输时，可在 /health 获得健康检查端点。该端点：

• 如果服务器健康且能连接到 ClickHouse，则返回 200 OK（响应体：OK）

• 如果服务器无法连接到 ClickHouse，则返回 503 Service Unavailable 及一条通用错误消息

对该端点的 GET 和 HEAD 请求有意不进行认证，并且不受 Host 和 Origin 校验的限制，以便编排器探针（例如 Kubernetes 存活/就绪探针、负载均衡器）无需额外配置即可使用运行时分配的 Pod 或目标 IP。/health 是保留路径，不能用作 MCP 传输路径。响应体刻意保持最小化，以避免泄露后端版本字符串或错误详情；请通过服务器日志排查失败。

示例：

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

Related MCP server: ClickHouse MCP Server

安全

HTTP/SSE 传输的认证

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

支持三种认证模式，请选择其中一种：

如果 HTTP/SSE 传输未配置以上任何一种模式，启动将失败。

设置认证

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

   # Using uuidgen (macOS/Linux)
   uuidgen
   
   # Using openssl
   openssl rand -hex 32

2. 使用该令牌配置服务器：

   export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

3. 配置您的 MCP 客户端，使其在请求中包含该令牌：

   对于使用 HTTP/SSE 传输的 Claude Desktop：

   {
     "mcpServers": {
       "mcp-clickhouse": {
         "url": "http://127.0.0.1:8000",
         "headers": {
           "Authorization": "Bearer your-generated-token"
         }
       }
     }
   }

   注意：/health 端点有意不进行认证（请参阅上文健康检查端点）。要验证 Bearer 令牌认证确实会拒绝未认证的请求，请直接访问 MCP 端点本身，例如使用 MCP Inspector，或向 /mcp POST 一个带和不带 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
export CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

警告： 仅限本地开发使用。当服务器暴露于任何网络时，请勿禁用认证。

配置

此 MCP 服务器同时支持 ClickHouse 和 chDB。您可以根据需要启用其中任何一个，或同时启用两者。

1. 打开位于以下位置的 Claude Desktop 配置文件：

   • 在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json

   • 在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

2. 添加以下内容：

{
  "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"
      }
    }
  }
}

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

4. 重启 Claude Desktop 以应用更改。

可选的写访问权限

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

破坏性操作保护

即使启用了写访问权限（CLICKHOUSE_ALLOW_WRITE_ACCESS=true），破坏性操作仍需要额外的显式启用标志以确保安全。该检查涵盖任何 DROP 语句（包括 ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN 子句）、任何 TRUNCATE、DELETE 和 UPDATE（包括轻量级语句和 ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE 变更）、REPLACE TABLE、CREATE OR REPLACE、ALTER TABLE ... REPLACE PARTITION、ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION，以及 DETACH ... PERMANENTLY。字符串字面量、带引号的标识符和 SQL 注释中的关键字会被忽略，因此它们既不会触发检查，也不会使语句逃避检查。

此检查在 MCP 服务器中运行，是一种尽力而为的事故防护措施。它不是安全边界。安全边界是 ClickHouse 用户的授权。只读模式（默认）通过 readonly=1 在服务器端强制执行。破坏性操作门控并非服务器端强制。

对于写入模式，请为 MCP 服务器提供一个专用的 ClickHouse 用户，仅授予其所需的权限：

CREATE USER mcp_agent IDENTIFIED BY '...';
GRANT SELECT, INSERT, CREATE TABLE, ALTER ADD COLUMN ON mydb.* TO mcp_agent;

这样，任何超出这些授权的语句都会在服务器端以 ACCESS_DENIED 失败，无论 MCP 标志如何设置。服务器设置 max_table_size_to_drop 和 max_partition_size_to_drop 如果通过设置约束固定下来，也可以限制爆炸半径。

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

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

这种两层方法使得意外删除变得困难：

• 写操作（INSERT、CREATE、ALTER ADD COLUMN）需要 CLICKHOUSE_ALLOW_WRITE_ACCESS=true

• 破坏性操作（DROP、TRUNCATE、DELETE、UPDATE 以及上述列表中的其余操作）还需要 CLICKHOUSE_ALLOW_DROP=true

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

如果您希望使用系统 Python 安装而不是 uv，可以从 PyPI 安装该包并直接运行：

1. 使用 pip 安装该包：

   python3 -m pip install mcp-clickhouse

   同时安装 chDB 支持：

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

   升级到最新版本：

   python3 -m pip install --upgrade mcp-clickhouse

2. 更新您的 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 协议消息（工具调用、资源读取、提示等）。

使用方法

1. 创建一个 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())

2. 将 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"
      }
    }
  }
}

3. 确保您的中间件模块位于 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
})

这可以实现高级用例，例如动态超时调整、租户特定路由或按用户连接设置。

状态值必须是字典。嵌套的 settings 和 generic_args 值必须是映射，并与基础配置合并。无效值会在创建 ClickHouse 客户端之前导致工具调用失败。除非覆盖项显式提供 settings.role，否则 CLICKHOUSE_ROLE 保持生效。顶层 role 和 ch_role 键，以及 generic_args 下的同名键，均会被拒绝。

将这些覆盖项视为受信任的中间件输入。中间件在设置这些值之前，必须对来自请求的值进行身份验证和授权。每个请求的 ClickHouse 角色属于连接配置，而非租户授权边界。请使用 ClickHouse 用户、角色和授权来强制实施租户隔离。

开发

1. 在 test-services 目录中运行 docker compose up -d 以启动 ClickHouse 集群。

2. 将以下变量添加到仓库根目录的 .env 文件中。

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

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

3. 运行 uv sync 安装依赖项。要安装 uv，请按照此处的说明操作。然后执行 source .venv/bin/activate。

4. 为便于使用 MCP Inspector 进行测试，请运行 fastmcp dev mcp_clickhouse/mcp_server.py 启动 MCP 服务器。

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

# For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000 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

环境变量

配置分为独立的组。将它们混用是导致难以排查的连接失败的常见原因：

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

例如：如果 MCP 服务器在 Kubernetes 中运行于终止 TLS 的 ingress 之后，那属于 MCP 传输层面的问题。请让 CLICKHOUSE_SECURE 与 Pod 访问 ClickHouse 自身的方式保持一致（HTTPS → true，纯 HTTP → false）。如果因为 MCP 服务器位于 ingress 之后而将 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 数据库用户视为连接到数据库的任何外部客户端，仅授予其运行所需的最低必要权限。在任何时候都应严格避免使用 default 用户或管理员用户。

可选变量

• 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 角色

  • 默认值：None

  • 如果你的用户需要特定角色，请设置此项

• CLICKHOUSE_SECURE：为 ClickHouse 数据库连接启用 HTTPS（而非为 MCP 客户端）

  • 默认值："true"

  • 仅当 MCP 服务器通过纯 HTTP 访问 ClickHouse 时（典型场景是本地 Docker Compose 使用端口 8123），才设置为 "false"

  • 对于 ClickHouse Cloud 和任何 HTTPS 数据库端点，请保持 "true"——即使 MCP 服务器本身通过 HTTP、stdio 或单独终止 TLS 的 ingress 暴露

  • 将此标志与数据库端口不匹配（例如对端口 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 覆盖和证书验证的服务器主机名

  • 默认值：None（使用连接主机名）

  • 当通过代理或负载均衡器连接且证书主机名与连接主机名不同时，此选项非常有用。设置后，该主机名将同时用于 TLS 握手期间的 SNI（服务器名称指示）和证书主机名验证。

• CLICKHOUSE_PROXY_PATH：ClickHouse HTTP 端点的 URL 路径前缀

  • 默认值：None

  • 当 ClickHouse HTTP 接口通过反向代理以路径前缀（例如 /clickhouse）暴露时，请设置此项

• CLICKHOUSE_CONNECT_TIMEOUT：ClickHouse 客户端的连接超时时间（秒）

  • 默认值："30"

  • 如果遇到连接超时，请增大此值

• CLICKHOUSE_SEND_RECEIVE_TIMEOUT：ClickHouse 客户端的发送/接收超时时间（秒）

  • 默认值："300"

  • 对于长时间运行的查询，请增大此值

• CLICKHOUSE_DATABASE：要使用的默认 ClickHouse 数据库

  • 默认值：None（使用服务器默认值）

  • 设置此项可自动连接到特定数据库

• CLICKHOUSE_ENABLED：启用/禁用 ClickHouse 数据库工具

  • 默认值："true"

  • 当仅使用 chDB 时，设置为 "false" 可禁用 ClickHouse 工具

• CLICKHOUSE_ALLOW_WRITE_ACCESS：允许对 ClickHouse 执行写操作（DDL 和 DML）

  • 默认值："false"

  • 设置为 "true" 可允许非破坏性 DDL 和 DML（CREATE、INSERT、ALTER ADD COLUMN）。破坏性语句还需要 CLICKHOUSE_ALLOW_DROP=true

  • 禁用时（默认），查询将以 readonly=1 设置运行，以防止数据修改

• CLICKHOUSE_ALLOW_DROP：允许破坏性操作（任何 DROP 或 TRUNCATE、DELETE 和 UPDATE（包括 ALTER TABLE 变体）、REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE、CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION，以及 DETACH ... PERMANENTLY）

  • 默认值："false"

  • 仅当同时设置 CLICKHOUSE_ALLOW_WRITE_ACCESS=true 时才生效

  • 此开关是 MCP 服务器中尽力而为的误操作防护，而非安全边界。要实现真正的强制，请限制 ClickHouse 用户的授权（参见破坏性操作保护）

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 传输的静态 Bearer token

  • 默认值：无

  • 对于 HTTP/SSE 传输，CLICKHOUSE_MCP_AUTH_TOKEN、FASTMCP_SERVER_AUTH 或 CLICKHOUSE_MCP_AUTH_DISABLED=true 三者之一为必需

  • 使用 uuidgen 或 openssl rand -hex 32 生成

  • 客户端必须在 Authorization: Bearer <token> 请求头中发送此 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" 以仅针对本地开发/测试禁用身份验证

  • 警告： 仅用于本地开发。暴露到网络时请勿禁用

• CLICKHOUSE_MCP_ALLOWED_HOSTS：HTTP/SSE 服务器响应的逗号分隔的 Host 请求头值

  • 回环绑定的默认值：127.0.0.1、localhost 和 [::1] 的裸形式及任意端口形式

  • 如果设置，该值必须至少包含一个 Host 条目。

  • 具体的非回环绑定地址默认为该地址和配置的端口。通配符绑定（如 0.0.0.0 或 ::）需要显式的非空值，因为无法推断公共 Host。

  • Host 验证是针对 DNS 重绑定的纵深防御。下面的 Origin 验证由 MCP 单独要求。

  • 条目是精确的（localhost:8000）或接受任意端口（localhost:*）。示例：CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

  • host:* 形式仅匹配带有端口的 Host 值。无端口的 Host（客户端省略 :80/:443 的标准端口部署）也必须列为裸精确条目（example.com）。

  • 带有不匹配或缺失 Host 请求头的请求会收到 421 Misdirected Request。对 /health 的 GET 和 HEAD 请求不受 Host 和 Origin 验证限制，以便编排器探针继续工作。

  • 在反向代理后面，列出代理转发的 Host 值。当 fastmcp run 等启动器为远程访问覆盖绑定地址时，请设置显式列表。

• CLICKHOUSE_MCP_ALLOWED_ORIGINS：HTTP/SSE 上接受的逗号分隔的 Origin 请求头值

  • 默认值：无，这会拒绝所有携带 Origin 请求头的请求

  • MCP 要求对 HTTP/SSE 传输连接进行 Origin 验证。没有 Origin 的请求会被接受，因为非浏览器 MCP 客户端通常会省略它。不匹配的 Origin 会收到 403 Forbidden。/health 端点如上所述不受此限制。

  • 条目是精确的（http://localhost:3000）或接受任意端口（http://localhost:*）。与 Host 一样，任意端口形式仅匹配带有端口的 Origin；标准端口 Origin（https://app.example.com）必须精确列出。

中间件变量

• 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 / ingress TLS — 因为 MCP 服务器位于 Kubernetes ingress、反向代理之后，或通过纯 HTTP 访问而关闭 CLICKHOUSE_SECURE 并不会禁用数据库 TLS；它只改变此进程连接 ClickHouse 的方式。请将 ingress 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

用于 MCP Inspector 或通过 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)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:4200,localhost:4200,mcp.example.com:4200  # Include every Host value clients and proxies send

使用 HTTP 传输进行本地开发（禁用身份验证）：

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

使用 HTTP 传输时，服务器将在配置的端口（默认 8000）上运行。例如，使用上述配置：

• MCP 端点：http://localhost:8000/mcp

• 健康检查：http://localhost:8000/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

YouTube 概述