clickhouse/mcp-clickhouse

开发工具官方

本页由 AI 翻译，技术细节请以原文为准。查看原文

900 stars 210 forks 质量 87 趋势 44Apache-2.0

Repository Install

将ClickHouse与您的AI助手连接起来。

概览

* run_query * 在你的 ClickHouse 集群上执行 SQL 查询。* 输入：查询（字符串）：要执行的 SQL 查询。* 查询默认只读模式运行（CLICKHOUSE_ALLOW_WRITE_ACCESS=false），但如有需要，可以显式启用写入。 * list_databases * 列出你ClickHouse集群上的所有数据库。 * list_tables * 在数据库中列出带有分页功能的表。* 必填输入：数据库（字符串）。* 可选输入：* like / not_like（字符串）：对表名应用LIKE或NOT过滤器。* page_token（字符串）：由之前调用返回的令牌，用于获取下一页。* page_size（整数，默认50）：每页返回的表数。* include_detailed_columns（bool，默认true）：当错误时，省略列元数据以减少响应，同时保持完整 create_table_query。* 响应形状：* tables：当前页面的表对象数组。* next_page_token：将此值回传以获取下一页，或在没有更多表时返回空值。

概述（AI 翻译）

ClickHouse 的 MCP 服务器。

服务器实现了MCP 2026-07-28，并支持从以下平台进行遗留初始化握手 [2024-11-05 到 2025-11-25。现代客户端使用无会话请求和 server/discover。现有客户端可以继续协商遗留协议。

[!注] 没有MCP-Protocol-Version]的HTTP请求会通过遗留处理路由，因此之前的客户端2025-06-18可以继续连接。MCP 2026-07-28 许可支持这些客户端的服务器上出现这种行为。现代客户端应该发送每个POST请求都要>个头。

特色

点击屋工具

ClickHouse 工具响应是 JSON 编码的字符串。整数外部 [-9007199254740991, 9007199254740991] 返回为十进制字符串以保持精确 JavaScript客户端中的值。这适用于查询行和整数表元数据。安全范围整数和布尔保持其 JSON 类型。

run_query
在您的ClickHouse集群上执行SQL查询。
输入：query（字符串）：要执行的SQL查询。
可选输入：params（对象）：ClickHouse {name:Type} 占位符的命名值。参见查询参数。

本页由 AI 翻译，技术细节请以原文为准。

README

以下为原文 README 节选，完整内容请查看原文。

ClickHouse MCP Server

An MCP server for ClickHouse.

The server implements MCP 2026-07-28 and supports legacy initialize handshakes from 2024-11-05 through 2025-11-25. Modern clients use sessionless requests and server/discover. Existing clients can continue to negotiate the legacy protocol.

[!NOTE] HTTP requests without MCP-Protocol-Version are routed through legacy handling so clients from before 2025-06-18 can continue to connect. MCP 2026-07-28 permits this behavior on servers that support those clients. Modern clients should send the header on every POST request.

Features

ClickHouse Tools

ClickHouse tool responses are JSON-encoded strings. Integers outside [-9007199254740991, 9007199254740991] are returned as decimal strings to preserve exact values in JavaScript clients. This applies to query rows and integer table metadata. Safe-range integers and booleans keep their JSON types.

run_query
- Execute SQL queries on your ClickHouse cluster.
- Input: query (string): The SQL query to execute.
- Optional input: params (object): Named values for ClickHouse {name:Type} placeholders. See Query parameters.
- Queries run in read-only mode by default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), but writes can be enabled explicitly if needed.
- DESCRIBE () and EXPLAIN ESTIMATE run here too and are optional ways to inspect a query’s result schema or its estimated reads. See Checking a query before running it.
list_databases
- List all databases on your ClickHouse cluster.
list_tables
- List tables in a database with pagination.
- Required input: database (string).
- Optional inputs:
  - like / not_like (string): Apply LIKE or NOT LIKE filters to table names.
  - page_token (string): Single-use token returned by a previous call. It is retained for up to one hour.
  - page_size (int, default 50): Number of tables returned per page; must be greater than 0.
  - include_detailed_columns (bool, default true): When false, omits column metadata for lighter responses while keeping the full create_table_query.
- Response shape:
  - tables: Array of table objects for the current page.
  - next_page_token: Pass this single-use value back before it expires to fetch the next page, or null when there are no more tables.
  - total_tables: Total count of tables that match the supplied filters.

Agents Schema discovery

The server instructions suggest reading Agents Schema’s

在 GitHub 查看完整 README

安装

This server does not publish a one-line install command.

Open the repository installation guide 新手？先看 mcpskill.org 教程 →

配置

{
     "mcpServers": {
       "mcp-clickhouse": {
         "url": "http://127.0.0.1:8000",
         "headers": {
           "Authorization": "Bearer your-generated-token"
         }
       }
     }
   }