mcp-clickvisual
Provides tools for interacting with ClickHouse instances through ClickVisual: listing instances, databases, and log tables; resolving table IDs; searching logs with SQL WHERE clauses; and retrieving log histogram data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-clickvisual search logs for 'error' in the last hour"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-clickvisual
A Model Context Protocol (MCP) server for ClickVisual — a lightweight log analytics platform built on ClickHouse.
It lets any MCP-capable AI client (Claude Desktop, Cursor, Hermes Agent, ModelScope MCP Hub, ...) search logs, browse instances/databases/tables, and inspect log histograms directly from a chat.
中文说明见下方 中文文档。
Tools
Tool | Description |
| Verify the ClickVisual login state |
| List all ClickHouse instances |
| List databases under an instance |
| List log tables under a database |
| Resolve a numeric |
| Search logs with a SQL WHERE clause, e.g. |
| Get log histogram data (count distribution over time) |
Related MCP server: ClickHouse MCP Server
Configuration
All settings come from environment variables — no credentials are stored in the code:
Variable | Required | Description |
| ✅ | ClickVisual web address, e.g. |
| ✅ | Login username |
| ✅ | Login password (plain text; hashed with MD5 automatically before being sent) |
The server talks to ClickVisual's HTTP API with cookie-based session auth and re-authenticates automatically when the session expires.
Install
Requires Python 3.10+.
# from source
pip install git+https://github.com/wsws1888/mcp-clickvisual.git
# or from a local checkout
pip install .Run
# both of these start the stdio MCP server
mcp-clickvisual
python -m mcp_clickvisualClient configuration
Claude Desktop / Cursor / generic MCP JSON
{
"mcpServers": {
"clickvisual": {
"command": "python",
"args": ["-m", "mcp_clickvisual"],
"env": {
"CV_BASE_URL": "http://your-clickvisual-host:19001",
"CV_USERNAME": "your-username",
"CV_PASSWORD": "your-password"
}
}
}
}If installed with uv, uvx --from mcp-clickvisual mcp-clickvisual
also works as the command.
Hermes Agent (config.yaml)
mcp_servers:
clickvisual:
command: python
args: ["-m", "mcp_clickvisual"]
env:
CV_BASE_URL: http://your-clickvisual-host:19001
CV_USERNAME: your-username
CV_PASSWORD: your-password
timeout: 60
enabled: trueUsage notes
search_logs/get_log_chartsneed a numerictable_id. Find it withlist_instances→list_databases→list_tables, orresolve_table_id(instance_id, database, table).st/etaccept unix seconds, ISO 8601 (2026-09-11T00:00:00) orYYYY-MM-DD HH:MM:SS.queryis a SQL WHERE clause:logtext LIKE '%error%',host = 'app13', combined withAND/OR.Set
is_query_count: 1to get total hit counts (slower queries).
Troubleshooting
Login failed — check the three env vars and that the ClickVisual host is reachable from your machine (VPN / intranet may be required).
Query error — make sure
queryis a valid SQL WHERE clause and the column names exist in the table.No data — check the time range and that the table actually has logs.
License
MIT
中文文档
ClickVisual(基于 ClickHouse 的轻量级日志平台)的 MCP (Model Context Protocol) 服务器,让支持 MCP 的 AI 客户端(Claude Desktop、Cursor、Hermes、 魔搭 ModelScope 等)可以直接在对话中搜索日志、浏览实例/数据库/表、查看日志直方图。
工具列表
工具 | 说明 |
| 验证 ClickVisual 登录状态 |
| 列出所有 ClickHouse 实例 |
| 列出指定实例下的数据库 |
| 列出指定数据库下的日志表 |
| 根据实例 ID、数据库名、表名解析数字 |
| 搜索日志(SQL WHERE 语法,如 |
| 获取日志直方图(按时间分布) |
配置
所有配置通过环境变量传入,代码中不存储任何凭据:
环境变量 | 必填 | 说明 |
| ✅ | ClickVisual 访问地址,如 |
| ✅ | 登录用户名 |
| ✅ | 登录密码(明文,发送前自动 MD5 加密) |
服务端使用 Cookie 会话认证,session 过期会自动重新登录。
安装与运行
需要 Python 3.10+:
pip install git+https://github.com/wsws1888/mcp-clickvisual.git
mcp-clickvisual # stdio 模式启动客户端配置
Claude Desktop / Cursor / 通用 MCP JSON
{
"mcpServers": {
"clickvisual": {
"command": "python",
"args": ["-m", "mcp_clickvisual"],
"env": {
"CV_BASE_URL": "http://你的ClickVisual地址:19001",
"CV_USERNAME": "用户名",
"CV_PASSWORD": "密码"
}
}
}
}Hermes Agent (config.yaml)
mcp_servers:
clickvisual:
command: python
args: ["-m", "mcp_clickvisual"]
env:
CV_BASE_URL: http://你的ClickVisual地址:19001
CV_USERNAME: 用户名
CV_PASSWORD: 密码
timeout: 60
enabled: true使用说明
search_logs/get_log_charts需要数字table_id:先用list_instances→list_databases→list_tables逐级查询,或用resolve_table_id按名称解析。时间参数
st/et支持 Unix 时间戳、ISO 8601、YYYY-MM-DD HH:MM:SS三种格式。query是 SQL WHERE 子句:logtext LIKE '%error%'、host = 'app13', 可用AND/OR组合。is_query_count: 1会额外统计命中总数(较慢,默认关闭)。
常见问题
登录失败:检查三个环境变量,确认本机能访问 ClickVisual 地址(内网环境可能需要 VPN)。
查询报错:确认
query是合法的 SQL WHERE 条件、字段名正确。没有数据:检查时间范围是否正确、表里是否有日志。
License
MIT
Available Tools
7 toolscheck_authB
Verify the ClickVisual login state.
Inputs: no named parameters.
get_log_chartsB
Get log histogram data (log count distribution over time).
Inputs: et (required), st (required), table_id (required), query.
list_databasesC
List databases under an instance.
Inputs: instance_id (required).
list_instancesB
List all ClickVisual (ClickHouse) log instances.
Inputs: no named parameters.
list_tablesC
List log tables under a database.
Inputs: database_id (required).
resolve_table_idB
Resolve a numeric tableId from instance ID, database name and table name.
Inputs: table (required), database (required), instance_id (required).
search_logsB
Search ClickVisual logs. Requires a numeric table_id and a time range. The query parameter uses SQL WHERE clause syntax, e.g. logtext LIKE '%error%'.
Inputs: et (required), st (required), table_id (required), page, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool maps to a distinct action/resource: discovery hierarchy (instances/databases/tables), table ID resolution, log querying, histogram aggregation, and auth check. search_logs and get_log_charts both use table_id but clearly differ by returning raw logs versus count distribution.
All names follow a consistent verb_noun snake_case pattern (list_*, search_logs, resolve_table_id, get_log_charts, check_auth). There are no mixed conventions or vague verbs.
Seven tools is well-scoped for a read-only log exploration server. The discovery, search, histogram, and auth pieces all serve the same purpose without bloat.
The set covers the core workflow end-to-end: authenticate, discover instances/databases/tables, resolve the required numeric table_id, then search raw logs or view histograms. The only notable gap is schema/field discovery, which agents may need to construct meaningful search_logs queries.
Maintenance
Related MCP Connectors
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
Query your app's logs, metrics and incidents from your AI assistant.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to query and manage ClickHouse databases, supporting SELECT queries, DDL/DML statements, and metadata listing.53 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables executing SQL queries, listing databases, and listing tables on a ClickHouse cluster through natural language.Apache 2.0
- AlicenseAqualityDmaintenanceA read-only MCP server for ClickHouse that enables AI agents to discover schema, sample data, and run read-only SQL queries to investigate observability data like logs, metrics, and traces.6MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible AI clients to search and retrieve Elasticsearch application logs through a provided search tool.Apache 2.0