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 for publishing to npm and listing on the MCP registry, Smithery, Glama, Cursor, and PulseMCP.

License

MIT