ClickHouse MCP Server – Analytics Data Access
ClickHouse provides both a fully managed remote MCP server for ClickHouse Cloud and an open-source local MCP server for ClickHouse databases. AI agents can use the integration to inspect databases and tables, run scoped SELECT queries, and, in ClickHouse Cloud, retrieve related organization, service, backup, ClickPipes, and billing context.
Overview
ClickHouse MCP connects MCP-compatible AI clients to ClickHouse analytical data. ClickHouse documents two official options: a managed remote MCP server in ClickHouse Cloud and the open-source mcp-clickhouse server on GitHub. The remote server is intended for ClickHouse Cloud users who want a hosted endpoint with OAuth authentication, while the local server can connect to any ClickHouse instance, including self-hosted deployments.
What the MCP server enables
The open-source local server exposes three core ClickHouse tools: list_databases, list_tables, and run_select_query. These let an AI agent discover available databases, inspect table schemas and counts, and execute SELECT queries for analysis. The package can also enable chDB support with the optional mcp-clickhouse[chdb] extra, adding run_chdb_select_query for embedded ClickHouse-style querying over local or external data sources.
ClickHouse Cloud's remote MCP server exposes a broader managed toolset. It includes query and schema exploration plus tools for organizations, services, backups, ClickPipes, and organization cost data. The remote Cloud server is read-only and is designed to provide analytical and operational context without allowing the agent to modify data or service configuration.
When to use it
Use ClickHouse MCP when an AI assistant needs live analytical context from ClickHouse: exploring schemas, drafting or checking SELECT queries, summarizing table structure, investigating service metadata, or answering usage and backup questions in ClickHouse Cloud. It is useful for data analysts, platform teams, and developers who want agents to work with ClickHouse data without copying credentials or result sets into prompts.
Connection and authentication
For ClickHouse Cloud, the remote MCP endpoint is https://mcp.clickhouse.cloud/mcp using Streamable HTTP. The user enables MCP for a service in the ClickHouse Cloud console, then authenticates through an OAuth 2.0 browser flow with ClickHouse Cloud credentials. Access is scoped to the organizations and services available to that user.
For the open-source local server, the documented default transport is stdio. It can be launched with uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse and configured with ClickHouse connection environment variables such as CLICKHOUSE_HOST, CLICKHOUSE_USER, and CLICKHOUSE_PASSWORD. The local server also has an HTTP mode controlled by CLICKHOUSE_MCP_SERVER_TRANSPORT=http, but the stdio configuration is the standard client setup shown in the repository.
Key considerations
Treat the database identity used by the MCP server like any external ClickHouse client. ClickHouse specifically recommends granting the minimum necessary privileges and avoiding default or administrative users. The open-source server enforces read-only queries by default; write access requires CLICKHOUSE_ALLOW_WRITE_ACCESS=true, and destructive DROP or TRUNCATE operations require both that flag and CLICKHOUSE_ALLOW_DROP=true. Authentication should not be disabled except for local development, and TLS verification should remain enabled in production.
Supported Transports
streamable_http
URL: https://mcp.clickhouse.cloud/mcp
stdio
Command: uv
Args:
run--withmcp-clickhouse--python3.10mcp-clickhouse
Frequently Asked Questions
- When should an AI agent use the ClickHouse MCP server?
- Use it when an AI agent needs to inspect ClickHouse databases, list tables, understand schemas, or run analytical SELECT queries against ClickHouse data. The ClickHouse Cloud remote server is also useful when the agent needs Cloud service, organization, backup, ClickPipes, or billing context without managing a local MCP process.
- What does ClickHouse MCP add to an AI agent's capabilities?
- It gives the agent live access to ClickHouse metadata and query tools instead of relying on static prompt context. The local open-source server exposes database listing, table listing, and SELECT query execution; the ClickHouse Cloud remote server adds managed read-only tools for Cloud organizations, services, backups, ClickPipes, and costs.
- What can the AI agent access or manage through ClickHouse MCP?
- Through the documented tools, an agent can list databases, inspect tables, and run read-only SELECT queries. In ClickHouse Cloud, it can also retrieve information about organizations, services, backups, ClickPipes, and organization costs. The remote Cloud MCP server is read-only and cannot modify data or service configuration.
- How is authentication configured for ClickHouse MCP?
- The remote ClickHouse Cloud MCP server uses OAuth 2.0 with the user's ClickHouse Cloud credentials and scopes access to the organizations and services that user can access. The local open-source server uses ClickHouse connection environment variables such as `CLICKHOUSE_HOST`, `CLICKHOUSE_USER`, and `CLICKHOUSE_PASSWORD`; production deployments should use a least-privilege database user.
- Which transport should be used for ClickHouse MCP?
- Use Streamable HTTP at `https://mcp.clickhouse.cloud/mcp` for the managed ClickHouse Cloud remote MCP server. Use stdio for the open-source `mcp-clickhouse` server when connecting a local MCP client to a ClickHouse instance through a locally launched process.