ClickHouse MCP Server
ClickHouse database queries and chDB engine operations via MCP.
Data last scanned today · Reviewed yesterday
Overview
This MCP server provides a interface for interacting with ClickHouse clusters. It features tools to execute SQL queries, list databases, and browse tables with configurable pagination and metadata filtering options. The server also supports the chDB embedded engine, allowing users to run SQL queries directly against files, URLs, or external data sources without prior ETL processing. Designed with flexible transport options, the server supports both stdio and HTTP/SSE. It includes a dedicated health check endpoint to facilitate integration with container orchestrators like Kubernetes. While it defaults to read-only operation for SQL queries, users can explicitly enable write access if their workflow requires it.
Our verdict
This server carries a high risk level with a security score of 30/100. The primary concern is the lack of inherent authentication, which allows anyone with access to the server configuration to execute commands against your cluster. Furthermore, the absence of an official vendor mandate means maintenance is community-driven. Due to the potential for unrestricted access to your data, this tool is best suited for isolated, private development environments rather than public-facing or sensitive production infrastructure.
- Zero direct dependencies minimize supply-chain surface area.
- Supports chDB for querying data without ETL.
- Built-in support for paginated table listing.
- Includes a health check endpoint for orchestration.
- No built-in authentication for local configuration access.
- Community-maintained rather than official ClickHouse vendor support.
- Unauthenticated health endpoint potentially exposed.
Tools
| Tool | Description | Risk |
|---|---|---|
| run_query | Execute SQL queries on your ClickHouse cluster. | medium |
| list_databases | List all databases on your ClickHouse cluster. | low |
| list_tables | List tables in a database with pagination. | low |
| run_chdb_select_query | Execute SQL queries using chDB's embedded ClickHouse engine. | low |
Compatibility
| Client | Local | Docker | Remote | Read-only |
|---|---|---|---|---|
| ChatGPT | ||||
| Claude Desktop | ||||
| Cursor | ||||
| VS Code | ||||
| Windsurf |
Frequently asked questions
›Can I perform write operations on my ClickHouse cluster?
Yes, writes are possible, but they are disabled by default. You must explicitly enable them by configuring the CLICKHOUSE_ALLOW_WRITE_ACCESS environment variable.
›Is authentication required to run the server?
Authentication is required by default when using HTTP or SSE transport modes. Stdio transport does not require authentication, and you can disable it for local development using the CLICKHOUSE_MCP_AUTH_DISABLED environment variable.
›How do I use the embedded ClickHouse engine?
You can use the run_chdb_select_query tool to query data directly from sources like files or URLs. This feature requires installing the chdb extra via 'pip install mcp-clickhouse[chdb]'.
›Is the /health endpoint protected by my authentication token?
No, the /health endpoint is intentionally unauthenticated to allow infrastructure like load balancers or Kubernetes liveness probes to verify the server status without credentials.
›Can I customize the table list output to reduce response size?
Yes, you can set the include_detailed_columns input to false when calling list_tables to omit column metadata while still receiving the create_table_query.
›Which authentication providers are supported for production?
You can use FastMCP's built-in OAuth/OIDC providers, which support services such as Azure Entra, Google, GitHub, and WorkOS by setting the FASTMCP_SERVER_AUTH environment variable.
Alternatives
Changelog
Badge
Maintain this server? Add the live badge to your README.