VERIFIED

Clickhouse

Safety: 65/100

0.0(0)

This MCP server enables interaction with ClickHouse and chDB databases, providing tools for querying, listing databases/tables, and health checks, with configurable authentication.

MCP ServersFreemium

Boost this tool

Subscribe to listing upgrades or segmented pushes.

Overview

This MCP server enables interaction with ClickHouse and chDB databases, providing tools for querying, listing databases/tables, and health checks, with configurable authentication.

This MCP server offers a reasonable level of safety when properly configured with authentication and secure connection settings. The greatest risks arise from disabling authentication or using the chDB tool with untrusted data sources. Exercise caution when configuring environment variables and granting access to the ClickHouse instance.

Performance is primarily determined by the ClickHouse cluster's resources and the complexity of the SQL queries. chDB performance depends on the size and location of the data being queried.

Cost considerations depend on the ClickHouse cluster's infrastructure and the volume of data being processed. chDB can reduce ETL costs by enabling direct querying of data sources.

HybridPython690 starsApache-2.0Released 1/28/2026CI/CD

Connections & Capabilities

Connects To

GitHubDocker

Capabilities

ReadWrite

Client Compatibility

Claude Desktop

full

Cursor

untested

Windsurf

untested

VS Code (Copilot)

untested

Quickstart

Claude Desktop Config

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "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_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Environment Variables

CLICKHOUSE_HOSTCLICKHOUSE_PORTCLICKHOUSE_USERCLICKHOUSE_PASSWORDCLICKHOUSE_SECURECLICKHOUSE_VERIFY

Tools (4)

safe

run_select_query

Executes a read-only SQL query on the ClickHouse cluster.

Queries are run with `readonly = 1`, preventing data modification.

safe

list_databases

Lists all databases on the ClickHouse cluster.

Read-only operation with no side effects.

safe

list_tables

Lists tables in a database with optional filtering and pagination.

Read-only operation with no side effects.

moderate

run_chdb_select_query

Executes a SQL query using the chDB embedded ClickHouse engine.

Queries data directly from various sources, potentially including untrusted URLs or files.

Security

Auth Method

Token

Data Locality

hybrid

Known Risks

!Disabling authentication exposes the server to unauthorized access.
!Using default or administrative ClickHouse users grants excessive privileges.
!Unvalidated data sources in chDB queries can lead to data poisoning or unexpected behavior.
!Environment variables containing credentials could be exposed if not properly secured.
!Insufficiently restricted network access to the server could allow unauthorized connections.

Safety Score

moderate risk

Positive

+SQL queries are run with `readonly = 1` by default for ClickHouse, preventing unintended data modification.
+Authentication is required for HTTP/SSE transports, preventing unauthorized access.
+The server supports SSL certificate verification for secure connections to ClickHouse.
+Clear instructions are provided for setting up authentication and disabling it only for local development.

Risks

-If authentication is disabled, the server is vulnerable to unauthorized access.
-The `run_chdb_select_query` tool allows querying data from various sources, potentially including untrusted URLs or files.
-Improper configuration of ClickHouse credentials in the environment variables could lead to exposure of sensitive information.
-While ClickHouse queries are read-only by default, misconfiguration or future tool additions could introduce write capabilities.

Use Cases

Data Exploration

-Listing available databases and tables to understand the data schema.
-Running ad-hoc queries to explore data and identify trends.
-Extracting data subsets for analysis in other tools.

Database Administration

-Monitoring database health using the health check endpoint.
-Auditing database schema and table structures.
-Validating data integrity through read-only queries.

Data Integration

-Querying data from various sources using chDB without ETL processes.
-Combining data from ClickHouse and other sources for unified analysis.
-Building data pipelines for real-time data processing.

Who Is This For?

Best For

Data analysts who need to explore and query ClickHouse data.
Database administrators who need to monitor and manage ClickHouse clusters.
Developers who need to integrate ClickHouse data into their applications.
Organizations that want to leverage chDB for querying data from various sources without ETL.

Not Ideal For

Scenarios requiring write access to the ClickHouse database without careful access control.
Environments where disabling authentication is unavoidable.
Use cases involving untrusted data sources with chDB without proper validation.
Situations where strict data governance and security policies are required without proper configuration.

Autonomy & Execution

Default ModeRead-only

Autonomy is limited by the read-only nature of most tools. The chDB tool introduces some risk due to its ability to query external data sources.

StatelessYes

Retry LogicNot documented

ConcurrencySingle-threaded

Production Tip

Ensure proper monitoring and alerting are in place to detect connection issues or unexpected query results.

FAQ

What is the default authentication method?

Authentication is required by default for HTTP/SSE transports, using a token-based authentication scheme. The stdio transport does not require authentication.

How do I disable authentication?

You can disable authentication by setting the `CLICKHOUSE_MCP_AUTH_DISABLED` environment variable to `true`. This is only recommended for local development.

What is the purpose of the health check endpoint?

The health check endpoint returns a 200 OK status with the ClickHouse version if the server is healthy and can connect to ClickHouse. It returns a 503 Service Unavailable status if the server cannot connect to ClickHouse.

What are the required environment variables for ClickHouse?

The required environment variables are `CLICKHOUSE_HOST`, `CLICKHOUSE_USER`, and `CLICKHOUSE_PASSWORD`.

How do I configure the server to use chDB?

You can enable chDB by setting the `CHDB_ENABLED` environment variable to `true` and providing a path to the data directory using `CHDB_DATA_PATH`.

Can I use both ClickHouse and chDB simultaneously?

Yes, you can enable both ClickHouse and chDB by configuring the appropriate environment variables for each.

What is the difference between `CLICKHOUSE_SECURE` and `CLICKHOUSE_VERIFY`?

`CLICKHOUSE_SECURE` enables or disables HTTPS connection, while `CLICKHOUSE_VERIFY` enables or disables SSL certificate verification. It is recommended to keep both enabled for secure connections.

Metrics

Discovered2/14/2026

Reviews0

Saved By0 users

Related Tools

Clickhouse - AI Tool Review & Alternatives | Flaex AI