mcp-clickhouse

GitHub
747 175 简单 1 次阅读 3天前Apache-2.0数据工具插件
AI 解读 由 AI 自动生成，仅供参考

mcp-clickhouse 是一款专为 AI 助手设计的桥梁工具，旨在让大语言模型能够直接连接并操作 ClickHouse 数据库。它解决了传统模式下 AI 无法实时访问企业级数据仓库、需依赖繁琐中间件或手动导出数据的痛点，使开发者能通过自然语言指令让 AI 自动执行 SQL 查询、浏览数据库结构或直接分析本地文件。

该工具主要面向后端开发者、数据工程师及构建 AI 应用的研究人员。通过集成 Model Context Protocol (MCP) 标准，mcp-clickhouse 提供了丰富的功能集：既支持对远程 ClickHouse 集群进行安全的只读查询、分页列出库表结构，也内置了 chDB 引擎，允许无需 ETL 过程即可直接查询本地文件或 URL 中的数据。此外，它还具备完善的健康检查机制和灵活的认证配置，确保在生产环境 HTTP/SSE 传输模式下的安全性，同时保留本地开发模式的便捷性。无论是需要快速验证数据原型的工程师，还是希望为 AI 代理赋予实时数据洞察能力的团队，mcp-clickhouse 都能提供高效、安全且低门槛的解决方案。

使用场景

某电商数据分析师需要在晨会前快速从亿级订单日志中定位昨日异常交易，并生成简要报告。

没有 mcp-clickhouse 时

  • 分析师必须手动切换到数据库客户端，编写并调试复杂的 SQL 语句来查询 ClickHouse 集群，过程繁琐且容易出错。
  • 面对成百上千张分表，需要反复执行命令列出数据库和表名，难以通过自然语言快速筛选目标数据表。
  • 将查询结果复制粘贴到 AI 对话框进行解读时，上下文断裂，AI 无法直接结合实时数据给出深度洞察。
  • 每次临时取数都需经历“查文档 - 写代码 - 跑脚本 - 导数据”的长链路，严重拖慢晨会决策效率。
  • 若需验证本地文件数据与线上差异，还得额外搭建 ETL 流程或下载海量数据到本地，耗时耗力。

使用 mcp-clickhouse 后

  • 分析师直接在对话中指令 mcp-clickhouse 执行 run_query，工具自动以只读模式安全地返回亿级数据的聚合结果。
  • 通过 list_tables 配合模糊过滤参数，瞬间锁定包含"order"字样的特定业务表，无需记忆冗长的表名。
  • AI 助手调用工具获取实时数据后，立即在同一对话窗口内完成异常检测、归因分析并生成自然语言报告。
  • 整个取数分析过程缩短为几分钟的对话交互，分析师可专注于业务逻辑而非数据提取的技术细节。
  • 利用内置的 chDB 功能，直接对本地 CSV 日志运行 SQL 并与线上数据对比，彻底免去了繁琐的数据搬运过程。

mcp-clickhouse 将原本割裂的数据库操作无缝融入 AI 对话流，让海量数据分析变得像日常聊天一样简单高效。

运行环境要求

操作系统
  • Linux
  • macOS
  • Windows
GPU

未说明

内存

未说明

依赖
notes该工具是一个 ClickHouse MCP 服务器，支持通过 uv 或系统 Python 运行。默认情况下需要配置 ClickHouse 连接信息（主机、端口、用户、密码等），也可选择使用嵌入式的 chDB 引擎无需外部数据库。HTTP/SSE 传输模式默认需要身份验证令牌，本地开发可禁用但生产环境严禁禁用。支持自定义中间件扩展功能。写操作和破坏性操作（如 DROP）需显式开启环境变量保护。
python3.10+
mcp-clickhouse
uv
chdb (可选)
fastmcp
mcp-clickhouse hero image

快速开始

ClickHouse MCP 服务器

PyPI - 版本

一个用于 ClickHouse 的 MCP 服务器。

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 流程。

健康检查端点

当使用 HTTP 或 SSE 传输协议时，健康检查端点位于 /health。该端点：

  • 如果服务器运行正常且能够连接到 ClickHouse，则返回 200 OK 并附带 ClickHouse 版本信息。
  • 如果服务器无法连接到 ClickHouse，则返回 503 服务不可用。

示例：

curl http://localhost:8000/health
# 响应：OK - 已连接到 ClickHouse 24.3.1

安全性

HTTP/SSE 传输的认证

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

设置认证

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

    # 使用 uuidgen（macOS/Linux）
uuidgen

# 使用 openssl
openssl rand -hex 32

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

    export CLICKHOUSE_MCP_AUTH_TOKEN="您生成的令牌"

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

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

    {
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer 您生成的令牌"
      }
    }
  }
}

    对于命令行工具：

    curl -H "Authorization: Bearer 您生成的令牌" http://localhost:8000/health

开发模式（禁用认证）

仅限本地开发和测试时，可以通过以下设置禁用认证：

export CLICKHOUSE_MCP_AUTH_DISABLED=true

警告： 请仅在本地开发时使用此设置。切勿在服务器暴露于任何网络时禁用认证。

配置

该 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",
        "--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-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"
      }
    }
  }
}

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

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

这种两层机制确保了意外执行 DROP 操作的可能性极低：

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

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

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

  1. 使用 pip 安装该包：

    python3 -m pip install mcp-clickhouse

    要升级到最新版本：

    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):
    """记录所有工具调用。"""
    
    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"调用工具：{tool_name}")
        result = await call_next(context)
        logger.info(f"工具 {tool_name} 执行完毕")
        return result

def setup_middleware(mcp):
    """将中间件注册到 MCP 服务器。"""
    mcp.add_middleware(LoggingMiddleware())
  1. 将 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"
      }
    }
  }
}
  1. 确保您的中间件模块位于 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
})

这使得一些高级用法成为可能，例如动态调整超时时间、按租户路由，或为每个用户设置不同的连接参数。

开发

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

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

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

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

  1. 运行 uv sync 来安装依赖项。要安装 uv，请按照 这里 的说明进行操作。然后执行 source .venv/bin/activate。

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

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

    # 对于开发，禁用身份验证
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main

# 或者启用身份验证（先生成令牌）
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main

# 然后在另一个终端中：
# 如果已禁用身份验证：
curl http://localhost:8000/health

# 如果启用身份验证：
curl -H "Authorization: Bearer your-token" http://localhost:8000/health

环境变量

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

ClickHouse 变量

必需变量
  • CLICKHOUSE_HOST：您的 ClickHouse 服务器的主机名
  • CLICKHOUSE_USER：用于身份验证的用户名
  • CLICKHOUSE_PASSWORD：用于身份验证的密码

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

可选变量
  • CLICKHOUSE_PORT：您的 ClickHouse 服务器的端口号
    • 默认值：如果启用了 HTTPS，则为 8443；如果未启用，则为 8123。
    • 通常无需设置，除非使用非标准端口。
  • CLICKHOUSE_ROLE：用于身份验证的角色
    • 默认值：无
    • 如果您的用户需要特定角色，请设置此变量。
  • CLICKHOUSE_SECURE：启用或禁用 HTTPS 连接
    • 默认值："true"
    • 对于非安全连接，将其设置为 "false"。
  • CLICKHOUSE_VERIFY：启用或禁用 SSL 证书验证
    • 默认值："true"
    • 将其设置为 "false" 可以禁用证书验证（不建议在生产环境中使用）。
    • TLS 证书：该包通过 truststore 使用您的操作系统信任存储来验证 TLS 证书。我们在启动时调用 truststore.inject_into_ssl()，以确保正确处理证书。只有在发生意外错误时，才会回退到 Python 的默认 SSL 行为。
  • 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_MCP_QUERY_TIMEOUT：SELECT 工具的超时时间（秒）
    • 默认值："30"
    • 如果遇到 Query timed out after ... 错误，对于复杂查询可以适当延长此时间。
  • CLICKHOUSE_MCP_AUTH_TOKEN：用于 HTTP/SSE 传输的身份验证令牌
    • 默认值：无
    • 必须在使用 HTTP 或 SSE 传输时提供（除非 CLICKHOUSE_MCP_AUTH_DISABLED=true）。
    • 可以使用 uuidgen 或 openssl rand -hex 32 生成令牌。
    • 客户端必须在 Authorization: Bearer <token> 头中发送此令牌。
  • CLICKHOUSE_MCP_AUTH_DISABLED：禁用 HTTP/SSE 传输的身份验证
    • 默认值："false（身份验证已启用）。
    • 设置为 "true" 只能在本地开发/测试时禁用身份验证。
    • 警告： 仅限于本地开发使用。切勿在网络环境中启用此功能。
  • CLICKHOUSE_ENABLED：启用或禁用 ClickHouse 功能
    • 默认值："true"
    • 设置为 "false" 可以在仅使用 chDB 时禁用 ClickHouse 工具。
  • CLICKHOUSE_ALLOW_WRITE_ACCESS：允许写操作（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_MIDDLEWARE_MODULE：包含自定义中间件的 Python 模块名称，用于注入到 MCP 服务器中
    • 默认值：无（未加载中间件）。
    • 设置为您中间件模块的名称（不带 .py 扩展名）。
    • 该模块必须提供一个 setup_middleware(mcp) 函数。
    • 有关详细信息和示例，请参阅 自定义中间件。

chDB 变量

  • CHDB_ENABLED：启用或禁用 chDB 功能
    • 默认值："false"
    • 设置为 "true" 可以启用 chDB 工具。
  • CHDB_DATA_PATH：chDB 数据目录的路径
    • 默认值：":memory:"（内存数据库）。
    • 使用 :memory: 可以创建内存数据库。
    • 使用文件路径可以实现持久化存储（例如 /path/to/chdb/data）。

示例配置

用于 Docker 的本地开发：

# 必需变量
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# 可选：覆盖本地开发的默认值
CLICKHOUSE_SECURE=false  # 自动使用 8123 端口
CLICKHOUSE_VERIFY=false

用于 ClickHouse Cloud：

# 必需变量
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# 可选：这些使用安全默认值
# CLICKHOUSE_SECURE=true  # 自动使用 8443 端口

# CLICKHOUSE_DATABASE=您的数据库

适用于 ClickHouse SQL Playground：

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# 使用安全默认设置（HTTPS，端口 8443）

仅使用 chDB（内存中）：

# chDB 配置
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH 默认为 :memory:

使用持久化存储的 chDB：

# chDB 配置
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  # 绑定到所有接口
CLICKHOUSE_MCP_BIND_PORT=4200  # 自定义端口（默认：8000）
CLICKHOUSE_MCP_AUTH_TOKEN=您生成的令牌  # HTTP/SSE 需要

用于本地开发且禁用身份验证的 HTTP 传输：

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # 仅限本地开发！

使用 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": "<可选数据库>",
        "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 # 安装开发依赖
uv run ruff check . # 运行代码检查

docker compose up -d test_services # 启动 ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # 仅针对 ClickHouse
uv run pytest -v tests/test_chdb_tool.py # 仅针对 chDB

YouTube 概览

YouTube

版本历史

v0.2.02026/01/28
v0.1.132025/12/16

常见问题

相似工具推荐

openclaw

OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。 这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。 OpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你

★ 349.3k|★★★☆☆|3天前
Agent开发框架图像

markitdown

MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。 在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。 这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器

★ 93.4k|★★☆☆☆|3天前
插件开发框架

ML-For-Beginners

ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。 无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。

★ 85.1k|★★☆☆☆|昨天
图像数据工具视频

funNLP

funNLP 是一个专为中文自然语言处理（NLP）打造的超级资源库，被誉为"NLP 民工的乐园”。它并非单一的软件工具，而是一个汇集了海量开源项目、数据集、预训练模型和实用代码的综合性平台。 面对中文 NLP 领域资源分散、入门门槛高以及特定场景数据匮乏的痛点，funNLP 提供了“一站式”解决方案。这里不仅涵盖了分词、命名实体识别、情感分析、文本摘要等基础任务的标准工具，还独特地收录了丰富的垂直领域资源，如法律、医疗、金融行业的专用词库与数据集，甚至包含古诗词生成、歌词创作等趣味应用。其核心亮点在于极高的全面性与实用性，从基础的字典词典到前沿的 BERT、GPT-2 模型代码，再到高质量的标注数据和竞赛方案，应有尽有。 无论是刚刚踏入 NLP 领域的学生、需要快速验证想法的算法工程师，还是从事人工智能研究的学者，都能在这里找到急需的“武器弹药”。对于开发者而言，它能大幅减少寻找数据和复现模型的时间；对于研究者，它提供了丰富的基准测试资源和前沿技术参考。funNLP 以开放共享的精神，极大地降低了中文自然语言处理的开发与研究成本，是中文 AI 社区不可或缺的宝藏仓库。

★ 79.9k|★☆☆☆☆|今天
语言模型数据工具其他

cs-video-courses

cs-video-courses 是一个精心整理的计算机科学视频课程清单，旨在为自学者提供系统化的学习路径。它汇集了全球知名高校（如加州大学伯克利分校、新南威尔士大学等）的完整课程录像，涵盖从编程基础、数据结构与算法，到操作系统、分布式系统、数据库等核心领域，并深入延伸至人工智能、机器学习、量子计算及区块链等前沿方向。 面对网络上零散且质量参差不齐的教学资源，cs-video-courses 解决了学习者难以找到成体系、高难度大学级别课程的痛点。该项目严格筛选内容，仅收录真正的大学层级课程，排除了碎片化的简短教程或商业广告，确保用户能接触到严谨的学术内容。 这份清单特别适合希望夯实计算机基础的开发者、需要补充特定领域知识的研究人员，以及渴望像在校生一样系统学习计算机科学的自学者。其独特的技术亮点在于分类极其详尽，不仅包含传统的软件工程与网络安全，还细分了生成式 AI、大语言模型、计算生物学等新兴学科，并直接链接至官方视频播放列表，让用户能一站式获取高质量的教育资源，免费享受世界顶尖大学的课堂体验。

★ 79.8k|★☆☆☆☆|今天
其他图像数据工具

OpenHands

OpenHands 是一个专注于 AI 驱动开发的开源平台，旨在让智能体（Agent）像人类开发者一样理解、编写和调试代码。它解决了传统编程中重复性劳动多、环境配置复杂以及人机协作效率低等痛点，通过自动化流程显著提升开发速度。 无论是希望提升编码效率的软件工程师、探索智能体技术的研究人员，还是需要快速原型验证的技术团队，都能从中受益。OpenHands 提供了灵活多样的使用方式：既可以通过命令行（CLI）或本地图形界面在个人电脑上轻松上手，体验类似 Devin 的流畅交互；也能利用其强大的 Python SDK 自定义智能体逻辑，甚至在云端大规模部署上千个智能体并行工作。 其核心技术亮点在于模块化的软件智能体 SDK，这不仅构成了平台的引擎，还支持高度可组合的开发模式。此外，OpenHands 在 SWE-bench 基准测试中取得了 77.6% 的优异成绩，证明了其解决真实世界软件工程问题的能力。平台还具备完善的企业级功能，支持与 Slack、Jira 等工具集成，并提供细粒度的权限管理，适合从个人开发者到大型企业的各类用户场景。

★ 70.9k|★★★☆☆|今天
语言模型Agent开发框架