ClickHouse Readonly MCP

What is ClickHouse Readonly MCP?

A FastMCP server for executing read-only ClickHouse queries. It supports local Python API integration and can run as a standalone service, making it suitable for AI assistants and workflow automation that need safe database access.

How to use ClickHouse Readonly MCP?

Install via pip install clickhouse-readonly-mcp or from source. Configure it in your MCP client (e.g., Cursor's config.json) by setting environment variables such as CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD, and optionally CLICKHOUSE_RESOURCE_DESC_FILE. The server then exposes tools that accept read-only SQL queries.

Key features of ClickHouse Readonly MCP

• Enforces read-only SQL queries (SELECT, SHOW, DESCRIBE, EXPLAIN)
• Supports both HTTP and native ClickHouse protocols with auto-fallback
• Outputs results in a clean table format
• Supports parameterized queries for safe execution
• High‑performance query execution and result handling

Use cases of ClickHouse Readonly MCP

• Allow AI assistants to safely query ClickHouse without risk of data modification
• Provide database context to large language models via a resource description file
• Expose ClickHouse as a read-only API within a Model Context Protocol workflow
• Integrate into automated data retrieval pipelines that require strict read‑only access

FAQ from ClickHouse Readonly MCP

What SQL operations are allowed?

Only read‑only SQL statements are permitted: SELECT, SHOW, DESCRIBE, EXPLAIN, and similar commands. Any attempt to run INSERT, UPDATE, DELETE, etc. is rejected.

Which ClickHouse connection protocols are supported?

Both the native ClickHouse port and the HTTP port are supported. The server automatically switches between them if one fails.

What environment variables are required?

You must set CLICKHOUSE_HOST, CLICKHOUSE_PORT, and authentication credentials (CLICKHOUSE_USER / CLICKHOUSE_USERNAME and CLICKHOUSE_PASSWORD). Optionally, set CLICKHOUSE_HTTP_PORT and CLICKHOUSE_RESOURCE_DESC_FILE to improve model understanding.

Does the server support parameterized queries?

Yes. It accepts query parameters, enabling safe, reusable query execution.

What runtime dependencies does it need?

Python 3 and the clickhouse-readonly-mcp package (which pulls in the necessary ClickHouse driver and FastMCP library). No additional system services are required.