← Explore all mcp servers

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.

Upstream setup instructions ↗

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.

  1. Follow the documented client launch configuration and configure the ClickHouse connection.
  2. Keep write access disabled for exploration; configure caller authentication before using a network transport.
  3. 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.

  1. Official documentation ↗Checked

    https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/README.md

    Supports: summary, whySelected, bestFor, limitations, install, access, compatibility, transports, configExample, review

  2. https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/LICENSE

    Supports: license

  3. https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/pyproject.toml

    Supports: language, review

  4. https://github.com/ClickHouse/mcp-clickhouse/blob/d21fe75a6f09afbfbe4cd5063372020bbe62c491/mcp_clickhouse/mcp_server.py

    Supports: language, review, Tool list

Evidence & Ask