# mcp-clickvisual

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for
[ClickVisual](https://github.com/clarkliang/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) |

## 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+.

```bash
# from source
pip install git+https://github.com/wsws1888/mcp-clickvisual.git

# or from a local checkout
pip install .
```

## Run

```bash
# both of these start the stdio MCP server
mcp-clickvisual
python -m mcp_clickvisual
```

## Client configuration

### Claude Desktop / Cursor / generic MCP JSON

```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](https://docs.astral.sh/uv/), `uvx --from mcp-clickvisual mcp-clickvisual`
also works as the command.

### Hermes Agent (`config.yaml`)

```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](https://github.com/clarkliang/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+：

```bash
pip install git+https://github.com/wsws1888/mcp-clickvisual.git
mcp-clickvisual   # stdio 模式启动
```

## 客户端配置

### Claude Desktop / Cursor / 通用 MCP JSON

```json
{
  "mcpServers": {
    "clickvisual": {
      "command": "python",
      "args": ["-m", "mcp_clickvisual"],
      "env": {
        "CV_BASE_URL": "http://你的ClickVisual地址:19001",
        "CV_USERNAME": "用户名",
        "CV_PASSWORD": "密码"
      }
    }
  }
}
```

### Hermes Agent (`config.yaml`)

```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