ClickHouse MCP Server
Official ClickHouse MCP server: the agent lists databases and tables and runs SQL, read-only by default
Install
{"mcpServers": {"mcp-clickhouse": {"command": "uv", "args": ["run", "--with", "mcp-clickhouse", "--python", "3.12", "mcp-clickhouse"], "env": {"CLICKHOUSE_HOST": "<clickhouse-host>", "CLICKHOUSE_PORT": "<clickhouse-port>", "CLICKHOUSE_USER": "<clickhouse-user>", "CLICKHOUSE_PASSWORD": "<clickhouse-password>", "CLICKHOUSE_SECURE": "true"}}}}Put the full path to uv in command (which uv).
This is third-party code. Review the repository files before installing.
What it does
The server connects the agent to a ClickHouse cluster with three tools: run a query, list databases and list tables with columns and pagination. Queries run read-only; writes and destructive statements are enabled by separate flags. The same tool accepts DESCRIBE and EXPLAIN ESTIMATE, so the agent can check the result schema and read volume before running a heavy query. It also supports the embedded chDB engine for querying files and URLs without a separate server.
Who it is for. For analysts and developers who keep data in ClickHouse and want to query it through an agent.
Good fit when
- You need to understand the structure of an unfamiliar ClickHouse database
- You want the agent to write and test analytical SQL on real data
- You need to estimate query cost before running it
Not a fit when
- You would have to give production access without a dedicated restricted user
- Your data is not in ClickHouse
Example request
List the tables in the analytics database and count events per day for the last monthLimitations
Requires a ClickHouse host and credentials. The DROP and DELETE guard runs inside the MCP server and does not replace database grants: for write mode the README recommends a dedicated user with minimal privileges. HTTP and SSE transports require authentication to be configured.
How to disable. Remove the mcp-clickhouse block from your MCP client config and restart the client.
MCP
- Transport
- stdio
- Authentication
- API key
| Environment variables | |
|---|---|
| CLICKHOUSE_HOST required | ClickHouse server host |
| CLICKHOUSE_PORT | Server port |
| CLICKHOUSE_USER required | ClickHouse user |
| CLICKHOUSE_PASSWORD required, secret | User password |
| CLICKHOUSE_ALLOW_WRITE_ACCESS | Allow INSERT, CREATE and ALTER |
| CLICKHOUSE_ALLOW_DROP | Allow DROP, TRUNCATE, DELETE and UPDATE together with the write flag |
| CHDB_ENABLED | Enable the embedded chDB engine |
Security check
- Runs SQL on your ClickHouse cluster
- Can modify and delete data once the flags are enabled
README in short
The README lists the ClickHouse and chDB tools, explains query checks with DESCRIBE and EXPLAIN ESTIMATE and documents the /health endpoint for HTTP mode. A large section covers security: a static token or OAuth via FastMCP for network transports, plus two-tier write and drop permissions. Setup is shown via uv in Claude Desktop and via pip with system Python. Apache-2.0 licensed.
FAQ
Can the agent drop a table by accident?
Not by default: queries run read-only. Writes need CLICKHOUSE_ALLOW_WRITE_ACCESS, and DROP, TRUNCATE or DELETE also need CLICKHOUSE_ALLOW_DROP.
Can I try it without my own server?
Yes, the README includes a config for the public ClickHouse SQL Playground with the demo user.
Related
166 skills for scientific work: bioinformatics, cheminformatics, clinical data, geospatial analysis and 100+ databases
Google's open-source MCP server for databases: ready tools for Postgres, MySQL, BigQuery, Spanner and more, plus custom tools in tools.yaml
A token-lean MCP server for PostgreSQL, MySQL, MariaDB, SQL Server and SQLite with a read-only mode
Official MongoDB MCP server: queries and aggregations, index management, Atlas clusters and local deployments