ClickHouse MCP Server: Setup for Claude, Cursor and Other Apps
Lets Claude, Cursor and other AI apps list your ClickHouse databases and tables and run SQL queries against them.
This is ClickHouse's own MCP server. It runs on your computer and connects to your ClickHouse server or ClickHouse Cloud service with a username and password you provide. The assistant can browse databases and tables and run SQL, and it is read-only by default.
Writes and destructive statements stay off until you set CLICKHOUSE_ALLOW_WRITE_ACCESS and CLICKHOUSE_ALLOW_DROP in the server's environment. The project calls that second gate a best-effort accident guard, not a security boundary, so give the server a database user that can only do what you want.
Good for
- Analysts who want to ask questions of ClickHouse data in plain English
- Data engineers exploring unfamiliar databases and table layouts
- Developers who want query help next to their code
Works in
12 should work
Tap an app to see how to set it up and any known problems.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Supports local MCP servers.
Client does not support this transport.
Client does not support this transport.
Install ClickHouse MCP
Claude Code
- 1
Copy this prompt.
Add the ClickHouse MCP server to Claude Code. Run this command: claude mcp add clickhouse -e CLICKHOUSE_HOST=<CLICKHOUSE_HOST> -e CLICKHOUSE_USER=<CLICKHOUSE_USER> -- uvx mcp-clickhouse Ask me for CLICKHOUSE_HOST, CLICKHOUSE_USER and only put the values in that config, nowhere else. Then check that it loaded and tell me if I need to sign in or restart.
- 2
Paste it into Claude Code. It shows the change and asks before running it.
Requires uv (Python).
Built from the package data we hold. Not yet tested by us.
Tools
Runs a SQL query on your ClickHouse database
Runs the SQL you give it against ClickHouse and returns the rows. It is read-only unless you turn on write access, and it accepts named parameters. It also runs DESCRIBE and EXPLAIN ESTIMATE to check a query before you run it.
Try: “Count the events per day for the last 7 days in the analytics database.”
Network ·
run_queryLists the databases on your ClickHouse server
Returns the names of every database on the server so the assistant knows where to look first.
Try: “Which databases do I have on this ClickHouse server?”
Network ·
list_databasesLists tables in a database, with columns
Lists the tables in one database, 50 per page by default, with optional LIKE filters. Each table comes with its columns and its CREATE TABLE statement, so the assistant can write correct queries.
Try: “List the tables in the analytics database whose names start with events_.”
Network ·
list_tablesRuns a SQL query in chDB, the built-in ClickHouse engine
Runs SQL in chDB, an embedded ClickHouse engine that can query files and URLs directly. It only exists if you install the optional chdb extra and set CHDB_ENABLED to true.
Try: “Use chDB to count the rows in ~/data/sales.parquet.”
Files ·
run_chdb_select_query
Read from the source code
Permissions
low risk · 3 things to watch
Low risk
The assistant can read any data the configured ClickHouse user can read, and by default it cannot change anything. Use a dedicated read-only ClickHouse user, and only enable write mode on a user with narrow grants.
What it can do
- Read your data
- Create and change things
- Delete things
- Read-only modeHow to turn it on
Watch out for
Write and drop modes are opt-in switches
With CLICKHOUSE_ALLOW_WRITE_ACCESS and CLICKHOUSE_ALLOW_DROP both true, run_query can run DROP, TRUNCATE, DELETE and UPDATE. Leave them off, or use a ClickHouse user that only has the grants you want. github.com
Query results go to your AI app
Rows returned by run_query are sent to the model provider behind your assistant. Keep sensitive tables out of reach of the ClickHouse user you configure. github.com
The drop guard is not a security boundary
The project says the destructive-statement check is a best-effort accident guard, and that the real boundary is the ClickHouse user grants. github.com
Security advisories
No published security advisories as of Nov 1, 2026.
Technical details
| Turning on read-only | Queries run read-only by default (readonly=1 enforced by ClickHouse). Writes need CLICKHOUSE_ALLOW_WRITE_ACCESS=true and destructive statements also need CLICKHOUSE_ALLOW_DROP=true. |
|---|---|
| Talks to | Your ClickHouse server (HTTP or HTTPS, port 8123 or 8443 by default) |
| Sign-in and keys | Host, user and password are read from environment variables in your client config. |
| Scopes |
|
Questions
Is the ClickHouse MCP server official?
Yes. It is published by ClickHouse in its own GitHub organization and listed in the MCP registry under the ClickHouse name.
Can it change or delete my data?
Not by default. Queries run read-only until you set CLICKHOUSE_ALLOW_WRITE_ACCESS to true, and DROP, TRUNCATE, DELETE and UPDATE also need CLICKHOUSE_ALLOW_DROP. The project says that last check is only an accident guard, so limit the database user as well.
What do I need to connect it?
A ClickHouse host and user are required, and a password unless you use a client certificate. CLICKHOUSE_SECURE defaults to true (HTTPS, port 8443), which is what ClickHouse Cloud needs; set it to false only for a plain HTTP server on port 8123. Add the settings in the install box above.
Does it run on my computer or in the cloud?
It runs on your computer and connects out to your ClickHouse server. The default mode talks to your app over standard input and output. An HTTP mode exists and listens on 127.0.0.1 by default and requires authentication.
What is chDB and do I need it?
No. chDB is an embedded ClickHouse engine for querying local files and URLs. It adds one extra tool, run_chdb_select_query, and is off until you install the chdb extra and set CHDB_ENABLED to true.
How do I add it to Claude or Cursor?
Use the install box above for your app. It needs uv installed, and you fill in your ClickHouse host and user.
Information
updated Nov 2, 2026
- Publisher
- Official
- Package
mcp-clickhouse- Registry
- PyPI
- Transport
- stdio
- Version
- 0.7.0
- License
- Apache-2.0
- Last commit
- Oct 27, 2026
- Open issues
- 4
- Listed in
- Official MCP registry, Docker MCP Catalog
Sources
Docs, issue trackers and discussions this page is built from. Issues, quotes and findings above link to their own source.
Show all 2Hide
- github.com · github.com
- github.com · github.com