A FastMCP server for executing read-only ClickHouse queries with support for both HTTP and native protocols
The ClickHouse MCP server has 3 tools with reasonable naming (verb-noun pattern) and descriptions, but critical gaps in schema completeness, parameter validation guidance, and output documentation reduce overall quality. Tool names follow the verb-first convention (list_databases, list_tables, clickhouse_execute_read), which is positive. Descriptions are present but generic (10 - 194 chars, average ~130). The main issue is incomplete input parameter documentation: while some parameters have descriptions, the descriptions lack format constraints, ranges, and validation guidance that LLMs need to pass correct values. Additionally, output schemas are not documented, the code shows dataclass definitions (Table, Column) but the MCP schema responses are not visible, making it impossible to verify that output is properly structured for downstream tool chaining. Error handling is minimal; no recovery guidance, retry logic, or actionable error messages are evident in the source. The server uses STDIO transport, which is a hard cap at 50.
Execute read-only ClickHouse SQL code. Only SELECT, SHOW, DESCRIBE, EXPLAIN allowed; queries are validated before execution.
List available ClickHouse databases
List available ClickHouse tables in a database, including only essential info: table name, engine, row count, and size.
Output schemas not documented. Code defines Table and Column dataclasses but MCP response schemas are not visible. LLMs cannot infer what fields are returned or plan downstream calls.
Parameter descriptions lack format constraints and validation guidance. E.g. 'max_rows' has default=10, maximum=100 in schema but description does not state the range or why these bounds exist. 'like' and 'not_like' lack examples or pattern specifications. LLMs cannot reason about valid inputs.
No error handling guidance. Code has no try-catch or error recovery information visible. LLMs will not know what to do if a query fails, times out, or returns malformed data. No actionable error messages documented.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 51 | <=2025-11-25 | v2 |
| 2026-03-09 | F | 0 | - | v1 |
Parameter 'explanation' is optional on all tools but its purpose is unclear from the description alone. It reads like an elicitation hint or trace annotation, not a functional parameter. If it is merely advisory, it should not be in the schema; if required for agent reasoning, it should be documented and possibly mandatory.
SQL query validation is mentioned ('queries are validated before execution') but validation rules are not documented. What queries are allowed? Are there JOIN limits? Can CTEs be used? LLMs need explicit constraints.
No pagination or result limit guidance for list_databases and list_tables. The rubric baseline is that large result sets should support offset/limit and return a total count. These discovery tools may return many rows; no cap or pagination strategy is documented.