How to Set Up a ClickHouse MCP Server for Claude, Cursor & Codex

This post was written by an engineer at QueryPlane. QueryPlane is an app builder for your database: bring your own postgres db and you can create interactive applications to share with other developers, coworkers or even your customers. If you’re interested in trying it out, get started here.

---

MCP (Model Context Protocol) lets AI tools like Claude Desktop, Claude Code, Cursor, and Codex connect directly to your ClickHouse database. Instead of copy-pasting schemas and query results into chat, the AI can inspect your tables, run analytical queries, and explore your data autonomously.

In this post, we’ll cover:

• What is MCP — How the protocol works
• Best ClickHouse MCP servers — Dedicated and multi-database options
• Setup guides — Step-by-step for Claude Desktop and Claude Code
• Security considerations — Keeping your database safe

What is MCP?

The Model Context Protocol is an open standard created by Anthropic that lets AI applications connect to external data sources and tools. Think of it as a USB-C port for AI — a standardized way for any AI client to talk to any data source.

For analytical databases like ClickHouse, MCP servers expose tools for schema exploration and SQL execution — letting AI agents write efficient ClickHouse queries without manual context.

Best ClickHouse MCP Servers

1. Altinity MCP

Altinity/altinity-mcp is a dedicated ClickHouse MCP server from the Altinity team, who are major contributors to the ClickHouse ecosystem.

Features:

• ClickHouse-native connection handling
• Schema inspection and SQL execution
• Multiple transport options (stdio, SSE)
• OAuth/JWE authentication and TLS support

Claude Desktop config (via Docker):

{
  "mcpServers": {
    "clickhouse": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/altinity/altinity-mcp:latest",
        "--clickhouse-host", "localhost",
        "--clickhouse-port", "8123",
        "--clickhouse-database", "default",
        "--clickhouse-username", "default",
        "--clickhouse-password", "password"
      ]
    }
  }
}

Claude Code setup:

claude mcp add --transport stdio clickhouse -- \
  docker run -i --rm \
  ghcr.io/altinity/altinity-mcp:latest \
  --clickhouse-host localhost \
  --clickhouse-port 8123 \
  --clickhouse-database default \
  --clickhouse-username default \
  --clickhouse-password password

2. Google MCP Toolbox for Databases

googleapis/mcp-toolbox (~14,800 stars) supports ClickHouse alongside PostgreSQL, MySQL, BigQuery, Snowflake, MongoDB, and many more.

Features:

• Prebuilt generic tools (list_tables, execute_sql)
• Custom tools framework for domain-specific queries
• Connection pooling and IAM auth
• OpenTelemetry observability built in

3. CentralMind Gateway

centralmind/gateway (~520 stars) supports ClickHouse alongside PostgreSQL, MySQL, Snowflake, and more. It auto-generates API endpoints from your database schema.

Features:

• Auto-generated API endpoints
• Multi-database support
• Built-in caching

4. DBHub (Bytebase)

DBHub (~2,600 stars) is a lightweight multi-database MCP server. While it doesn’t have dedicated ClickHouse support, it can connect via the ClickHouse PostgreSQL interface if enabled.

Which ClickHouse MCP Server Should You Use?

Server	Stars	Dedicated ClickHouse	Multi-database
Altinity MCP	New	Yes	No
Google MCP Toolbox	~14,800	No	Yes
CentralMind Gateway	~520	No	Yes

For most developers, start with Altinity MCP for dedicated ClickHouse support, or Google MCP Toolbox if you work with multiple databases.

Security Considerations

Connecting an AI agent to ClickHouse carries risk. Follow these practices:

• Use a read-only user — create a dedicated user with only SELECT permissions
• Set query limits — use max_execution_time and max_rows_to_read to prevent expensive scans
• Restrict database access — grant access only to specific databases
• Don’t expose credentials in configs — use environment variables
• Enable query logging — monitor what the AI runs via system.query_log

-- Create a read-only user for MCP
CREATE USER mcp_reader IDENTIFIED BY 'secure_password'
  SETTINGS readonly = 1,
           max_execution_time = 30,
           max_rows_to_read = 1000000;

GRANT SELECT ON mydb.* TO mcp_reader;

Using MCP with QueryPlane

If you want the benefits of AI-powered database access without managing MCP servers, QueryPlane provides this out of the box. Connect your ClickHouse database and use AI to generate queries, explore schemas, and build dashboards — all from your browser with built-in access controls and team collaboration.

FAQ

What is a ClickHouse MCP server?

A ClickHouse MCP server is a process that implements the Model Context Protocol to let AI tools (Claude, Cursor, Codex, Windsurf) connect to your ClickHouse database. It exposes tools for listing tables, describing schemas, and running SQL queries.

How do I connect Claude to ClickHouse?

Install a ClickHouse-compatible MCP server like Altinity MCP or Google MCP Toolbox, then add it to your Claude Desktop config or use claude mcp add in Claude Code.

Is it safe to connect AI to ClickHouse?

It can be safe with proper precautions: use a read-only user with readonly = 1, set query execution limits, restrict database access, and monitor queries via system.query_log.

Does MCP work with ClickHouse Cloud?

Yes. MCP servers connect via standard ClickHouse connection strings. ClickHouse Cloud instances that allow external connections work with any ClickHouse MCP server.

Wrapping up

The ClickHouse MCP ecosystem is growing. Altinity’s dedicated server provides native ClickHouse support, while Google’s MCP Toolbox covers ClickHouse as part of its multi-database offering. Start with a read-only user, set query limits, and explore how AI-powered database access fits your analytics workflow.