ClickHouse MCP Server

The ClickHouse MCP Server is ClickHouse's official open-source server for the Model Context Protocol. It connects a compatible AI client to a specific ClickHouse instance. According to ClickHouse documentation, an assistant can explore databases and tables and execute SQL queries. This is database access, not merely a search plug-in: the connection, ClickHouse user, that user's roles and grants, and server configuration determine which information can be exposed and which instructions can be carried out.

Data analysis and development with a clear boundary

Its three core tools are list_databases, list_tables, and run_query. They let a client enumerate databases, inspect tables and metadata, and send SQL to the connected instance. That can support analysis questions, schema orientation, debugging, and developing or reviewing queries. Data Analysis and Coding are therefore the appropriate categories. The server does not replace data-model ownership or domain review, though: table metadata and query results can be incomplete, stale, misunderstood, or unsuitable for the decision at hand.

Official documentation describes the standard deployment as a local stdio process, while the README also documents Streamable HTTP and SSE. This entry therefore records both as the deployment type; it does not imply a ClickHouse-operated public MCP endpoint for this open-source project. The process needs at least CLICKHOUSE_HOST, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD for its database connection. Port, TLS, certificate verification, role, and default database are further optional settings. For ClickHouse Cloud, the documentation identifies HTTPS on port 8443 as the default. Those are database-connection settings, not automatic protection for an HTTP MCP endpoint.

Read by default; explicitly enable writes

run_query executes SQL. By default, the README says the server sets CLICKHOUSE_ALLOW_WRITE_ACCESS=false and enforces readonly=1, intended to prevent accidental mutations during exploration. A read path can still expose sensitive table names, column definitions, metadata, and query results. A read-only user is therefore not automatically a data-minimised user. Limit databases, tables, columns, and rows to the actual task, and create a dedicated ClickHouse user for an agent instead of using default or an administrator.

If CLICKHOUSE_ALLOW_WRITE_ACCESS=true is set, non-destructive DDL/DML such as CREATE, INSERT, or ALTER ADD COLUMN can become possible where ClickHouse grants permit it. Destructive SQL requires the additional CLICKHOUSE_ALLOW_DROP=true flag; the README includes DROP, TRUNCATE, DELETE, UPDATE, and several ALTER variants among the protected operations. That second switch is an accident guard inside the MCP server, not an authorization boundary. The actual boundary is minimally scoped ClickHouse grants and roles, with server-side controls such as max_table_size_to_drop where appropriate. Begin with read-only access and a non-production database or restricted view; enable writing only for a clearly reviewed operation.

Credentials, limits, and network operation

Keep passwords, tokens, and configuration files out of prompts, repositories, screenshots, and tool output. Pass them through protected local client configuration or an appropriate secret mechanism. Use TLS for the database connection, keep certificate verification enabled, and use the ClickHouse instance's HTTP port rather than the native clickhouse-client TCP port. When HTTP or SSE transport is used, the server requires authentication by default through a bearer token or OAuth/OIDC; the README reserves disabling authentication for local development. A network listener also needs a restrictive bind address, Host/Origin validation, and a suitable TLS/proxy boundary.

Constrain execution as well. According to the README, CLICKHOUSE_MCP_QUERY_TIMEOUT defaults to 30 seconds and attempts KILL QUERY on timeout, while CLICKHOUSE_MCP_MAX_WORKERS defaults to 10 concurrent query workers. Add appropriate query, database, and resource limits in ClickHouse itself. A timeout is not a cost, data-volume, or permission boundary: a large permitted query may still return substantial and sensitive material.

Prompt injection and the model data path

An agent may read instructions embedded in table values, comments, error messages, or query results. That material is data, not a trusted command. Treat text such as “ignore rules,” “reveal credentials,” or “change this table” as possible prompt injection; review SQL before approval and use client-side tool confirmations when available. No database value can override authorization or approval rules.

The MCP server returns metadata and query results to the connected AI client. That client may place them into model context, logs, telemetry, or an external model-provider path; the result depends on the selected client, model, and their settings. A locally running stdio server therefore does not guarantee that data stays local. Review the complete path before accessing personal, confidential, or regulated data. The repository is Apache-2.0 licensed. On 2026-09-08, the GitHub API reported exactly 869 stars; this is a point-in-time repository-popularity signal, not evidence of quality or security.

FAQ

Can the server change data? Queries are intended to be read-only by default. With CLICKHOUSE_ALLOW_WRITE_ACCESS=true, permitted non-destructive SQL changes can become possible; destructive operations additionally require CLICKHOUSE_ALLOW_DROP=true. ClickHouse grants are the effective safety boundary.

Is a read-only user enough? It prevents writes but can still read sensitive data and metadata. Also scope databases, tables, columns, rows, and roles to the minimum necessary access.

Do query results stay local with local stdio? Not necessarily. The MCP server runs locally, but the AI client can place results into model context, logs, or an external model-provider path.

Python 3.10 through 3.14, uv or Python/pip, an MCP-capable client, and a ClickHouse host, user, and password with minimally required privileges.

For local stdio, configure uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse in the MCP client and set CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, and, where required, port/TLS/role as protected environment variables. For HTTP or SSE, also configure documented MCP authentication; enable write access only after deliberate review.

uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

The database connection uses a ClickHouse host, user, and password, with optional CLICKHOUSE_ROLE. HTTP/SSE MCP transport requires bearer-token or OAuth/OIDC authentication by default. Stdio has no separate MCP network-authentication requirement.

Permissions follow the selected ClickHouse user, roles, and grants. Use a dedicated least-privilege user; read-only is the default, while write and especially destructive SQL need deliberate additional flags and matching ClickHouse grants.

Schema metadata and SQL results go to the MCP client and can enter model context, logging, telemetry, or an external model-provider path there. Local stdio operation alone does not limit that downstream data path.

SQL can read, expose, create, or modify data. Risks include overly broad grants, credentials in configuration, large queries, network exposure, and prompt injection from database content. Query/resource limits and human approvals complement but do not replace least privilege.