ClickHouse MCP Server
Official ClickHouse MCP server: the agent lists databases and tables and runs SQL, read-only by default
- 898 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Runs SQL on your ClickHouse cluster
- Can modify and delete data once the flags are enabled
Install
- Works in
Manual 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).
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Runs SQL on your ClickHouse cluster
- Can modify and delete data once the flags are enabled
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 monthMCP
- Transport
- stdio
- Authentication
- API key
Environment variables
CLICKHOUSE_HOSTrequired- ClickHouse server host
CLICKHOUSE_PORT- Server port
CLICKHOUSE_USERrequired- ClickHouse user
CLICKHOUSE_PASSWORDrequired, 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
Limitations
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.
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.
Discussion
No questions or reviews yet.
Related
MCP serversA Go MCP server for querying ClickHouse: schemas, SQL, tools generated from views, OAuth and Kubernetes deployment
Official ClickHouse skills: schema and query rules, architecture decisions, chDB for Python and ClickHouse Cloud workflows
A desktop SQL workspace with a built-in MCP server: the agent reads the schema and runs queries in the same client you already use
MCP server that gives an agent access to MySQL: schema inspection and queries, read-only by default, writes behind flags
A Python MCP server for MySQL: listing tables, reading data, running SQL and inspecting schema through a controlled interface
A token-lean MCP server for PostgreSQL, MySQL, MariaDB, SQL Server and SQLite with a read-only mode
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.