简介

具有模式检查和查询功能的ClickHouse数据库集成

简介

具有模式检查和查询功能的ClickHouse数据库集成

ClickHouse MCP 服务器

一个用于 ClickHouse 的 MCP 服务器。

功能

工具

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

配置

打开位于以下位置的 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.13",
        "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 游乐场尝试它，可以使用以下配置：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "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"
      }
    }
  }
}

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

开发

在 test-services 目录中运行 docker compose up -d 来启动 ClickHouse 集群。
在存储库的根目录下添加一个 .env 文件，并添加以下变量。

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

运行 uv sync 安装依赖项。要安装 uv 请遵循此处的说明。然后执行 source .venv/bin/activate。
为了方便测试，您可以运行 mcp dev mcp_clickhouse/mcp_server.py 启动 MCP 服务器。

环境变量

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

必需变量

CLICKHOUSE_HOST: 您的 ClickHouse 服务器的主机名
CLICKHOUSE_USER: 用于身份验证的用户名
CLICKHOUSE_PASSWORD: 用于身份验证的密码

可选变量

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: 使用的默认数据库
- 默认值：无（使用服务器默认值）
- 设置此项以自动连接到特定数据库

示例配置

对于本地开发使用 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)

您可以在环境变量、.env 文件或 Claude Desktop 配置中设置这些变量：

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>"
      }
    }
  }
}

工具列表

list_databases:
list_tables:
run_select_query:

服务配置

[{'mcpServers': {'mcp-clickhouse': {'args': ['run', '--with', 'mcp-clickhouse', '--python', '3.13', 'mcp-clickhouse'], 'command': 'uv', 'env': {'CLICKHOUSE_CONNECT_TIMEOUT': '30', 'CLICKHOUSE_HOST': '<clickhouse-host>', 'CLICKHOUSE_PASSWORD': '<clickhouse-password>', 'CLICKHOUSE_PORT': '<clickhouse-port>', 'CLICKHOUSE_SECURE': 'true', 'CLICKHOUSE_SEND_RECEIVE_TIMEOUT': '30', 'CLICKHOUSE_USER': '<clickhouse-user>', 'CLICKHOUSE_VERIFY': 'true'}}}}, {'mcpServers': {'mcp-clickhouse': {'args': ['run', '--with', 'mcp-clickhouse', '--python', '3.13', 'mcp-clickhouse'], 'command': 'uv', 'env': {'CLICKHOUSE_CONNECT_TIMEOUT': '30', 'CLICKHOUSE_HOST': 'sql-clickhouse.clickhouse.com', 'CLICKHOUSE_PASSWORD': '', 'CLICKHOUSE_PORT': '8443', 'CLICKHOUSE_SECURE': 'true', 'CLICKHOUSE_SEND_RECEIVE_TIMEOUT': '30', 'CLICKHOUSE_USER': 'demo', 'CLICKHOUSE_VERIFY': 'true'}}}}, {'mcpServers': {'mcp-clickhouse': {'args': ['run', '--with', 'mcp-clickhouse', '--python', '3.13', 'mcp-clickhouse'], 'command': 'uv', 'env': {'CLICKHOUSE_DATABASE': '<optional-database>', 'CLICKHOUSE_HOST': '<clickhouse-host>', 'CLICKHOUSE_PASSWORD': '<clickhouse-password>', 'CLICKHOUSE_USER': '<clickhouse-user>'}}}}]

来源

来源：github
链接：https://github.com/ClickHouse/mcp-clickhouse

ClickHouse集成查询工具

简介

简介