项目简介

Agent Zero 是一个基于 Model Context Protocol (MCP) 构建的服务器，专注于 ClickHouse 数据库的监控和管理。它允许 AI 助手（如 Claude）通过标准化的 MCP 协议与 ClickHouse 数据库进行交互，执行性能分析、资源监控、错误调查等多种数据库操作。

主要功能点

性能分析：追踪慢查询、分析查询执行模式和瓶颈。
资源监控：监控 ClickHouse 集群的内存、CPU 和磁盘使用情况。
表和分区管理：分析表分区、合并和存储效率。
错误调查：识别和解决 ClickHouse 集群中的错误和异常。
健康检查：生成全面的 ClickHouse 集群健康状态报告。
安全查询执行：支持执行 SELECT 查询并分析结果。

安装步骤

环境准备：
- 确保已安装 Python 3.13 或更高版本。
- 确保可以访问 ClickHouse 数据库/集群。
- 确保已安装支持 MCP 的 AI 助手客户端（如 Claude）。

安装 Agent Zero：

推荐使用虚拟环境安装，首先创建并激活虚拟环境：

python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate  # Windows

使用 pip 安装 Agent Zero：

pip install ch-agent-zero

服务器配置 (MCP 客户端配置)

要将 Agent Zero 配置为 MCP 服务器供 MCP 客户端（例如 Claude Desktop）使用，您需要在 MCP 客户端的配置文件中添加以下 JSON 配置。以下配置示例适用于 Claude Desktop，其他 MCP 客户端的配置方法类似，请参考其文档。

Claude Desktop 配置示例 (claude_desktop_config.json):

{
  "mcpServers": {
    "agent-zero": {  // 服务器名称，可以自定义
      "command": "<PATH_TO_YOUR_VENV>/bin/ch-agent-zero", // Agent Zero 启动命令的完整路径，需要替换为实际路径。如果使用 uv 安装，则替换为 uv 的路径
      "args": [],  // 启动命令的参数，Agent Zero 默认配置即可，无需额外参数
      "env": {  // 环境变量配置
        "CLICKHOUSE_HOST": "your-clickhouse-host",  // 替换为您的 ClickHouse 主机地址
        "CLICKHOUSE_PORT": "8443",  // ClickHouse 端口，默认 8443 (https) 或 8123 (http)，根据您的 ClickHouse 配置修改
        "CLICKHOUSE_USER": "your-username",  // ClickHouse 用户名
        "CLICKHOUSE_PASSWORD": "your-password",  // ClickHouse 密码
        "CLICKHOUSE_SECURE": "true",  // 是否使用 HTTPS 连接 ClickHouse，默认为 true
        "CLICKHOUSE_VERIFY": "true",  // 是否验证 SSL 证书，默认为 true
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",  // ClickHouse 连接超时时间，单位秒
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "300"  // ClickHouse 发送/接收超时时间，单位秒
      }
    }
  }
}

配置说明:

'command': 指向 'ch-agent-zero' 启动脚本的完整路径。如果您使用虚拟环境安装，请使用虚拟环境中的路径。您可以使用 'which ch-agent-zero' (macOS/Linux) 或 'where ch-agent-zero' (Windows) 命令查找路径。
'args': Agent Zero 默认配置即可，通常无需额外参数。
'env': 环境变量用于配置 Agent Zero 连接 ClickHouse 数据库的参数，请务必根据您的 ClickHouse 实际配置进行修改。

基本使用方法

配置完成后，重启您的 MCP 客户端 (如 Claude Desktop)。您可以通过自然语言指令指示 AI 助手使用 Agent Zero 监控和管理 ClickHouse 数据库。

例如，您可以向 Claude 提出以下问题：

"列出我的 ClickHouse 集群中的所有数据库"
"显示 'system' 数据库中的所有表"
"展示过去 24 小时内运行时间最长的 10 个查询"
"监控我的 ClickHouse 集群过去 3 天的内存使用趋势"
"运行 ClickHouse 集群的完整健康检查"

AI 助手会将这些指令转换为 MCP 请求发送给 Agent Zero 服务器，Agent Zero 执行相应的数据库操作并将结果返回给 AI 助手。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (MCP 客户端配置)

基本使用方法

信息