ClickHouse MCP Server
Query your ClickHouse Cloud analytics database in natural language via the official remote MCP server.
Updated
What is ClickHouse MCP?
The ClickHouse MCP server is a Model Context Protocol server that lets AI agents and assistants query a ClickHouse Cloud analytics database in natural language — listing databases and tables, inspecting schemas, and running read-only SQL.
ClickHouse offers an official remote, cloud-hosted MCP server built into ClickHouse Cloud, reachable at https://mcp.clickhouse.cloud/mcp. There is nothing to deploy or maintain: you enable the server from the Connect menu of your ClickHouse Cloud service (it is disabled by default) and point any MCP-compatible client at the URL.
Authentication uses OAuth with your ClickHouse Cloud credentials. The identity acts on behalf of the authenticated user, so the agent inherits exactly the permissions that user already has in ClickHouse Cloud — queries run scoped and read-only. (ClickHouse also publishes an open-source, self-hostable MCP server, ClickHouse/mcp-clickhouse, for connecting to any ClickHouse instance.)
Tools the ClickHouse MCP server exposes
| Tool | What it does |
|---|---|
| run_select_query | Run a read-only SELECT query against your ClickHouse Cloud data. |
| list_databases | List the databases available on the connected service. |
| list_tables | List the tables within a given database. |
| get_organizations | List the ClickHouse Cloud organizations the user can access. |
| get_services_list | List the ClickHouse Cloud services in an organization. |
| get_service_details | Retrieve configuration details for a specific service. |
| get_service_backup_configuration | Get the backup configuration for a service. |
| list_service_backups | List existing backups for a service. |
| list_clickpipes | List ClickPipes ingestion pipelines for a service. |
| get_organization_cost | Retrieve cost/usage information for an organization. |
Connect the ClickHouse MCP server
Claude Code
- 1
Enable the remote MCP server
In ClickHouse Cloud, open the Connect menu for your service and enable the remote MCP server (off by default).
- 2
Add the server
Run: claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp
- 3
Authenticate
Trigger the connection so Claude Code opens the OAuth flow, then sign in with your ClickHouse Cloud credentials to authorize.
- 4
Verify
Ask Claude to list databases or run a SELECT query to confirm the tools are available.
Cursor
- 1
Enable the remote MCP server
In ClickHouse Cloud, enable the remote MCP server from the Connect menu of your service.
- 2
Add to Cursor
Add an HTTP MCP server in Cursor's MCP settings with URL https://mcp.clickhouse.cloud/mcp (or install the ClickHouse entry from the Cursor MCP marketplace).
- 3
Authenticate
Complete the OAuth sign-in with your ClickHouse Cloud credentials when Cursor prompts.
- 4
Verify
Confirm the ClickHouse tools appear and run a read-only query from chat.
Sample use cases
An analyst asks a plain-English question about user signups; the agent translates it to a SELECT query via run_select_query
It returns the signup count broken down by day and region without the analyst writing SQL.
A scheduled agent calls get_organization_cost weekly and compares against the budget threshold
It sends a Slack alert if ClickHouse Cloud spend exceeds 80% of the monthly budget with a breakdown by service.
An agent runs get_service_backup_configuration and list_service_backups for each service in the org
It produces a compliance report confirming backup intervals, retention periods, and the last successful backup timestamp.
An agent calls list_clickpipes to enumerate all ingestion pipelines for a service
It reports which data sources are connected, pipeline health, and flags any that haven't processed new records recently.
An agent uses list_databases and list_tables to explore a newly provisioned ClickHouse service
It returns a structured schema map showing every database, its tables, and estimated row counts.
During an incident, an agent runs diagnostic SELECT queries to check for data freshness and query latency
It identifies the specific table or partition where ingestion is lagging and reports the delay in minutes.
An agent calls get_services_list across multiple organizations and compares configurations
It flags services with inconsistent settings (tier, scaling limits, idle timeout) and recommends standardization.
Security & permissions
The remote server uses OAuth against your ClickHouse Cloud credentials. After authorization the MCP identity acts on behalf of the signed-in user, so it can only access what that user can already access in ClickHouse Cloud — your existing roles and grants apply. Queries are read-only SELECT statements; the server cannot write or mutate data. The feature is disabled by default and must be explicitly enabled per service from the Connect menu, limiting exposure.
Using ClickHouse MCP with Gamut
In Gamut, you connect the ClickHouse remote MCP server once (Gamut manages the OAuth connection), and an agent can then use it as a tool inside automated, event- or schedule-triggered workflows — for example, a nightly run that lists tables, queries fresh metrics with a read-only SELECT, and routes the results into a report or alert. Because access is read-only and scoped to the connected user's ClickHouse Cloud permissions, the agent reads analytics without risk of mutating your data.
Frequently asked questions
What is the ClickHouse MCP server?
It is a Model Context Protocol server that lets AI agents query a ClickHouse analytics database in natural language — listing databases and tables, inspecting schemas, and running read-only SQL. ClickHouse offers an official remote, cloud-hosted version at https://mcp.clickhouse.cloud/mcp.
Is the ClickHouse MCP server free?
There is no separate charge to enable the remote MCP server on a ClickHouse Cloud service, but you need a ClickHouse Cloud account/service (which offers a free trial). The open-source self-hosted server is also free to run.
How do I connect the ClickHouse MCP server to Claude Code or Cursor?
First enable the remote MCP server from your ClickHouse Cloud Connect menu. In Claude Code run: claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp. In Cursor, add an HTTP MCP server with the same URL (or install it from the MCP marketplace). Both then prompt an OAuth sign-in with your ClickHouse Cloud credentials.
Is the ClickHouse MCP server hosted or self-hosted?
Both. ClickHouse hosts an official remote MCP server at mcp.clickhouse.cloud/mcp built into ClickHouse Cloud, and it also publishes the open-source ClickHouse/mcp-clickhouse server you can self-host to connect to any ClickHouse instance.
Can the ClickHouse MCP server modify data?
No. The query tool only supports read-only SELECT queries. It cannot INSERT, UPDATE, or DELETE data, which makes it safe for analytics and monitoring use cases.
Does it support multiple ClickHouse Cloud organizations?
Yes. The get_organizations tool lists all organizations accessible to your API key, and you can drill into services, backups, and costs within each one.
Can I monitor ClickPipes ingestion pipelines through it?
Yes. The list_clickpipes tool returns all ingestion pipelines for a service, including their configuration and status — useful for monitoring data freshness and pipeline health.