MCP ClickHouse

Official

Connect ClickHouse to your AI assistants

How to install ↓ Compare GitHub source repository ↗

Category: Database #1 of 58
Stars: ★ 883 Very popular
Transport: stdio (local process)
Runtime: Python 3.10+ · Docker
Credentials: Optional API key
License: Apache-2.0
Last commit: 4 days ago
Tools: 4

79FMRS · B

Official MCP server with comprehensive features, but careful attention to permission configuration and security is needed.

Strongest · Security and permissions 18/20 Weakest · Reliability 12/20

Reliability

12/20

Security and permissions

18/20

Maintenance

17/20

Documentation

17/20

Setup experience

15/20

Why each score

Reliability 12/20: Evidence: Official ClickHouse repository with a tests directory (tests/test_tool.py, tests/test_chdb_tool.py), Ruff linting, Docker Compose test services, and detailed configuration docs; the server is built on FastMCP and the declared tools (run_query, list_databases, list_tables, run_chdb_select_query) match the README. Because this is a static review with no execution, reliability is capped at 12 per the calibration rules. Deductions: the actual init/tool handshake and runtime behavior could not be verified, and operation depends on an external database; MCP Inspector and test commands are documented but the complete execution path is not proven by static evidence.
Security and permissions 18/20: Evidence: Read-only mode is enforced by default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false); destructive ops (DROP/TRUNCATE) require an additional opt-in CLICKHOUSE_ALLOW_DROP=true; HTTP/SSE transports require authentication by default (static bearer token or OAuth/OIDC) and fail startup otherwise; the /health endpoint is intentionally unauthenticated with a minimal response body to avoid leaking backend details; the password is flagged isSecret; docs explicitly warn against default/admin database users and recommend least privilege. No red-line issues found (no malware, no real secrets in examples, no destructive defaults without confirmation). Deductions: static review cannot confirm runtime credential protection (e.g., log redaction) or fully validate the read-only enforcement implementation without executing tests.
Maintenance 17/20: Evidence: Apache-2.0 license; versioned releases (0.4.0) with PyPI and OCI packages; active-looking CI (Ruff, pytest, Docker Compose); clear development/test workflow. Stars and issue counts were treated as discovery signals only and did not contribute points. Deductions: release cadence, issue-response timeliness, and dependency-update velocity cannot be confirmed from static material; no dedicated security-response channel (e.g., SECURITY.md) is evident in the supplied evidence.
Documentation 17/20: Evidence: Layered documentation: quick start, full environment-variable reference, three auth modes, security defaults, common configuration pitfalls, example configs (local Docker, ClickHouse Cloud, SQL Playground, chDB), troubleshooting hints (e.g., native-protocol port misuse), and health-check behavior. Tool parameters, pagination, timeouts, and permission toggles are documented. Deductions: no dedicated troubleshooting section with common error codes and diagnostic steps; middleware setup assumes Python import-path knowledge; static evidence cannot prove docs fully match runtime behavior.
Setup experience 15/20: Evidence: Multiple installation paths are provided: PyPI via uv run or pip/system Python, OCI image, and stdio/http/sse transports; concrete Claude Desktop JSON configs, a SQL Playground example, optional chDB install, and documented env-var defaults make the setup steps clear. Deductions: static review cannot execute the installation; the flow depends on external tools like uv and the startup behavior is not verified from source; per calibration rules, setup cannot exceed 15 without execution evidence.

Static review · not runListed 2026-08-07

Read the FMRS scoring method →

Fit and risk

What it can accessUses the networkConnects to a database

Best for

Teams already using ClickHouse who want AI assistants to access data directly.
Scenarios requiring fast, read-only data queries and schema exploration.

Not for

Scenarios requiring write access to the database without explicit opt-in.
Production environments with stringent security requirements that avoid default permission settings.

Required permissions

Requires read-only access to ClickHouse database (default).
Optional: write access via CLICKHOUSE_ALLOW_WRITE_ACCESS.
Optional: destructive operations via CLICKHOUSE_ALLOW_DROP.

Risks and side effects

If write access is enabled, AI might make unintended modifications.
If DROP access is enabled, data deletion could occur accidentally.
Credentials may be exposed via environment variables.

Setup

Before you start

Runtime：Python 3.10+ · Docker

CLICKHOUSE_HOST required Hostname of the ClickHouse server (database endpoint, not the MCP bind address); from your ClickHouse service or ClickHouse Cloud.

CLICKHOUSE_USER required ClickHouse authentication username, assigned by your database admin; avoid default or admin accounts.

CLICKHOUSE_PASSWORD requiredsecret ClickHouse authentication password, assigned by your database admin; keep secret.

CLICKHOUSE_MCP_AUTH_TOKEN optionalsecret Static bearer token for HTTP/SSE transports; generate yourself with uuidgen or openssl rand -hex 32.

Other optional settings (21)

CLICKHOUSE_PORT optional ClickHouse HTTP interface port; defaults to 8443 (HTTPS) / 8123 (HTTP), usually not needed.

CLICKHOUSE_SECURE optional Use HTTPS for the ClickHouse database connection; defaults to true.

CLICKHOUSE_VERIFY optional Verify SSL certificates for the ClickHouse connection; defaults to true.

CLICKHOUSE_CONNECT_TIMEOUT optional ClickHouse client connection timeout in seconds; defaults to 30.

CLICKHOUSE_SEND_RECEIVE_TIMEOUT optional ClickHouse client send/receive timeout in seconds; defaults to 300, increase for long queries.

CLICKHOUSE_DATABASE optional Optional default database name from your ClickHouse instance.

CLICKHOUSE_ROLE optional Optional ClickHouse role to activate for the session; assigned by your database admin.

CLICKHOUSE_ALLOW_WRITE_ACCESS optional Set to true to allow DDL/DML write operations; queries are read-only by default.

CLICKHOUSE_ALLOW_DROP optional Set to true (with write access enabled) to allow destructive DROP/TRUNCATE operations.

CLICKHOUSE_MCP_QUERY_TIMEOUT optional Query tool execution timeout in seconds; defaults to 30.

CLICKHOUSE_MCP_SERVER_TRANSPORT optional MCP transport: stdio (default), http, or sse.

CLICKHOUSE_MCP_BIND_HOST optional Bind address for the MCP HTTP/SSE server; defaults to 127.0.0.1.

CLICKHOUSE_MCP_BIND_PORT optional Bind port for the MCP HTTP/SSE server; defaults to 8000.

CLICKHOUSE_MCP_AUTH_DISABLED optional Set to true to disable HTTP/SSE authentication; local development only.

FASTMCP_SERVER_AUTH optional Full class path of a FastMCP auth provider (e.g. Azure Entra) for OAuth/OIDC authentication.

CLICKHOUSE_SERVER_HOST_NAME optional Optional SNI override and certificate validation hostname for proxies/load balancers.

CLICKHOUSE_PROXY_PATH optional Optional URL path prefix for the ClickHouse HTTP endpoint behind a reverse proxy.

CLICKHOUSE_ENABLED optional Enable/disable ClickHouse database tools; defaults to true; set false for chDB-only usage.

CHDB_ENABLED optional Enable chDB embedded engine tools; defaults to false; requires the mcp-clickhouse[chdb] extra.

CHDB_DATA_PATH optional Path to the chDB data directory; defaults to :memory: (in-memory).

MCP_MIDDLEWARE_MODULE optional Python module name (without .py) containing custom middleware with a setup_middleware(mcp) function.

Install dependencies: uv or Python.
Add mcpServers entry to Claude Desktop config (see install_config).
Set environment variables CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD.
Restart Claude Desktop.

claude_desktop_config.json

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

Shown for Claude Desktop. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

.vscode/mcp.json

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

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal

claude mcp add mcp-clickhouse -e 'CLICKHOUSE_HOST=<clickhouse-host>' -e 'CLICKHOUSE_PORT=<clickhouse-port>' -e 'CLICKHOUSE_USER=<clickhouse-user>' -e 'CLICKHOUSE_PASSWORD=<clickhouse-password>' -e 'CLICKHOUSE_ROLE=<clickhouse-role>' -e CLICKHOUSE_SECURE=true -e CLICKHOUSE_VERIFY=true -e CLICKHOUSE_CONNECT_TIMEOUT=30 -e CLICKHOUSE_SEND_RECEIVE_TIMEOUT=30 -- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

Confirm that run_query, list_databases, list_tables (and optionally run_chdb_select_query) appear in the client's tool list, then ask the assistant to run a query like SELECT 1; a returned result proves the connection works.

Troubleshooting

Check if CLICKHOUSE_SECURE and CLICKHOUSE_PORT match.
Ensure CLICKHOUSE_PORT is the HTTP port (8123/8443), not native TCP (9000/9440).
Check server logs for detailed errors.
Verify ClickHouse service is reachable and credentials are correct.

Things to try

Once connected, you can ask your AI assistant things like:

List all databases on my ClickHouse cluster
Show all tables in the default database
Run this query on ClickHouse: SELECT version()
Use chDB to query this CSV file directly without importing it

Tools 4

run_query writes

Execute SQL queries on your ClickHouse cluster. Read-only by default.

list_databases read-only

List all databases on your ClickHouse cluster.

list_tables read-only

List tables in a database with pagination and filtering.

run_chdb_select_query read-only

Execute SQL queries using chDB's embedded ClickHouse engine.

Use cases

Allow AI assistants to directly query ClickHouse for data insights.

Explore database schema, such as listing databases and tables.

Perform local data analysis with chDB without setting up a separate database.

Supported clients

Claude Desktop

Listed from the project's documentation, not tested by this site.

Overview

Official ClickHouse MCP server for querying and exploring ClickHouse clusters and chDB. Provides SQL query, database and table listing tools via MCP.

Similar servers

ChEMBL MCP Server 75 · B

Unofficial MCP server providing advanced access to the ChEMBL chemical database

★ 89 · Tools 27 Compare with this →

MCP Toolbox for Databases 74 · B

Google's official database MCP toolbox — define AI-accessible database tools via config

★ 16.6k Compare with this →

DBHub 74 · B

Bytebase's official, minimalist two-tool database MCP server

★ 3.6k · Tools 2 Compare with this →

Supabase MCP Server 74 · B

Connect Supabase to your AI assistants

★ 2.9k Compare with this →

Compare with other MCP servers

Source revision d21fe75a6f09 Data synced 2026-10-11 Read the FMRS scoring method