ClickHouse MCP服务器项目详细介绍

概述

ClickHouse MCP服务器是由ClickHouse官方开发的Model Context Protocol (MCP)服务器实现，专门为AI助手（如Claude）提供与ClickHouse数据库的安全连接和交互能力。该项目通过标准化的MCP协议，让AI助手能够执行SQL查询、管理数据库结构，并进行实时数据分析。

MCP（Model Context Protocol）是一个开放标准，旨在为AI应用提供安全、标准化的外部服务集成方式。通过这个服务器，用户可以让AI助手直接访问他们的ClickHouse数据库，实现智能数据查询和分析。

核心功能

1. SQL查询执行 (run_select_query)

• 功能描述: 在ClickHouse集群上执行SQL查询
• 安全机制: 所有查询都在readonly = 1模式下运行，确保数据安全
• 输入参数:
  • sql (字符串): 要执行的SQL查询语句
• 使用场景: 数据检索、统计分析、报表生成

2. 数据库管理 (list_databases)

• 功能描述: 列出ClickHouse集群中的所有数据库
• 用途: 数据库结构探索、权限验证
• 返回内容: 可访问的数据库列表

3. 表格管理 (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_HOST: ClickHouse服务器主机名
• CLICKHOUSE_USER: 认证用户名
• CLICKHOUSE_PASSWORD: 认证密码

可选变量

• CLICKHOUSE_PORT: 端口号
  • 默认: HTTPS启用时为8443，禁用时为8123
• CLICKHOUSE_SECURE: 启用/禁用HTTPS连接
  • 默认: "true"
• CLICKHOUSE_VERIFY: 启用/禁用SSL证书验证
  • 默认: "true"
• CLICKHOUSE_CONNECT_TIMEOUT: 连接超时时间（秒）
  • 默认: "30"
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: 发送/接收超时时间（秒）
  • 默认: "300"
• CLICKHOUSE_DATABASE: 默认连接的数据库
  • 默认: 无（使用服务器默认）

使用场景

1. ClickHouse SQL演练场配置

{
  "env": {
    "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
    "CLICKHOUSE_PORT": "8443",
    "CLICKHOUSE_USER": "demo",
    "CLICKHOUSE_PASSWORD": "",
    "CLICKHOUSE_SECURE": "true",
    "CLICKHOUSE_VERIFY": "true"
  }
}

2. 本地开发环境配置

# .env文件配置
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_SECURE=false
CLICKHOUSE_VERIFY=false

3. ClickHouse Cloud配置

CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password
# 使用安全默认设置

开发与测试

环境准备

# 安装依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate

# 启动开发服务器
mcp dev mcp_clickhouse/mcp_server.py

测试流程

# 安装开发依赖
uv sync --all-extras --dev

# 代码检查
uv run ruff check .

# 启动测试服务
docker compose up -d test_services

# 运行测试
uv run pytest tests

安全考虑

数据库权限管理

• 最小权限原则: MCP数据库用户应只拥有必要的最小权限
• 避免管理员账户: 严禁使用默认或管理员用户
• 只读模式: 所有查询都在只读模式下执行，防止数据修改

网络安全

• HTTPS连接: 生产环境建议启用HTTPS
• 证书验证: 启用SSL证书验证确保连接安全
• 超时设置: 合理设置连接和查询超时，防止资源占用

技术特性

兼容性

• Python版本: 支持Python 3.13
• 依赖管理: 使用uv进行包管理
• 容器化: 支持Docker部署
• 跨平台: 支持macOS、Windows、Linux

性能优化

• 连接池: 高效的数据库连接管理
• 超时控制: 可配置的连接和查询超时
• 异步支持: 支持异步查询执行

总结

ClickHouse MCP服务器项目为AI助手与ClickHouse数据库之间搭建了一座安全、高效的桥梁。通过标准化的MCP协议，它让AI助手能够理解和操作复杂的数据库结构，执行sophisticated的SQL查询，并提供实时的数据洞察。

主要优势

1. 官方支持: 由ClickHouse官方维护，确保兼容性和稳定性
2. 安全设计: 内置只读模式和权限控制，保护数据安全
3. 易于集成: 标准化的MCP协议，简化AI应用集成
4. 灵活配置: 支持多种部署场景，从本地开发到云端生产
5. 开发友好: 完整的开发工具链和测试框架

适用场景

• 数据分析: 让AI助手协助进行复杂的数据分析任务
• 商业智能: 自动化报表生成和数据洞察
• 实时监控: 结合AI进行系统和业务指标监控
• 数据探索: 通过自然语言查询探索数据库结构和内容

这个项目代表了AI与数据库集成的新方向，为开发者提供了一个强大而安全的工具，让AI助手能够真正理解和操作企业级数据资源。