ClickHouse MCP Server

ClickHouse is a high-performance, column-oriented SQL database management system for online analytical processing (OLAP) and real-time analytics.

Tools

Last Updated

Apr 7, 2026

What is the ClickHouse MCP Server?

The ClickHouse MCP server gives AI agents structured, permission-aware access to ClickHouse through the Model Context Protocol. With 20 pre-built actions, agents can read, create, and update ClickHouse data on behalf of authorized users.

Willow ships the ClickHouse MCP server as part of an enterprise control plane. Every call runs behind SSO (Okta, Azure AD), enforces RBAC and least-privilege at runtime, writes to a full audit trail, and integrates with Splunk and Loki for SIEM visibility. Connect from Claude Desktop, Claude Code, Cursor, ChatGPT, VS Code, n8n, or any custom agent. Install once, distribute org-wide, and see exactly how ClickHouse is being used by every AI agent in your stack.

Tools

List Databases

List all databases on the ClickHouse server. Returns the database name, engine type, and comment for each database. Use this as a starting point to explore what data is available on the server.

List Tables

List tables in a specific database. Returns table name, engine, total rows, total bytes, partition count, and comment. Optionally filter by a name pattern using SQL LIKE syntax (e.g. '%logs%'). Use this to explore what tables exist and their approximate sizes.

Describe Table

Get detailed column information for a specific table including column names, data types, default expressions, comments, and whether columns are part of the primary key. Use this to understand a table's schema before querying it.

Get Table Statistics

Get storage and performance statistics for a specific table including total rows, compressed and uncompressed size, number of parts, and partition details. Uses system.parts to provide accurate statistics for MergeTree-family tables. Use this to assess table size, storage efficiency, and health.

Get Create Table Statement

Get the CREATE TABLE statement that defines a table's full schema, including engine, partition key, order by, settings, and all column definitions. Use this to understand the complete table definition, replicate a table, or review its configuration.

Search Columns

Search for columns across all tables by column name pattern or data type. Use this to find which tables contain a specific field (e.g. 'user_id'), discover columns of a certain type, or explore the schema across multiple tables at once.

Execute SQL Query

Execute an arbitrary SQL query against the ClickHouse server. Supports all ClickHouse SQL including SELECT, INSERT, CREATE, ALTER, DROP, and system commands. Results are returned in JSON format. For SELECT queries, use this as the primary tool for data analysis and exploration. For DDL/DML, prefer the specialized tools when available.

Explain Query

Get the execution plan for a SQL query without running it. Shows how ClickHouse will process the query including the pipeline, indexes used, and estimated rows. Supports different EXPLAIN types: 'PLAN' (default, logical plan), 'PIPELINE' (physical execution pipeline), 'SYNTAX' (optimized query after rewrites), 'ESTIMATE' (estimated rows and marks to read). Use this to optimize slow queries.

Get Sample Data

Preview rows from a table by selecting all columns with an optional row limit. Use this to quickly inspect what data looks like in a table, understand column values, and verify data quality before writing more complex queries.

Insert Data

Insert rows into a ClickHouse table. Data is provided as a JSON array of objects where each object represents a row and keys are column names. Uses JSONEachRow format for flexible insertion. Use this to add new data, populate tables, or load small batches of records.

1 2

1–10 of 20 tools

Customize Tools

Edit descriptions, modify arguments, select tools, or add new ones

Set Up Your ClickHouse MCP Server in Minutes

Add the following configuration to your MCP client. Authentication is handled via OAuth. Compatible with Claude Desktop, Claude Code, Cursor, ChatGPT, VS Code, n8n, and any MCP-compatible agent.

Claude Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "willow-clickhouse": {
      "type": "http",
      "url": "https://<org>.mcp-s.com/mcp/mcp/clickhouse"
    }
  }
}

Cursor

.cursor/mcp.json

{
  "mcpServers": {
    "willow-clickhouse": {
      "type": "http",
      "url": "https://<org>.mcp-s.com/mcp/mcp/clickhouse"
    }
  }
}

Claude Code

CLI

claude mcp add willow-clickhouse --transport http https://<org>.mcp-s.com/mcp/mcp/clickhouse

n8n

HTTP Request Node

{
  "url": "https://<org>.mcp-s.com/mcp/mcp/clickhouse",
  "method": "POST"
}

Or click "Install with Willow" above to set up automatically with SSO and RBAC preconfigured.

Enterprise Governance for ClickHouse

Willow adds the layer ClickHouse and every other SaaS doesn't ship out of the box: every call runs behind SSO (Okta, Azure AD), enforces RBAC and least-privilege at runtime, writes to full audit logs, and detects shadow AI usage across your stack. One MCP gateway. Any agent. Every tool.

ClickHouse MCP Server FAQ

What is the ClickHouse MCP server?

The ClickHouse MCP server is a Model Context Protocol implementation that lets AI agents like Claude, Cursor, and ChatGPT read and write ClickHouse data through a standardized interface. Willow hosts and governs this server so enterprises can roll it out without a security review backlog.

How is Willow's ClickHouse MCP server different from the official one?

The official ClickHouse MCP server is scoped to a single user's account and does not include enterprise governance. Willow's version adds SSO, RBAC, audit logging, shadow AI detection, and centralized control over which actions agents can take across the entire org.

Which AI clients work with the ClickHouse MCP server?

Claude Desktop, Claude Code, Cursor, ChatGPT, VS Code with MCP support, n8n, and any custom agent built with OpenAI Agents SDK, LangChain, Vercel AI SDK, or Anthropic SDK.

Is the ClickHouse MCP server secure? How does Willow handle authentication?

Every call runs behind your existing SSO (Okta, Azure AD). Per-user OAuth scopes the agent to exactly what that user can do in ClickHouse, nothing more. No credentials reach the LLM. Every action writes to an audit trail.

Can I limit which ClickHouse actions agents can take?

Yes. Willow lets you scope agents to specific actions, specific projects, or specific environments. Toggle actions on or off in the dashboard, or enforce policy via infrastructure-as-code through GitHub.

How do I detect shadow ClickHouse MCP servers in my org?

Willow's browser extension and discovery service surface unmanaged MCP servers, skills, and AI agents across the org. If a developer installed an unapproved ClickHouse MCP locally, you'll see it.

What does the ClickHouse MCP server cost?

Pricing depends on org size and deployment model (SaaS, dedicated cloud, self-host). See withwillow.ai/pricing or contact sales for a quote.

How do I install the ClickHouse MCP server with Willow?

Install via the Willow Connect Panel in one click, or paste the JSON snippet above into your Claude Desktop, Cursor, or Claude Code config. SSO and RBAC inherit from your existing Willow setup.