Skip to content
Back to search

clickscope

MarketplaceWorks with Claude CodeGitHub

Read-only ClickHouse tooling for Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sgr-xd--clickscope/badge.svg)](/listings/sgr-xd--clickscope)

HTML

<a href="/listings/sgr-xd--clickscope"><img src="/api/listings/sgr-xd--clickscope/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

As a Claude Code plugin (recommended)

/plugin marketplace add sgr-xd/clickscope
/plugin install clickscope

While the repository is private, use a local checkout instead — `/plugin marketplace add /path/to/clickscope` — or the standalone route below.

Claude Code then asks for four things:

| Field | Example | |---|---| | **Server** | `clickhouse.internal`, `host:port`, or `https://abc.clickhouse.cloud` | | **Username** | `readonly_user` | | **Password** | masked; goes to your operating system's secure storage — keychain on macOS, the credential store on Windows — never to a settings file | | **Database** | `my_db` |

Port and TLS come from whatever you put in Server, so there is nothing else to set.

This also installs two skills: `clickhouse-query-craft`, which teaches the explore → estimate → run discipline the tools are built around, and `clickhouse-cluster-health`, a one-shot sweep of replication, disks, parts, merges, mutations and errors that reports whether the cluster is healthy right now.

As a standalone MCP server

claude mcp add clickscope --scope user \
  -e CLICKHOUSE_HOST=clickhouse.internal \
  -e CLICKHOUSE_USER=readonly_user \
  -e CLICKHOUSE_PASSWORD_FILE=$HOME/.config/clickscope/password \
  -e CLICKHOUSE_DATABASE=my_db \
  -- uvx clickscope

Works with any MCP client, not only Claude Code — point it at `uvx clickscope` over stdio.

From PyPI

pip install clickscope    # or: uvx clickscope

From source

git clone https://github.com/sgr-xd/clickscope && cd clickscope
uv venv && uv pip install -e ".[dev]"
pytest -m "not integration"      # unit tests, no database needed
pytest                           # adds live tests against a real server

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines
  1. {
  2. "name": "clickscope",
  3. "description": "Read-only ClickHouse tooling for Claude Code",
  4. "owner": {
  5. "name": "sgr-xd",
  6. "url": "https://github.com/sgr-xd"
  7. },
  8. "plugins": [
  9. {
  10. "name": "clickscope",
  11. "description": "Read-only ClickHouse access \u2014 explore schemas and cost a query with EXPLAIN ESTIMATE before running it, so a full scan is caught before it starts.",
  12. "source": "./",
  13. "version": "0.2.1",
  14. "category": "database",
  15. "tags": [
  16. "clickhouse",
  17. "sql",
  18. "database",
  19. "read-only",
  20. "analytics"
  21. ]
  22. }
  23. ]
  24. }
README.md · README · 410 lines
  1. # ClickScope
  2. A read-only [ClickHouse](https://clickhouse.com) MCP server that lets an agent explore your
  3. schema and **cost a query before running it**.
  4. Most database MCP servers give a model one blunt instrument: "run this SQL". On a table with
  5. billions of rows that is how you get a surprise full scan. ClickScope exposes ClickHouse's own
  6. planner instead — `EXPLAIN ESTIMATE` tells you how many parts, rows and marks a query *would*
  7. read, before a single byte is touched.
  8. Works with any ClickHouse: self-hosted, clustered, local, or Cloud.
  9. ## Install
  10. ### As a Claude Code plugin (recommended)
  11. ```
  12. /plugin marketplace add sgr-xd/clickscope
  13. /plugin install clickscope
  14. ```
  15. While the repository is private, use a local checkout instead — `/plugin marketplace add /path/to/clickscope` — or the standalone route below.
  16. Claude Code then asks for four things:
  17. | Field | Example |
  18. |---|---|
  19. | **Server** | `clickhouse.internal`, `host:port`, or `https://abc.clickhouse.cloud` |
  20. | **Username** | `readonly_user` |
  21. | **Password** | masked; goes to your operating system's secure storage — keychain on macOS, the credential store on Windows — never to a settings file |
  22. | **Database** | `my_db` |
  23. Port and TLS come from whatever you put in Server, so there is nothing else to set.
  24. This also installs two skills: `clickhouse-query-craft`, which teaches the
  25. explore → estimate → run discipline the tools are built around, and
  26. `clickhouse-cluster-health`, a one-shot sweep of replication, disks, parts, merges,
  27. mutations and errors that reports whether the cluster is healthy right now.
  28. ### As a standalone MCP server
  29. ```bash
  30. claude mcp add clickscope --scope user \
  31. -e CLICKHOUSE_HOST=clickhouse.internal \
  32. -e CLICKHOUSE_USER=readonly_user \
  33. -e CLICKHOUSE_PASSWORD_FILE=$HOME/.config/clickscope/password \
  34. -e CLICKHOUSE_DATABASE=my_db \
  35. -- uvx clickscope
  36. ```
  37. Works with any MCP client, not only Claude Code — point it at `uvx clickscope`
  38. over stdio.
  39. ### From PyPI
  40. ```bash
  41. pip install clickscope # or: uvx clickscope
  42. ```
  43. ### From source
  44. ```bash
  45. git clone https://github.com/sgr-xd/clickscope && cd clickscope
  46. uv venv && uv pip install -e ".[dev]"
  47. pytest -m "not integration" # unit tests, no database needed
  48. pytest # adds live tests against a real server
  49. ```
  50. ## Configure
  51. Only needed for the standalone and from-source paths; the plugin asks instead.
  52. ```bash
  53. export CLICKHOUSE_HOST=clickhouse.internal # or host:port, or a full URL
  54. export CLICKHOUSE_USER=readonly_user
  55. export CLICKHOUSE_PASSWORD_FILE=~/.config/clickscope/password # preferred
  56. export CLICKHOUSE_DATABASE=my_db
  57. ```
  58. `CLICKHOUSE_HOST` accepts three forms, so port and TLS usually need no separate setting:
  59. | You enter | Host | Port | HTTPS |
  60. |---|---|---|---|
  61. | `clickhouse.internal` | clickhouse.internal | 8123 | no |
  62. | `clickhouse.internal:9440` | clickhouse.internal | 9440 | no |
  63. | `https://abc.clickhouse.cloud:8443` | abc.clickhouse.cloud | 8443 | yes |
  64. | `https://abc.clickhouse.cloud` | abc.clickhouse.cloud | 8443 | yes |
  65. `CLICKHOUSE_PORT` and `CLICKHOUSE_SECURE` still work and take precedence if you set them.
  66. The password is read from `CLICKHOUSE_PASSWORD_FILE` if set, otherwise
  67. `CLICKHOUSE_PASSWORD`. It is never accepted as a command-line argument — arguments leak
  68. through shell history and `ps`.
  69. Optional, environment only (not offered in the plugin dialog, to keep it to four fields):
  70. | Variable | Purpose |
  71. |---|---|
  72. | `CLICKSCOPE_PROFILES` | Path to a multi-cluster profiles file — see below |
  73. | `CLICKSCOPE_AUDIT_LOG` | Path to a JSONL record of every query decision |
  74. ## Using it
  75. Ask in plain language — the tools are named in the responses, not in your question.
  76. **Learn the shape of a table first.**
  77. > *What are the biggest tables in my database?*
  78. `list_tables` returns each table with its `sorting_key` and `partition_key`. Those two
  79. fields decide everything about cost: a filter matching the leading sorting-key column, or
  80. pinning a partition, is the difference between reading a few granules and reading the lot.
  81. **Then cost the query before running it.**
  82. > *How many events belong to tenant acme-corp since August 1st?*
  83. `estimate_query_cost` reports what the query *would* read, without reading it:
  84. ```
  85. verdict=selective parts=4 rows=4,445 of 43,374 (10.2% of table)
  86. ```
  87. Then it runs. Compare that with a filter that misses the key:
  88. ```
  89. verdict=full_scan parts=13 rows=43,373 of 43,374 (100.0% of table)
  90. → Add a filter on the partition key or the leading sorting-key column.
  91. ```
  92. Same table, same row count returned — 10× the work. The verdict arrives *before* the query
  93. runs, which is the entire point: an agent can correct itself instead of discovering the cost
  94. afterwards.
  95. **When something is expensive, ask why.**
  96. > *Why is that query slow?*
  97. `explain_plan` measures how much the indexes actually pruned, stage by stage:
  98. ```
  99. uses_index=False granules 110/113 (97.3%) — effectively a full scan
  100. MinMax parts 17/17 granules 113/113
  101. Partition parts 17/17 granules 113/113
  102. PrimaryKey parts 14/17 granules 110/113
  103. ```
  104. Note `uses_index` comes from the ratio, not from the presence of an `Indexes:` section —
  105. ClickHouse emits that section even when the index removed nothing.
  106. **Writes simply are not available.**
  107. > *Drop the events table*
  108. ```
  109. Query rejected by ClickScope policy:
  110. - query must begin with one of SELECT, WITH, SHOW, DESC, DESCRIBE, EXPLAIN; got DROP
  111. - forbidden keyword: DROP
  112. ```
  113. Rejected before any network call.
  114. **What comes back.** Every response names the cluster that answered and the SQL actually
  115. executed, so a rewritten `LIMIT` is visible rather than silent:
  116. ```json
  117. {"cluster": "prod",
  118. "executed_sql": "SELECT tenant_id FROM events WHERE tenant_id = 'acme-corp' LIMIT 100",
  119. "row_count": 100, "rows_read": 9845, "elapsed_ms": 62,
  120. "policy_notes": ["no LIMIT present; appended LIMIT 100",
  121. "result reached the limit of 100; there may be more rows"]}
  122. ```
  123. ## Tools
  124. **Discovery** — schema exploration, no user SQL accepted:
  125. | Tool | Purpose |
  126. |---|---|
  127. | `list_clusters` | Configured clusters, which is default, and each one's limits |
  128. | `list_databases` | Databases visible to your user |
  129. | `list_tables` | Tables with engine, row count, size, sorting key, partition key |
  130. | `describe_table` | Columns, types, codecs, TTL, per-column compression |
  131. | `show_create_table` | Full `CREATE TABLE` DDL |
  132. | `list_partitions` | Parts, rows and bytes per partition |
  133. | `profile_column` | One column's nulls, distinct count, range and most common values |
  134. **Query**:
  135. | Tool | Purpose |
  136. |---|---|
  137. | `run_select_query` | Execute a `SELECT` under enforced caps |
  138. | `sample_rows` | Preview rows from a table (SQL built server-side) |
  139. **Operations** — what the server is doing, and whether its background work is keeping up:
  140. | Tool | Purpose |
  141. |---|---|
  142. | `list_running_queries` | Queries executing now, longest first |
  143. | `search_query_log` | Slowest completed queries, or failures grouped by exception |
  144. | `table_storage_stats` | Tables ranked by part count and size — where storage pressure is |
  145. | `background_operations` | Merges in flight, and mutations that are stuck retrying |
  146. | `replication_status` | Read-only replicas, lag and queue backlog |
  147. **Cost & validation** — these read no data:
  148. | Tool | Purpose |
  149. |---|---|
  150. | `validate_query` | `EXPLAIN SYNTAX` — is the SQL legal? |
  151. | `estimate_query_cost` | `EXPLAIN ESTIMATE` — parts / rows / marks it would read, as a share of the table |
  152. | `explain_plan` | `EXPLAIN PLAN indexes=1` — how much the indexes actually pruned |
  153. ## Safety
  154. ClickScope is read-only, enforced in three independent layers:
  155. 1. **Statement policy** — single statement only; must open with `SELECT`, `WITH…SELECT`,
  156. `SHOW`, `DESCRIBE` or `EXPLAIN`; DDL/DML keywords, `INTO OUTFILE` and inline `SETTINGS`
  157. overrides are rejected. A missing `LIMIT` is appended; an oversized one is clamped.
  158. 2. **Server-enforced caps** — every query runs with `readonly=1` plus `max_execution_time`,
  159. `max_result_rows`, `max_rows_to_read`, `max_bytes_to_read`, `max_memory_usage` and
  160. `max_threads`. These bind inside ClickHouse, so they hold even if layer 1 is bypassed.
  161. 3. **Database grants** — connect as a user with only `SELECT`. This is the layer that cannot
  162. be argued with, and the one you should not skip:
  163. ```sql
  164. CREATE USER readonly_user IDENTIFIED BY '…' SETTINGS readonly = 1;
  165. GRANT SELECT ON my_db.* TO readonly_user;
  166. ```
  167. The policy layer **rejects, it does not rewrite** — the sole exception being `LIMIT`
  168. injection. Query rewriting that tries to be clever about filters is deployment-specific and
  169. fails in ways that are hard to predict, so ClickScope does not do it.
  170. ### Tuning the caps
  171. | Variable | Default |
  172. |---|---|
  173. | `CLICKSCOPE_MAX_EXECUTION_TIME` | `30` (seconds) |
  174. | `CLICKSCOPE_MAX_RESULT_ROWS` | `10000` |
  175. | `CLICKSCOPE_MAX_ROWS_TO_READ` | `100000000` |
  176. | `CLICKSCOPE_MAX_BYTES_TO_READ` | `10000000000` (10 GB) |
  177. | `CLICKSCOPE_MAX_MEMORY_USAGE` | `4000000000` (4 GB) |
  178. | `CLICKSCOPE_MAX_THREADS` | `4` |
  179. | `CLICKSCOPE_DEFAULT_LIMIT` | `100` |
  180. | `CLICKSCOPE_MAX_LIMIT` | `10000` |
  181. | `CLICKSCOPE_AUDIT_LOG` | unset — set a path to record every decision as JSONL |
  182. ## Several clusters
  183. Point `CLICKSCOPE_PROFILES` at a JSON file, and every tool gains an optional `cluster`
  184. argument.
  185. **The file holds references, never values** — so it is safe to commit, and safe to read
  186. over someone's shoulder:
  187. ```json
  188. {
  189. "default": "prod",
  190. "limits": { "max_limit": 5000 },
  191. "clusters": {
  192. "prod": {
  193. "description": "primary analytics cluster",
  194. "host": "${env:PROD_CH_HOST}",
  195. "port": "${env:PROD_CH_PORT:-8123}",
  196. "user": "${env:PROD_CH_USER:-readonly}",
  197. "password": "${cmd:vault kv get -field=password secret/ch-prod}",
  198. "database": "${env:PROD_CH_DB}",
  199. "limits": { "default_limit": 25, "max_limit": 200 }
  200. },
  201. "staging": {
  202. "host": "clickhouse-staging.example.com",
  203. "password": "${file:~/.config/clickscope/staging.pw}",
  204. "database": "events"
  205. }
  206. }
  207. }
  208. ```
  209. ### Secret references
  210. Any string may contain `${scheme:argument}`, resolved once at startup.
  211. | Scheme | Example | Notes |
  212. |---|---|---|
  213. | `env` | `${env:PROD_CH_PASSWORD}` | `${env:VAR:-default}` supplies a fallback |
  214. | `file` | `${file:~/.config/clickscope/prod.pw}` | Trailing newline stripped. What Kubernetes and Docker secret mounts give you |
  215. | `cmd` | `${cmd:vault kv get -field=password secret/ch-prod}` | stdout of a command |
  216. `cmd` is deliberately the only secret-manager integration. Depending on a cloud SDK would
  217. serve one vendor's users and strand the rest; shelling out to the tool you already run
  218. serves everyone:
  219. ```
  220. ${cmd:gcloud secrets versions access latest --secret=ch-prod}
  221. ${cmd:aws secretsmanager get-secret-value --secret-id ch-prod --query SecretString --output text}
  222. ${cmd:az keyvault secret show --vault-name v --name ch-prod --query value -o tsv}
  223. ${cmd:op read op://vault/ch-prod/password}
  224. ${cmd:pass show clickhouse/prod}
  225. ```
  226. Commands run **without a shell** — the string is split and executed directly, so a value
  227. cannot chain another command with `;` or open a subshell. `clickscope.secrets.register_scheme`
  228. is available if you want a native backend instead.
  229. Rules worth knowing:
  230. - **A literal password is rejected**, with an error pointing at the reference syntax. A
  231. warning would not do: people commit past warnings. This is what makes "safe to commit"
  232. a property of the format rather than a convention.
  233. - **A resolved value is never re-expanded.** A secret whose contents happen to look like
  234. `${env:OTHER}` is data, not a reference — otherwise control of one secret would grant
  235. reads of others.
  236. - **A profiles file writable by anyone but its owner is refused.** A `${cmd:...}` reference
  237. means the file decides what gets executed, so its integrity matters more than its
  238. confidentiality. SSH refuses a private key on the same grounds.
  239. - Host, port, user and database may be literals or references; only `password` is forced
  240. to be a reference.
  241. ### Limits and routing
  242. Limits layer: environment defaults → file-wide `limits` → per-cluster `limits`, so
  243. production can be stricter than staging without restating every field.
  244. Connections are lazy — an unreachable cluster does not stop the server starting and does
  245. not affect the others; you get a normal error payload naming the cluster.
  246. There is deliberately **no `use_cluster` tool.** Selection is an argument on every call,
  247. never stored state, and every response carries the `cluster` that answered it. A mode you
  248. can forget you are in is how you read production believing you are on staging.
  249. ```
  250. list_clusters → what exists, and which is default
  251. run_select_query(sql="…") → the default cluster
  252. run_select_query(sql="…", cluster="staging") → explicitly staging
  253. ```
  254. The single-cluster environment variables above keep working unchanged; they simply produce
  255. one cluster named `default`.
  256. ## Releasing
  257. Changes are recorded in [CHANGELOG.md](CHANGELOG.md).
  258. **Always bump the version when shipping code**, documentation and skills included. Not doing so is silent: users keep running
  259. the old build, and nothing reports an error to reveal it.
  260. Three files carry the version, and they must agree:
  261. ```
  262. .claude-plugin/plugin.json "version"
  263. .claude-plugin/marketplace.json plugins[0].version
  264. pyproject.toml version
  265. ```
  266. Then update an installed copy from `/plugin` in Claude Code:
  267. ```
  268. /plugin → ClickScope → Update now
  269. ```
  270. That preserves configuration, including the keychain-held password. There is no CLI
  271. equivalent — `claude plugin` has no `update` subcommand, and `install` over an existing
  272. plugin is a no-op. For a scripted environment the only option is uninstall and reinstall,
  273. which **erases configuration**, so pass the non-sensitive values back:
  274. ```bash
  275. claude plugin uninstall clickscope@clickscope
  276. claude plugin install clickscope@clickscope --scope user \
  277. --config CLICKHOUSE_HOST=... --config CLICKHOUSE_USER=... --config CLICKHOUSE_DATABASE=...
  278. # then re-enter the password via /plugin configure
  279. ```
  280. ### Why each step is there
  281. **`marketplace update` alone does nothing to the installed copy.** The plugin cache lives at
  282. `plugins/cache/<marketplace>/<plugin>/<version>/`. With the version unchanged the installer
  283. considers the cached copy current, so a successful "update" can leave the old source in place.
  284. The version *is* the cache key.
  285. **Uninstalling erases the configuration**, which is why *Update now* is the path to prefer.
  286. Uninstall empties `pluginConfigs` and takes the keychain entry with it, with no warning. An
  287. update keeps both.
  288. **Directory-sourced installs need their build cache cleared too.** When a marketplace points at
  289. a local directory, `${CLAUDE_PLUGIN_ROOT}` is a path that never changes between versions, so
  290. `uvx` reuses the environment it built the first time — a fix committed hours earlier can still
  291. reproduce, and `/reload-plugins` does not help (it starts a new process against the same stale
  292. environment, and leaves the old one running). To confirm what a running server actually
  293. imports:
  294. ```bash
  295. ps -eo pid,command | grep clickscope # note the archive-v0/<hash>/bin/python path
  296. grep -r "the-fix-you-expect" <that env>/lib/python3.*/site-packages/clickscope/
  297. ```
  298. The fix is `uv cache clean clickscope`, kill the server processes, then reload. Installs from
  299. GitHub are immune, because their plugin root is version-scoped and a bump forces a rebuild.
  300. ### Before publishing
  301. - `pytest` — the full suite, including live tests against a real server
  302. - `clickscope --version` — confirms which build a given install is actually running,
  303. which is the quickest way to catch a stale plugin cache
  304. - Claim the name on PyPI if you intend to use `uvx clickscope` in the docs; an unclaimed name
  305. can be taken by anyone once the repository is public
  306. ## License
  307. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.