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 agent answers ad-hoc analytics questions by translating them into read-only SELECT queries over ClickHouse Cloud.
Self-serve insights without writing SQL by hand.
A scheduled workflow pulls fresh metrics each morning and compiles a summary report.
Automated, up-to-date analytics digests.
An agent inspects database and table schemas before drafting or validating a query.
More accurate, schema-aware querying.
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.