analyticbase

analyticbase

analyticbase 可让 Agent（或在终端操作的你）查看 ClickHouse 数据库并向其提问，同时完全无法修改数据库。它会列出服务器上的数据库，列出某个数据库中的表及每个表的引擎、注释、行数和列数，并运行单条只读 SELECT 查询。所有通信都通过 ClickHouse 的普通 HTTP 接口进行，因此无需捆绑客户端库，也无需建立原生端口隧道。

如果 ClickHouse 不可用，analyticbase 会如实说明。即使没有后端服务器，MCP 服务也会启动并列出其工具；只有实际执行操作时才会发出请求。如果连接被拒绝或服务器返回错误，结果会是包含服务器原文的错误，而不会是凭空编造的行。

安装

npx @reneturcios/analyticbase list-databases

或者运行容器映像：

docker run -i ghcr.io/cloudcorprecords/analyticbase

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

# Which databases does this server hold?
analyticbase list-databases

# What tables live in one database? (name filters are LIKE patterns)
analyticbase list-tables analytics
analyticbase list-tables analytics --like "events_%" --not-like "%_tmp"

# Run one read-only query; rows print as JSON
analyticbase query "SELECT count() AS n FROM analytics.events"

# Start the MCP server
analyticbase mcp

analyticbase --version

退出码：成功时为 0；查询、保护机制或连接失败时为 1（错误信息会说明具体原因）；用法错误时为 2。

通过环境变量配置端点：

变量	含义	默认值
CLICKHOUSE_URL	HTTP 接口的完整基础 URL；优先于主机和端口设置	—
CLICKHOUSE_HOST	主机名，或完整的 http(s):// URL	localhost
CLICKHOUSE_PORT	HTTP 接口端口	8123
CLICKHOUSE_USER	用户名	default
CLICKHOUSE_PASSWORD	密码	（空）

查询的工作方式

每项操作都会将 SQL 作为请求正文，通过 POST 发送到 HTTP 接口，并将凭据作为 URL 参数传递——这是该接口自身的约定。列表操作会追加 FORMAT JSONEachRow，并逐行解析 JSON 对象；list_tables 会读取 system.tables，并通过对 system.columns 的子查询统计每个表的列数，同时将 like / not_like 筛选条件作为 LIKE / NOT LIKE 子句应用，并安全转义字面值。Select 查询会追加 FORMAT JSON，并返回响应中的 data 数组。

只读保护机制

run_select_query（以及 CLI 的 query 命令）只有在满足以下所有条件时才会接受查询：

• 去除开头的空白和注释后，第一个关键字是 SELECT 或 WITH。
• 查询只能包含一条语句：分号后如果有任何非空白内容，查询就会被拒绝。
• 字符串字面值之外不能出现 INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、TRUNCATE、GRANT、REVOKE、OPTIMIZE、RENAME、DETACH 或 ATTACH 这些完整单词。扫描前会将单引号字面值清空，因此 SELECT 'drop table t' 是合法查询；但名称恰好为 update 的列则不行——对于奇怪的名称，保护机制宁愿拒绝，也不会被绕过。

列表操作会使用经过验证和转义的片段在内部构建 SQL，因此无需保护机制。

MCP 服务

同一个可执行文件提供这两种用法。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/analyticbase mcp

MCP 客户端配置：

{
  "mcpServers": {
    "analyticbase": {
      "command": "npx",
      "args": ["-y", "@reneturcios/analyticbase", "mcp"],
      "env": { "CLICKHOUSE_HOST": "localhost", "CLICKHOUSE_PORT": "8123" }
    }
  }
}

工具

工具	输入	返回内容
list_databases	（无）	来自 system.databases 的数据库对象，每个数据库一个。
list_tables	database（字符串，必填），like / not_like（字符串，可选）	该数据库中每个表对应的一个对象，包含其架构（数据库）、名称、引擎、注释、行数和列数。
run_select_query	query（字符串，必填）——一条只读 SQL 语句	结果行，以 JSON 对象数组形式返回，键为列名。违反保护规则、服务器缺失和数据库错误都会作为工具错误返回，不会返回编造的行。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, no live ClickHouse
npm run dev     # run the CLI from source via tsx

所有 HTTP 请求都通过可注入的 fetch 函数发送，测试套件会调用该函数：配置解析、保护机制、SQL 构建、两种响应格式解析器以及全部三项操作，都会通过模拟 fetch 进行测试。

许可证

MIT——详见 LICENSE。