{
  "slug": "io-github-clickhouse-mcp-clickhouse",
  "name": "io.github.ClickHouse/mcp-clickhouse",
  "title": "ClickHouse",
  "description": "Official ClickHouse MCP server for querying and exploring ClickHouse clusters and chDB.",
  "version": "0.7.0",
  "publishedAt": "2026-09-21T14:02:19.431473Z",
  "updatedAt": "2026-09-21T14:02:19.431473Z",
  "repoUrl": "https://github.com/ClickHouse/mcp-clickhouse",
  "websiteUrl": "https://clickhouse.com",
  "namespace": {
    "type": "github",
    "owner": "ClickHouse"
  },
  "kind": "local",
  "packages": [
    {
      "registryType": "pypi",
      "identifier": "mcp-clickhouse",
      "version": "0.7.0",
      "transport": "stdio",
      "runtimeHint": "uvx"
    },
    {
      "registryType": "oci",
      "identifier": "ghcr.io/clickhouse/mcp-clickhouse:0.7.0",
      "version": null,
      "transport": "stdio",
      "runtimeHint": null
    }
  ],
  "remotes": [],
  "envVars": [
    {
      "name": "CLICKHOUSE_HOST",
      "isSecret": false,
      "isRequired": true,
      "description": "Hostname of the ClickHouse server"
    },
    {
      "name": "CLICKHOUSE_USER",
      "isSecret": false,
      "isRequired": true,
      "description": "Username for ClickHouse authentication"
    },
    {
      "name": "CLICKHOUSE_PASSWORD",
      "isSecret": true,
      "isRequired": false,
      "description": "Password for ClickHouse authentication. Required unless a client certificate uses the default or mutual TLS mode"
    },
    {
      "name": "CLICKHOUSE_PORT",
      "isSecret": false,
      "isRequired": false,
      "description": "ClickHouse HTTP(S) port. Defaults to 8443 when CLICKHOUSE_SECURE=true, 8123 otherwise"
    },
    {
      "name": "CLICKHOUSE_SECURE",
      "isSecret": false,
      "isRequired": false,
      "description": "Use HTTPS to connect to ClickHouse"
    },
    {
      "name": "CLICKHOUSE_VERIFY",
      "isSecret": false,
      "isRequired": false,
      "description": "Verify SSL certificates"
    },
    {
      "name": "CLICKHOUSE_CA_CERT",
      "isSecret": false,
      "isRequired": false,
      "description": "Path to a PEM CA bundle for ClickHouse server certificate verification"
    },
    {
      "name": "CLICKHOUSE_CLIENT_CERT",
      "isSecret": false,
      "isRequired": false,
      "description": "Path to a PEM client certificate for the ClickHouse HTTPS connection"
    },
    {
      "name": "CLICKHOUSE_CLIENT_CERT_KEY",
      "isSecret": false,
      "isRequired": false,
      "description": "Path to the PEM private key for CLICKHOUSE_CLIENT_CERT"
    },
    {
      "name": "CLICKHOUSE_TLS_MODE",
      "isSecret": false,
      "isRequired": false,
      "description": "Client certificate mode: mutual, proxy, or strict"
    },
    {
      "name": "CLICKHOUSE_DATABASE",
      "isSecret": false,
      "isRequired": false,
      "description": "Default database to use"
    },
    {
      "name": "CLICKHOUSE_ROLE",
      "isSecret": false,
      "isRequired": false,
      "description": "ClickHouse role to activate for the session"
    },
    {
      "name": "CLICKHOUSE_ALLOW_WRITE_ACCESS",
      "isSecret": false,
      "isRequired": false,
      "description": "Allow write operations (DDL and DML). Queries run read-only by default"
    },
    {
      "name": "CLICKHOUSE_ALLOW_DROP",
      "isSecret": false,
      "isRequired": false,
      "description": "Allow destructive operations (DROP, TRUNCATE, DELETE, UPDATE, REPLACE, CLEAR, and DETACH PERMANENTLY) when write access is also enabled"
    },
    {
      "name": "CLICKHOUSE_MCP_QUERY_TIMEOUT",
      "isSecret": false,
      "isRequired": false,
      "description": "Query tool timeout in seconds"
    },
    {
      "name": "CLICKHOUSE_MCP_MAX_WORKERS",
      "isSecret": false,
      "isRequired": false,
      "description": "Maximum query worker thread pool size"
    }
  ],
  "category": "databases",
  "subcategory": "sql",
  "company": "",
  "categoryAuto": true,
  "checks": [
    {
      "id": "source-linked",
      "label": "Source repository linked",
      "result": "pass",
      "detail": "https://github.com/ClickHouse/mcp-clickhouse"
    },
    {
      "id": "version-pinned",
      "label": "Version pinned",
      "result": "pass",
      "detail": "Every package has an explicit version"
    },
    {
      "id": "secrets-requested",
      "label": "Secrets requested",
      "result": "info",
      "detail": "Asks for 1 secret: CLICKHOUSE_PASSWORD"
    },
    {
      "id": "known-registry",
      "label": "Known package registry",
      "result": "pass",
      "detail": "All packages come from npm, PyPI, OCI, NuGet or MCPB"
    },
    {
      "id": "namespace",
      "label": "Namespace ownership",
      "result": "info",
      "detail": "Name verified via GitHub account ClickHouse"
    },
    {
      "id": "meta-text",
      "label": "Registry text aimed at the AI",
      "result": "pass",
      "detail": "Description and settings contain no hidden characters or instructions to the AI"
    },
    {
      "id": "install-scripts",
      "label": "Install scripts",
      "result": "pass",
      "detail": "mcp-clickhouse 0.7.0 has no setup.py; nothing runs at install"
    },
    {
      "id": "code-flags",
      "label": "Code red flags",
      "result": "pass",
      "detail": "Read 59 files in mcp-clickhouse 0.7.0: no obfuscation, encoded execution, credential reads or data-collection endpoints found"
    },
    {
      "id": "ai-text",
      "label": "Text aimed at the AI",
      "result": "pass",
      "detail": "No hidden characters or instructions to the AI in 59 files, including comments and the README"
    }
  ],
  "scannedAt": "2026-10-29",
  "level": "Scanned",
  "install": [
    {
      "label": "Claude Desktop (pypi)",
      "kind": "claude_desktop_json",
      "text": "{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"mcp-clickhouse==0.7.0\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"<your value>\",\n        \"CLICKHOUSE_USER\": \"<your value>\"\n      }\n    }\n  }\n}"
    },
    {
      "label": "Claude Desktop (oci)",
      "kind": "claude_desktop_json",
      "text": "{\n  \"mcpServers\": {\n    \"mcp-clickhouse\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"-e\",\n        \"CLICKHOUSE_HOST\",\n        \"-e\",\n        \"CLICKHOUSE_USER\",\n        \"ghcr.io/clickhouse/mcp-clickhouse:0.7.0\"\n      ],\n      \"env\": {\n        \"CLICKHOUSE_HOST\": \"<your value>\",\n        \"CLICKHOUSE_USER\": \"<your value>\"\n      }\n    }\n  }\n}"
    }
  ],
  "curated": true,
  "stars": 898,
  "archived": false,
  "pushedAt": "2026-10-27T19:10:59Z",
  "review": {
    "package": "mcp-clickhouse",
    "version": "0.7.0",
    "at": "2026-10-31",
    "files": 17,
    "lines": 4092,
    "verdict": "pass-with-notes",
    "summary": "Lets an AI list and query your ClickHouse databases. It only talks to the ClickHouse server you configure, has no telemetry, and is read-only by default with the database itself enforcing it. Its startup instructions suggest the AI install ClickHouse's 'agent skills' with an npx command, which you may not want an agent to run on its own. The optional chDB engine can read files and websites from your computer, so enable it only if you need it.",
    "hosts": [
      {
        "host": "the configured ClickHouse server (CLICKHOUSE_HOST:CLICKHOUSE_PORT over HTTP/HTTPS)",
        "when": "lazily on tool calls (list_databases, list_tables, run_query) and on the /health route in HTTP mode; client cached afterwards",
        "sends": "SQL queries and bound params, username/password or client certificate, client_name mcp_clickhouse, plus SHOW GRANTS once when writes are enabled and drops are not"
      },
      {
        "host": "OAuth/OIDC provider configured via FASTMCP_SERVER_AUTH (Auth0, Azure, GitHub, Google, WorkOS, etc.)",
        "when": "only in HTTP/SSE mode with that auth option, when clients authenticate",
        "sends": "provider client ID/secret and token verification requests (FastMCP dependency behaviour)"
      },
      {
        "host": "any URL/S3/database named in chDB SQL",
        "when": "only if CHDB_ENABLED=true and the model's SQL uses url()/s3()/postgresql()/mysql() table functions",
        "sends": "requests chosen by the query, made from the user's machine"
      }
    ],
    "env": [
      {
        "name": "CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, CLICKHOUSE_ROLE, CLICKHOUSE_DATABASE, CLICKHOUSE_PROXY_PATH, CLICKHOUSE_SERVER_HOST_NAME",
        "sent_to": "the configured ClickHouse server"
      },
      {
        "name": "CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, CLICKHOUSE_CA_CERT, CLICKHOUSE_CLIENT_CERT, CLICKHOUSE_CLIENT_CERT_KEY, CLICKHOUSE_TLS_MODE",
        "sent_to": "local TLS settings (client cert presented to ClickHouse)"
      },
      {
        "name": "CLICKHOUSE_ALLOW_WRITE_ACCESS, CLICKHOUSE_ALLOW_DROP, CLICKHOUSE_ENABLED, CLICKHOUSE_CONNECT_TIMEOUT, CLICKHOUSE_SEND_RECEIVE_TIMEOUT",
        "sent_to": "not sent; local switches"
      },
      {
        "name": "CLICKHOUSE_MCP_AUTH_TOKEN",
        "sent_to": "not sent; used locally to verify bearer tokens on the HTTP transport"
      },
      {
        "name": "FASTMCP_SERVER_AUTH and FASTMCP_SERVER_AUTH_<PROVIDER>_* (client secrets)",
        "sent_to": "the chosen OAuth provider"
      },
      {
        "name": "CLICKHOUSE_MCP_SERVER_TRANSPORT, CLICKHOUSE_MCP_BIND_HOST/PORT, CLICKHOUSE_MCP_ALLOWED_HOSTS/ORIGINS, CLICKHOUSE_MCP_TRUSTED_PROXIES, CLICKHOUSE_MCP_AUTH_DISABLED, CLICKHOUSE_MCP_QUERY_TIMEOUT, CLICKHOUSE_MCP_MAX_WORKERS, CHDB_ENABLED, CHDB_DATA_PATH, MCP_CLICKHOUSE_TRUSTSTORE_DISABLE, MCP_MIDDLEWARE_MODULE",
        "sent_to": "not sent; local settings"
      }
    ],
    "local": "Loads .env from the package directory upward (auth.py:213-248) and from the working directory (auth.py:266). Reads the TLS certificate files configured by the user. With chDB enabled, keeps chDB data at CHDB_DATA_PATH (default in-memory), and chDB SQL can read and write local files via file() and sqlite(). No other file access.",
    "exec": "No shell or eval. Operator-controlled dynamic imports: MCP_MIDDLEWARE_MODULE imports any named Python module (mcp_middleware_hook.py:10-17), and FASTMCP_SERVER_AUTH imports a class path (auth.py:358). Neither is reachable from tool input.",
    "telemetry": "None. The client identifies itself to the user's ClickHouse server as client_name=mcp_clickhouse.",
    "tools": [
      "list_databases",
      "list_tables",
      "run_query",
      "run_chdb_select_query (only with CHDB_ENABLED=true)"
    ],
    "toolText": "Tool descriptions are clean and unusually candid (they say the drop gate is 'not a security boundary'). Server instructions (skills_advisor.py:3-10) recommend the AI install ClickHouse Agent Skills by running 'npx -y skills add clickhouse/agent-skills --all'. That nudges the agent to download and run third-party code, though the text is visible and points at ClickHouse's own GitHub repo. The opt-in chdb_initial_prompt tells the AI to fall back to downloading data with Python and to show only key results. No hidden or invisible text.",
    "deps": [
      "fastmcp",
      "mcp",
      "clickhouse-connect",
      "python-dotenv",
      "pydantic",
      "cachetools",
      "simplejson",
      "starlette",
      "uvicorn",
      "truststore",
      "chdb (optional extra)"
    ],
    "findings": [
      {
        "severity": "note",
        "at": "mcp_clickhouse/skills_advisor.py:3-10",
        "what": "Server instructions sent to every client suggest the AI run 'npx -y skills add clickhouse/agent-skills --all', which downloads and executes code from GitHub. It is phrased as 'consider' and points at the vendor's own repo, but an agent with shell access might act on it without asking the user."
      },
      {
        "severity": "note",
        "at": "mcp_clickhouse/chdb_backend.py:46-66",
        "what": "Opt-in chDB tool (CHDB_ENABLED=true) runs any SQL in-process with no read-only setting. Its table functions (file, url, s3, postgresql, mysql) can read/write local files and reach any network host from the user's machine."
      },
      {
        "severity": "note",
        "at": "mcp_clickhouse/clients.py:418-470; queries.py:106-136",
        "what": "run_query runs arbitrary SQL by design. Read-only is the default and is properly enforced server-side by sending readonly=1 with every query unless CLICKHOUSE_ALLOW_WRITE_ACCESS=true. With writes on, the DROP/DELETE gate is a regex that the code itself calls best-effort; real protection is the ClickHouse user's grants."
      },
      {
        "severity": "info",
        "at": "mcp_clickhouse/queries.py:316,364; chdb_backend.py:70",
        "what": "Full query text is logged at INFO to stderr (bound parameter values are kept out of these log lines)."
      },
      {
        "severity": "info",
        "at": "mcp_clickhouse/__init__.py:18-23; mcp_env.py:261-266",
        "what": "truststore.inject_into_ssl() switches all Python TLS in the process to the OS certificate store (disable with MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1). CLICKHOUSE_VERIFY=false can turn off certificate verification (opt-in only)."
      },
      {
        "severity": "info",
        "at": "mcp_clickhouse/auth.py:420-477; http_security.py; transport.py",
        "what": "HTTP/SSE mode is well protected: it refuses to start without an auth mode, binds 127.0.0.1 by default, and validates Host and Origin headers. /health is intentionally unauthenticated and returns only OK/error."
      },
      {
        "severity": "info",
        "at": "mcp_clickhouse/mcp_middleware_hook.py:10-17",
        "what": "MCP_MIDDLEWARE_MODULE lets the operator load arbitrary Python into the server. Expected for an extension hook, but anyone who controls the env controls the process."
      },
      {
        "severity": "info",
        "at": "(package)",
        "what": "pyproject.toml was not among the reviewed files; dependencies listed come from imports. Line counts use the manifest convention (newline count + 1 per file, i.e. the empty segment after a final newline is counted); every line of every file was read with the Read tool."
      }
    ]
  },
  "health": {
    "score": 90,
    "parts": {
      "popularity": 0.8101398608268663,
      "activity": 0.9276476915852664,
      "issues": 0.9393939393939394,
      "security": 1
    },
    "fail": 0,
    "warn": 0,
    "raw": {
      "stars": 899,
      "forks": 210,
      "downloads": 88727,
      "hn": {
        "n": 3,
        "pts": 4,
        "t": [
          [
            "44311164",
            "ClickHouse MCP",
            2,
            0,
            "2025-06-18"
          ],
          [
            "44857323",
            "ClickHouse MCP",
            1,
            0,
            "2025-08-10"
          ],
          [
            "42639997",
            "Show HN: Model Context Protocol (MCP) Server for ClickHouse",
            1,
            0,
            "2025-01-09"
          ]
        ]
      },
      "issuesOpen": 4,
      "issuesClosed": 62,
      "prsMerged": 94,
      "commits90": 28,
      "release": "2026-09-21T13:55:16Z",
      "pushed": "2026-10-27T19:10:59Z",
      "growth": null,
      "growthDays": null,
      "archived": false
    },
    "at": "2026-10-31T07:42:38.200Z"
  }
}