ClickHouse MCP Server: Tools, Setup and Security

The ClickHouse MCP server lets an AI app list databases and tables and run SQL on a ClickHouse cluster. It can also query files and URLs through chDB, ClickHouse's embedded engine. ClickHouse publishes it as an open-source Python package, and its MCP docs link setup guides for Claude Code, Claude Desktop, Codex, ChatGPT, Cursor and Windsurf (now Devin Desktop).

Checked against: ClickHouse MCP Server README on 28 October 2026. eSEOspace did not install or test this server.

At a glance

What it can do

The README lists these tools:

• run_query: runs SQL on your cluster. It accepts an optional params object for ClickHouse {name:Type} placeholders. It also runs DESCRIBE (<query>) to check result columns and EXPLAIN ESTIMATE to see how many rows a query would read.
• list_databases: lists all databases.
• list_tables: lists tables in a database, with paging, LIKE filters and optional column details.
• run_chdb_select_query: runs SQL in chDB against files, URLs or databases without loading the data first. It needs the optional chdb extra.

A /health endpoint is available when the server runs over HTTP or SSE.

How to connect it

For Claude Desktop, the README gives this config, run with uv:

{
  "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"
      }
    }
  }
}

ClickHouse supports Python 3.10 to 3.14 and recommends 3.12. The README also has a config for the public ClickHouse SQL Playground, which is handy for a first look.

If you run the server over HTTP for a team, clients connect to its URL with a bearer token header. The README shows a client config with "Authorization": "Bearer your-generated-token".

Security notes

ClickHouse's defaults are cautious. In its words, the server "enforces read-only queries so that accidental mutations cannot happen during exploration."

There are two separate switches:

The server stays read-only if the ClickHouse instance itself disallows writes. That means a read-only database user is a second layer of protection. Use the CLICKHOUSE_ROLE setting to run as a narrow role. See least privilege for MCP.

HTTP authentication. Over HTTP or SSE, auth is required by default. You choose a static bearer token, OAuth/OIDC through FastMCP providers such as Entra ID, Google or GitHub, or disabled auth. ClickHouse says to disable auth for "local development only." Never expose an unauthenticated server on a network. Read exposed local MCP servers.

Health check. The /health endpoint is intentionally unauthenticated. To confirm auth works, ClickHouse says to call the MCP endpoint itself without a token and check for a 401.

Parameters are not private. Parameter values stay out of the server's own SQL logs. But ClickHouse says they still appear in tool arguments and may show in ClickHouse system logs. More in the MCP security hub.

Alternatives

• Google BigQuery MCP Server: a Google-hosted server with a read-only SQL tool.
• Snowflake MCP Server: a managed server with a read-only SQL option.
• Elastic MCP Server: search and analytics through Agent Builder.

More profiles are in the MCP server directory.

Next step

Keep both write flags off and connect as a read-only ClickHouse role. Add write access only for a named task. If you plan to host the server for a team, our MCP development team can set up OAuth in front of it.

Frequently asked questions