星战科技xingzhan.cloud
返回市场
麦普点击屋

麦普点击屋

作者：ClickHouse599 星标更新：2025-11-14
安装使用来源：spider==github.com

项目介绍

ClickHouse MCP Server

PyPI - 版本

这是一个用于ClickHouse的MCP服务器。

<a href="https://glama.ai/mcp/servers/yvjy4csvo1"><img width="380" height="200" src="https://gips3.baidu.com/it/u=3595331081,2145566475&fm=3081&app=3081&f=PNG?w=760&h=400" alt="mcp-clickhouse MCP服务器" /></a>

功能

ClickHouse工具

  • run_select_query

    • 在您的ClickHouse集群上执行SQL查询。
    • 输入：sql（字符串）：要执行的SQL查询。
    • 所有ClickHouse查询都以readonly = 1运行，以确保它们是安全的。

  • 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查询。
    • 输入：sql（字符串）：要执行的SQL查询。
    • 直接从各种来源（文件、URL、数据库）查询数据，无需ETL过程。

健康检查端点

当使用HTTP或SSE传输运行时，在/health处提供健康检查端点。该端点：

  • 如果服务器正常且能够连接到ClickHouse，则返回200 OK并附带ClickHouse版本。
  • 如果服务器无法连接到ClickHouse，则返回503 Service Unavailable。

示例：

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

配置

此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_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以应用更改。

不使用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 对于已安装的脚本

开发

  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传输和健康检查端点进行测试：

    # 使用默认端口8000
CLICKHOUSE_MCP_SERVER_TRANSPORT=http python -m mcp_clickhouse.main

# 或使用自定义端口
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_BIND_PORT=4200 python -m mcp_clickhouse.main

# 然后在另一个终端中：
curl http://localhost:8000/health  # 或者对于自定义端口 http://localhost:4200/health

环境变量

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

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"以禁用证书验证（不推荐用于生产）
    • 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_ENABLED：启用/禁用ClickHouse功能
    • 默认值："true"
    • 设置为"false"以禁用ClickHouse工具，仅使用chDB

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=your_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）

使用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 # 安装开发依赖项
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