使用说明

ClickHouse MCP服务器

ClickHouse的MCP服务器。

特性

ClickHouse工具

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

chDB工具

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

健康检查端点

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

退货 200 OK 如果服务器运行正常并且可以连接到ClickHouse，则使用ClickHouse版本
退货 503 Service Unavailable 如果服务器无法连接到ClickHouse

例子：

curl http://localhost:8000/health
# Response: OK - Connected to ClickHouse 24.3.1

配置

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

打开位于以下位置的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.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游乐场，您可以使用以下配置：

{
  "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 Desktop以应用更改。

在没有uv的情况下运行（使用Python系统）

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

使用pip安装软件包：

python3 -m pip install mcp-clickhouse

要升级到最新版本：

python3 -m pip install --upgrade mcp-clickhouse

更新您的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 对于已安装的脚本

发展

在……里面 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检查器进行测试，请运行 fastmcp dev mcp_clickhouse/mcp_server.py 启动MCP服务器。

要使用HTTP传输和健康检查端点进行测试，请执行以下操作：

# Using default port 8000
CLICKHOUSE_MCP_SERVER_TRANSPORT=http python -m mcp_clickhouse.main

# Or with a custom port
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_BIND_PORT=4200 python -m mcp_clickhouse.main

# Then in another terminal:
curl http://localhost:8000/health  # or http://localhost:4200/health for custom port

环境变量

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

ClickHouse变量

必需变量

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

[！小心] 将MCP数据库用户视为连接到数据库的任何外部客户端，只授予其操作所需的最低权限，这一点很重要。应始终严格避免使用默认用户或管理用户。

可选变量

CLICKHOUSE_PORT：ClickHouse服务器的端口号
- 违约： 8443 如果启用了HTTPS， 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进行本地开发：

# 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游乐场：

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检查器或使用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)

使用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 # 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
uv run pytest -v tests/test_chdb_tool.py # chDB only

ClickHouse查询服务

使用说明

ClickHouse MCP服务器

特性

ClickHouse工具

chDB工具

健康检查端点

配置

在没有uv的情况下运行（使用Python系统）

发展

环境变量

ClickHouse变量

必需变量

可选变量

chDB变量

示例配置

运行测试

YouTube概述

使用说明

ClickHouse MCP服务器

特性

ClickHouse工具

chDB工具

健康检查端点

配置

在没有uv的情况下运行（使用Python系统）

发展

环境变量

ClickHouse变量

必需变量

可选变量

chDB变量

示例配置

运行测试

YouTube概述

相关 MCP

DBHub 数据库MCP服务器

MySQL数据库管理工具

MySQL数据库MCP服务

StarRocks 数据库 MCP 服务器

Supabase MCP 服务器

Text2SQL查询工具