MCP Clickhouse

mcp-clickhouse

A Model Context Protocol server for ClickHouse. It lets an MCP-capable client (Claude Desktop, Claude Code, etc.) explore schemas, run analytical queries, and manage the database — with behaviour controlled entirely by flags.

The security model is statement-aware: every SQL statement is classified as read, write, or destructive, and gated against the current access mode. Read-only mode additionally runs queries under ClickHouse's own readonly=1 setting.

Features

• Exploration & monitoring — databases, tables, columns, SHOW CREATE, table stats (parts/rows/bytes), running queries, server metrics, cluster topology.
• Read queries — a query tool that only accepts read statements, capped at CLICKHOUSE_MAX_ROWS.
• Management — an execute tool for INSERT/CREATE/ALTER (read-write) and DROP/TRUNCATE/DELETE (admin), each gated by classification.
• Access modes — read-only → read-write → admin, layered so a mode never exposes statements above its level.
• Security flags — database allowlist, protected databases, destructive gating, row cap, dry-run, and JSON audit logging (see below).

Security model

Statement classification lives in src/sql.ts and is fail-safe: ALTER … DELETE/UPDATE counts as destructive, and anything unparseable is treated as destructive.

Tools

Read (read-only+): list_databases, list_tables, describe_table, show_create_table, table_stats, running_queries, server_metrics, cluster_info, query

Write/Admin (read-write+): execute — runs a single statement after classifying it; writes need read-write mode, destructive statements need admin mode + CLICKHOUSE_ALLOW_DELETE.

Quickstart — add to your agent

Published on npm as @dockndevai/mcp-clickhouse. No clone or build needed — your MCP client runs it on demand with npx. Start in `read-only` mode; see .env.example for every variable and docs/CLIENTS.md for the full per-client guide.

Claude Code (CLI)

claude mcp add clickhouse -e CLICKHOUSE_URL="http://localhost:8123" -e CLICKHOUSE_USER="default" -e CLICKHOUSE_MODE="read-only" -- npx -y @dockndevai/mcp-clickhouse

Claude Desktop · Cursor · Windsurf — same block in claude_desktop_config.json, .cursor/mcp.json, or ~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "clickhouse": { "command": "npx", "args": [ "-y", "@dockndevai/mcp-clickhouse" ], "env": { "CLICKHOUSE_URL": "http://localhost:8123", "CLICKHOUSE_USER": "default", "CLICKHOUSE_MODE": "read-only" } } } }

OpenAI Codex CLI — in ~/.codex/config.toml:

[mcp_servers.clickhouse]

command = "npx" args = ["-y", "@dockndevai/mcp-clickhouse"] env = { CLICKHOUSE_URL = "http://localhost:8123", CLICKHOUSE_USER = "default", CLICKHOUSE_MODE = "read-only" }

VS Code (GitHub Copilot, Agent mode) — in .vscode/mcp.json:

{

"servers": { "clickhouse": { "type": "stdio", "command": "npx", "args": [ "-y", "@dockndevai/mcp-clickhouse" ], "env": { "CLICKHOUSE_URL": "http://localhost:8123", "CLICKHOUSE_USER": "default", "CLICKHOUSE_MODE": "read-only" } } } }

Example prompts

• *"What are the biggest tables in the analytics database?"*
• *"Show me the schema for events and run a query for daily counts this week."*
• *"Which queries are currently running and using the most memory?"*

Run from source (development)

Prefer the published package above. To run from a clone:

npm install

npm run build node dist/index.js # with the environment variables set

Develop

npm run dev

npm test # SQL classification + security policy (30 tests) npm run typecheck

Publishing

This server ships a server.json for the official MCP registry and an mcpName for npm ownership validation. See [PUBLISHING.md](PUBLISHING.md) for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.

License

MIT