ClickHouse Readonly MCP

基本能力

产品定位

ClickHouse Readonly MCP 是一个专为执行只读ClickHouse查询设计的FastMCP服务，旨在提供高性能的查询执行和结果处理能力。

核心功能

• 支持通过MCP工具执行只读SQL查询
• 输入验证确保只能执行SELECT、SHOW、DESCRIBE、EXPLAIN等只读操作
• 支持HTTP和原生ClickHouse连接方式，自动故障切换
• 简洁的表格格式输出结果
• 支持参数化查询
• 高性能查询执行和结果处理

适用场景

• 需要执行只读ClickHouse查询的场景
• 需要高性能查询执行和结果处理的场景
• 需要自动故障切换的场景

工具列表

• clickhouse-readonly-mcp: 主服务工具，提供只读ClickHouse查询功能

常见问题解答

1. CLICKHOUSE_PORT为原生连接的端口，CLICKHOUSE_HTTP_PORT为HTTP协议端口，MCP会自动切换，不一定需要全部填写。
2. CLICKHOUSE_RESOURCE_DESC_FILE是一个说明文件，可以将数据库中的一些信息放入其中，例如表是做什么用的，能够提升模型理解能力。
3. CLICKHOUSE_ENABLED默认可以不用填。

使用教程

使用依赖

无特殊依赖，只需Python环境。

安装教程

通过pip安装

pip install clickhouse-readonly-mcp

从源代码安装

git clone https://github.com/the-nine-nation/clickhouse-mcp.git
cd clickhouse-readonly-mcp
pip install -e .

调试方式

配置示例（放入config.json）:

{
    "clickhouse": {
        "command": "python",
        "args": ["clickhouse_mcp_py"],
        "env": {
            "CLICKHOUSE_ENABLED": "true",
            "CLICKHOUSE_HOST": "ClickHouse database IP",
            "CLICKHOUSE_PORT": "ClickHouse database port",
            "CLICKHOUSE_HTTP_PORT": "",
            "CLICKHOUSE_DATABASE": "ClickHouse database name",
            "CLICKHOUSE_USERNAME": "ClickHouse database username",
            "CLICKHOUSE_PASSWORD": "ClickHouse database password",
            "CLICKHOUSE_RESOURCE_DESC_FILE": "Path to ClickHouse database resource description file"
        }
    }
}

注意事项: 1. CLICKHOUSE_PORT为原生连接的端口，CLICKHOUSE_HTTP_PORT为HTTP协议端口，MCP会自动切换，不一定需要全部填写。 2. CLICKHOUSE_RESOURCE_DESC_FILE是一个说明文件，可以将数据库中的一些信息放入其中。 3. CLICKHOUSE_ENABLED默认可以不用填。

许可证

该项目遵循 MIT 开源许可条款，请参阅 MIT 了解完整条款。