ANALYTICS DATABASES / ClickHouse
ClickHouse MCP Server
Queries ClickHouse and inspects table metadata, with read-only SQL by default and separate authentication for network transports.
“An MCP server for ClickHouse.”
01 / THE REASONING
Why this made the selection.
- Documents query permissions and HTTP caller authentication separately.
- Supports metadata inspection and parameterized SQL, useful for targeted analytics investigations.
02 / THE REVIEW RECORD
What we actually inspected.
Source review has boundaries.
A clear record is more useful than a “safe” badge.
Material inspected
- README.md (tools, security, configuration, write access and destructive-operation sections)
- pyproject.toml
- mcp_clickhouse/mcp_server.py
- LICENSE
Our findings
- CLICKHOUSE_ALLOW_WRITE_ACCESS defaults false; writes require an explicit change.
- HTTP/SSE requires a configured bearer token or FastMCP auth provider unless authentication is deliberately disabled; the health probe is unauthenticated.
- mcp_server.py registers list_databases, list_tables and run_query while CLICKHOUSE_ENABLED is true (the default). It adds run_chdb_select_query and the chdb_initial_prompt prompt only when chDB is enabled and importable.
- DROP, TRUNCATE, DELETE, UPDATE and the other statements the README lists need CLICKHOUSE_ALLOW_DROP=true on top of CLICKHOUSE_ALLOW_WRITE_ACCESS=true. The README says this gate is not server-enforced; read-only mode is enforced with readonly=1.
- The README’s Claude Desktop block launches uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse and passes host, port, user, password and role as placeholder environment values.
- Since the previous pin the README adds Agents Schema guidance: the server instructions suggest reading AGENTS.ROOT through run_query. The README says no metadata is fetched automatically.
Not established by this review
- Server startup, authentication and tool execution were not tested.
The review applies to the material and revision named here. A newer upstream release can change its behavior.
03 / PUT IT TO WORK
Connect a server deliberately.
DOCUMENTED COMMAND
uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse Copying does not execute this command. It may retrieve a newer version than the reviewed source.
- Follow the documented client launch configuration and configure the ClickHouse connection.
- Keep write access disabled for exploration; configure caller authentication before using a network transport.
- The command above is the command and args of the README’s Claude Desktop block, not a separate installer. It was not run.
Before you start
- Python/uv or the documented container runtime and a ClickHouse user.
Documented configuration example
Use the client and authentication context described in the setup guidance. Configuration formats vary between hosts.
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.12",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "<clickhouse-host>",
"CLICKHOUSE_PORT": "<clickhouse-port>",
"CLICKHOUSE_USER": "<clickhouse-user>",
"CLICKHOUSE_PASSWORD": "<clickhouse-password>",
"CLICKHOUSE_ROLE": "<clickhouse-role>",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true",
"CLICKHOUSE_CONNECT_TIMEOUT": "30"
}
}
}
} 04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
- Official documentation ↗Checked
https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/README.md
Supports: summary, whySelected, bestFor, limitations, install, access, compatibility, transports, configExample, review
- Applicable source licence ↗Checked
https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/LICENSE
Supports: license
https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/pyproject.toml
Supports: language, review
https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/mcp_clickhouse/mcp_server.py
Supports: language, review, Tool list