Skip to main content
Glama
mcp-clickvisual

mcp-clickvisual

by shuaidawang

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

check_auth

Verify the ClickVisual login state

list_instances

List all ClickHouse instances

list_databases

List databases under an instance

list_tables

List log tables under a database

resolve_table_id

Resolve a numeric tableId from instance ID + database name + table name

search_logs

Search logs with a SQL WHERE clause, e.g. logtext LIKE '%error%'

get_log_charts

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

CV_BASE_URL

✅

ClickVisual web address, e.g. http://your-clickvisual:19001

CV_USERNAME

✅

Login username

CV_PASSWORD

✅

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_clickvisual

Client 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: true

Usage notes

  • search_logs / get_log_charts need a numeric table_id. Find it with list_instances → list_databases → list_tables, or resolve_table_id(instance_id, database, table).

  • st / et accept unix seconds, ISO 8601 (2026-09-11T00:00:00) or YYYY-MM-DD HH:MM:SS.

  • query is a SQL WHERE clause: logtext LIKE '%error%', host = 'app13', combined with AND / OR.

  • Set is_query_count: 1 to 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 query is 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 等)可以直接在对话中搜索日志、浏览实例/数据库/表、查看日志直方图。

工具列表

工具

说明

check_auth

验证 ClickVisual 登录状态

list_instances

列出所有 ClickHouse 实例

list_databases

列出指定实例下的数据库

list_tables

列出指定数据库下的日志表

resolve_table_id

根据实例 ID、数据库名、表名解析数字 tableId

search_logs

搜索日志(SQL WHERE 语法,如 logtext LIKE '%error%')

get_log_charts

获取日志直方图(按时间分布)

配置

所有配置通过环境变量传入,代码中不存储任何凭据:

环境变量

必填

说明

CV_BASE_URL

✅

ClickVisual 访问地址,如 http://your-clickvisual:19001

CV_USERNAME

✅

登录用户名

CV_PASSWORD

✅

登录密码(明文,发送前自动 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 tools
check_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

    A3.5/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to query and manage ClickHouse databases, supporting SELECT queries, DDL/DML statements, and metadata listing.
      5
      3 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables executing SQL queries, listing databases, and listing tables on a ClickHouse cluster through natural language.
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-compatible AI clients to search and retrieve Elasticsearch application logs through a provided search tool.
      Apache 2.0