MCP server · Databases
ClickHouse MCP server
Lets an assistant list ClickHouse databases and tables and run SQL queries, read-only by default, plus optional embedded chDB queries.
- Maintainer
- ClickHouse (official)
- Licence
- Apache-2.0
- Runs
- Locally (uv)
- Sign-in
- A token or API key
- Registry version
- 0.7.0 (updated 2026-09-21)
- Last activity
- 2026-10-06
Overview
What it does
ClickHouse’s MCP server is a Python package started with uv. You point it at a ClickHouse service with environment variables for host, port, user and password, and it exposes three tools: run a query, list databases and list tables with their columns. An optional chDB mode adds an embedded ClickHouse engine that can query files, URLs and other sources without loading them first.
It is read-only by default. Writes need CLICKHOUSE_ALLOW_WRITE_ACCESS=true, and destructive statements such as DROP, TRUNCATE, DELETE and UPDATE need CLICKHOUSE_ALLOW_DROP=true as well. Queries can take named parameters, so values stay separate from the SQL text. Pick it for analytics work where an assistant explores large tables and answers questions in SQL. You can try it against the public ClickHouse SQL Playground using the demo settings in the README.
Tools
What the assistant can do
- run_query for SQL, with named query parameters
- list_databases
- list_tables with paging, filters and column details
- run_chdb_select_query on the embedded chDB engine
- Optional HTTP transport with bearer token or OAuth
Install
Install ClickHouse MCP server in your app
You need:
- uv
- Python 3.10 to 3.14 (3.12 recommended)
- A ClickHouse service and user credentials
Run in your project. --scope local keeps the servers private to you in this project; use user for every project.
claude mcp add --env CLICKHOUSE_HOST="${CLICKHOUSE_HOST}" --env CLICKHOUSE_PORT=8443 --env CLICKHOUSE_USER="${CLICKHOUSE_USER}" --env CLICKHOUSE_PASSWORD="${CLICKHOUSE_PASSWORD}" --env CLICKHOUSE_SECURE=true --env CLICKHOUSE_VERIFY=true --scope local clickhouse -- uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse
claude mcp add --env CLICKHOUSE_HOST="$env:CLICKHOUSE_HOST" --env CLICKHOUSE_PORT=8443 --env CLICKHOUSE_USER="$env:CLICKHOUSE_USER" --env CLICKHOUSE_PASSWORD="$env:CLICKHOUSE_PASSWORD" --env CLICKHOUSE_SECURE=true --env CLICKHOUSE_VERIFY=true --scope local clickhouse -- uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse
- Set CLICKHOUSE_HOST, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD first, e.g. export CLICKHOUSE_HOST=… in your shell. The command saves the value, not the variable.
Project root. Commit it to share the servers with your team; each person sets the variables in their own shell.
{
"mcpServers": {
"clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.12",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "${CLICKHOUSE_HOST}",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "${CLICKHOUSE_USER}",
"CLICKHOUSE_PASSWORD": "${CLICKHOUSE_PASSWORD}",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true"
}
}
}
}
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json (Settings → Developer → Edit Config). Restart Claude after saving.
{
"mcpServers": {
"clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.12",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "<CLICKHOUSE_HOST>",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "<CLICKHOUSE_USER>",
"CLICKHOUSE_PASSWORD": "<CLICKHOUSE_PASSWORD>",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true"
}
}
}
}
- Claude Desktop doesn’t read variables in this file: replace <CLICKHOUSE_HOST>, <CLICKHOUSE_USER>, <CLICKHOUSE_PASSWORD> with the real values.
- This file contains your keys once filled in. It lives in your user folder; never commit or share it.
In your project, or ~/.cursor/mcp.json for every project.
{
"mcpServers": {
"clickhouse": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.12",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "${env:CLICKHOUSE_HOST}",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "${env:CLICKHOUSE_USER}",
"CLICKHOUSE_PASSWORD": "${env:CLICKHOUSE_PASSWORD}",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true"
}
}
}
}
In your workspace. VS Code asks for each secret the first time a server starts and stores it securely.
{
"inputs": [
{
"type": "promptString",
"id": "clickhouse-host",
"description": "CLICKHOUSE_HOST",
"password": true
},
{
"type": "promptString",
"id": "clickhouse-user",
"description": "CLICKHOUSE_USER",
"password": true
},
{
"type": "promptString",
"id": "clickhouse-password",
"description": "CLICKHOUSE_PASSWORD",
"password": true
}
],
"servers": {
"clickhouse": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.12",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "${input:clickhouse-host}",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "${input:clickhouse-user}",
"CLICKHOUSE_PASSWORD": "${input:clickhouse-password}",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true"
}
}
}
}
macOS/Linux: ~/.config/devin/mcp_config.json · Windows: %APPDATA%\devin\mcp_config.json. Read by the default Devin Local agent and by the legacy Cascade agent.
{
"mcpServers": {
"clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.12",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "${env:CLICKHOUSE_HOST}",
"CLICKHOUSE_PORT": "8443",
"CLICKHOUSE_USER": "${env:CLICKHOUSE_USER}",
"CLICKHOUSE_PASSWORD": "${env:CLICKHOUSE_PASSWORD}",
"CLICKHOUSE_SECURE": "true",
"CLICKHOUSE_VERIFY": "true"
}
}
}
}
- Devin’s docs confirm ${env:…} references for the legacy Cascade agent; for the default Devin Local agent they only document them in OAuth settings. If a server can’t authenticate, check Devin’s MCP docs.
Want it alongside other servers? Open ClickHouse MCP Server in the MCP config generator and add the rest; it writes one file per app. The snippets follow the setup in the server’s README, checked on 2026-10-14.
Before you install
- Queries run read-only (readonly=1) unless CLICKHOUSE_ALLOW_WRITE_ACCESS is set to true.
- The extra CLICKHOUSE_ALLOW_DROP gate is a best-effort check, not a security boundary; give the server a ClickHouse user with only the grants it needs.
- chDB mode can read local files and URLs the process can reach.
- A local MCP server runs with your user account’s permissions. Install it only from the source linked above. See how to choose a safe server.
Why it’s listed
Why we list it
Official, safe by default and well documented, with steady releases.
Related
More MCP servers
- Neon MCP ServerLets an assistant manage Neon Postgres projects and branches, run SQL, and test schema migrations on a temporary branch first.
- Prisma MCP serverLets an assistant create and query Prisma Postgres databases, restore backups, and manage Prisma Compute apps and Object Storage.
- MongoDB MCP ServerLets an assistant query and manage MongoDB databases and, with Atlas credentials, manage Atlas projects, clusters and users.
- Redis MCP ServerLets an assistant read and write Redis data types, streams and JSON documents, and run vector search on a Redis database.
- DuckDB / MotherDuck Local MCP ServerLets an assistant run DuckDB SQL on local files, in-memory databases, S3-hosted databases or MotherDuck, read-only unless you allow writes.
- mcp-server-qdrantGives an assistant a semantic memory: it stores notes in a Qdrant collection and finds them later by meaning rather than exact words.
All MCP serversMCP config generatorGuide: MCP servers in Claude CodeGuide: what is MCP?