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).

Related MCP server: clickhouse-mcp-server

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.

Use with your MCP client

Works with Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code (Copilot), and any other MCP client — see docs/CLIENTS.md for per-client setup.

Install

npm install
npm run build

Run with Claude Desktop / Claude Code

{
  "mcpServers": {
    "clickhouse": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-clickhouse/dist/index.js"],
      "env": {
        "CLICKHOUSE_URL": "http://clickhouse:8123",
        "CLICKHOUSE_USER": "readonly",
        "CLICKHOUSE_PASSWORD": "…",
        "CLICKHOUSE_MODE": "read-only",
        "CLICKHOUSE_DATABASE_ALLOWLIST": "analytics"
      }
    }
  }
}

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?"

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