mcp-clickhousexSAFE
Read-only MCP server for ClickHouse: SELECT queries, EXPLAIN plan/pipeline/syntax analysis, and a snapshot mode that spills large results to a CSV resource. Read-only is enforced by the engine — every client carries readonly=1, so writes, external table functions and query-level SETTINGS are refused
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://github.com/alyiox/mcp-clickhousex/actions/workflows/ci.yml) [](https://pypi.org/project/mcp-clickhousex/) [](https://www.python.org/downloads/) [](LICENSE)
A read-only-by-default Model Context Protocol (MCP) server for ClickHouse that provides schema discovery, read-only queries, execution-plan analysis, opt-in writes, and profile-based access to multiple servers from a single toolset deployment.
Read-only is enforced by the engine, not by SQL text matching: the query tools' clients carry ClickHouse's readonly=1, so writes, external table functions and query-level SETTINGS are refused by the server being queried. Writes live behind a separate tool that is not registered at all until a profile asks for it.
Requirements: Python 3.13+, a running ClickHouse instance, and connection details via environment variables or a config file.
Quick start
Set a DSN and run the server with MCP Inspector:
# Option 1: Run directly with uvx (no clone needed) export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default" npx -y @modelcontextprotocol/inspector@latest uvx mcp-clickhousex
# Option 2: Run from source (clone repo, then) export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default" npx -y @modelcontextprotocol/inspector@latest uv run mcp-clickhousex
Configuration
A profile is one ClickHouse connection: a DSN plus the row and timeout caps that apply to it. A profile named default always exists; every tool takes an optional profile to reach another, and list_profiles reports what is configured
d775ebac0915OBSERVED · 2026-10-12Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add mcp-clickhousex --env MCP_CLICKHOUSE_DSN=${MCP_CLICKHOUSE_DSN} -- uvx mcp-clickhousex==0.12.0Exposed tools (1)
1 read · 0 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
list_profiles | read | [ClickHouse] List configured connection profiles. |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- none-observed
- Network
- declared (1 observation(s))
- Shell
- none-observed
- Dependencies
- pinned
- Secrets in source
- none-found
Findings (4)
.pre-commit-config.yaml
"/etc/passwd",
"../../outside",
"SELECT * FROM url('http://127.0.0.1:8123/ping', LineAsString)",Gates applied: no_behavioural_pass.
d775ebac0915full audit observations/trust-audit/mcp-server/alyiox__mcp-clickhousex.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-12 | d775ebac0915 | SAFE | B | 89 | first audit |
Questions
What is the mcp-clickhousex MCP server?
Read-only MCP server for ClickHouse: SELECT queries, EXPLAIN plan/pipeline/syntax analysis, and a snapshot mode that spills large results to a CSV resource. Read-only is enforced by the engine — every client carries readonly=1, so writes, external table functions and query-level SETTINGS are refused
What tools does mcp-clickhousex expose?
1 in total: 1 read-only, 0 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is mcp-clickhousex safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B.
What credentials does mcp-clickhousex need?
It reads MCP_CLICKHOUSE_DSN from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does mcp-clickhousex run?
It speaks stdio, so it runs as a local process your client starts. It is published on PyPI as mcp-clickhousex.
How current is this page?
The grade is for one exact copy of the source (d775ebac0915), read on 2026-10-12. The repository is watched and re-audited when it changes.