ClickHouse MCP Server

ClickHouse的MCP服务器。

功能

ClickHouse工具

run_select_query
- 在您的ClickHouse集群上执行SQL查询。
- 输入：sql（字符串）：要执行的SQL查询。
- 所有ClickHouse查询都以readonly = 1运行以确保它们是安全的。
list_databases
- 列出您ClickHouse集群上的所有数据库。
list_tables
- 列出数据库中的所有表。
- 输入：database（字符串）：数据库名称。

chDB工具

run_chdb_select_query
- 使用chDB的嵌入式OLAP引擎执行SQL查询。
- 输入：sql（字符串）：要执行的SQL查询。
- 直接从各种来源（文件、URL、数据库）查询数据，无需ETL流程。

健康检查端点

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

如果服务器健康且可以连接到ClickHouse，则返回200 OK以及ClickHouse版本
如果服务器无法连接到ClickHouse，则返回503 Service Unavailable

示例：

curl http://localhost:8000/health
# 响应：OK - Connected to ClickHouse 24.3.1

配置

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

打开位于以下位置的Claude桌面配置文件：
- 在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_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（嵌入式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-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桌面以应用更改。

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

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

使用pip安装包：

python3 -m pip install mcp-clickhouse

要升级到最新版本：

python3 -m pip install --upgrade mcp-clickhouse

更新您的Claude桌面配置以直接使用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用于已安装脚本

开发

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

# 使用默认端口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"以禁用证书验证（不推荐用于生产环境）
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的本地开发：

# 必要变量
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=
# 使用安全默认值（端口8443上的HTTPS）

对于仅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桌面配置中设置：

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

ClickHouse/mcp-clickhouse

星标增长

证据时间轴