ClickHouse MCP Server

ClickHouse's own MCP server. It runs on your machine and lets your agent discover databases and tables, inspect schemas and run SQL against your ClickHouse service, whether that's ClickHouse Cloud or a server you run yourself. Queries are read-only unless you turn writes on. What you can do with it - List the databases on your cluster, and page through the tables in one, with their columns and CREATE TABLE statements - Run SQL queries, with named parameters for the values - Check a query before running it: DESCRIBE shows the columns it returns, and EXPLAIN ESTIMATE shows how many rows it would read - Query files, URLs and other sources in place with chDB, ClickHouse's embedded engine, when you turn it on How it connects It's a Python package, mcp-clickhouse, that runs with uv (for example uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse). It talks to ClickHouse's HTTP interface with the details you give it: CLICKHOUSE_HOST and CLICKHOUSE_USER, plus CLICKHOUSE_PASSWORD, which you need unless you sign in with a client certificate. For ClickHouse Cloud it uses HTTPS on port 8443. For a self-managed server on plain HTTP, also set CLICKHOUSE_SECURE=false, and CLICKHOUSE_PORT=8123 if needed. To try it without your own data, point it at the public ClickHouse SQL Playground: host sql-clickhouse.clickhouse.com, user demo and an empty password. Read-only unless you say so - Queries run read-only by default. - CLICKHOUSE_ALLOW_WRITE_ACCESS=true allows inserts, CREATE and ALTER ADD COLUMN. - Destructive statements such as DROP, TRUNCATE, DELETE and UPDATE also need CLICKHOUSE_ALLOW_DROP=true. - ClickHouse recommends a dedicated database user with only the permissions your agent needs, never a default or admin user: that user's grants are the real limit. Good to know - You need uv installed. If your agent can't find it, use its full path. - ClickHouse documents setup for Claude Code, Claude Desktop, Codex, ChatGPT's desktop app, Cursor and Windsurf. For ChatGPT on the web, ClickHouse Cloud has a separate remote MCP server. - Queries time out after 30 seconds by default; CLICKHOUSE_MCP_QUERY_TIMEOUT changes that.

• “List the databases available in ClickHouse, then show me the tables in one of them.”

  1. list_databases
  2. list_tables
  Copy

• “Show me the columns of every table in the analytics database.”

  1. list_tables
  Copy

• “Total spend per user in events over the last 30 days.”

  1. run_query
  Copy

• “Before running it, estimate how many rows this query would read.”

  1. run_query
  Copy

• “Query this Parquet file with chDB.”

  1. run_chdb_select_query
  Copy