mcp-clickhouse
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation4/5
Most tools target clearly distinct resources: databases, tables, column metadata, DDL statements, table storage stats, running queries, server metrics, and cluster topology. The main overlaps are `query` with the targeted metadata helpers and `list_tables`/`table_stats`, but the descriptions are specific enough to guide an agent.
Naming Consistency3/5All names use lowercase snake_case, which helps, but the pattern is not uniform: `list_databases`, `list_tables`, and `describe_table` are verb-first, while `table_stats`, `server_metrics`, and `cluster_info` are noun-first phrases. A consistent `verb_noun` convention would make the toolset more predictable.
Tool Count5/5Nine tools is a well-scoped size for a ClickHouse exploration and querying server. Each tool maps to a meaningful, non-redundant area such as schema inspection, runtime stats, or query execution.
Completeness3/5The read-side coverage is strong: schema discovery, table statistics, running queries, metrics, cluster topology, and SELECT/SHOW/DESCRIBE querying are all covered. The notable gap is that non-read statements are explicitly mentioned as possible via `execute`, but no such tool is exposed here, so DDL/write workflows are not actually provided.
Average 3.7/5 across 9 of 9 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 3 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only lists the type of data returned and does not state that this is a read-only operation, what happens for nonexistent tables, whether permissions are needed, or any other behavioral traits. The noun-phrase form also avoids explicitly confirming an action like 'retrieve' or 'return'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is a single concise phrase, 'Column names, types, defaults, and comments for a table,' which directly addresses the tool's purpose without any filler or needless repetition. It is appropriately short for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with only two required, fully schema-described parameters, the description is largely complete: it clearly indicates the returned content despite there being no output schema. It could add contextual completeness by explicitly stating what can go wrong (e.g., nonexistent table) or confirming a read-only behavior, but the core agent-facing information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema as 'Table name' and 'Database name' (100% schema_description_coverage). The description does not materially add meaning beyond 'for a table'; the baseline score of 3 is appropriate because the schema already covers parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates the resource (a table) and the kind of information returned: column names, types, defaults, and comments. It goes beyond a tautology and accurately describes the tool's purpose, but it does not explicitly differentiate it from sibling tools like `show_create_table` or `table_stats`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as show_create_table, list_tables, or table_stats. The description implies a table inspection use-case but provides no explicit conditions, exclusions, or contrasting guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does disclose that only non-zero metrics are returned and names example metric areas, which is useful. However, it does not describe the return format, units, or any operational constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key behavior (non-zero metrics) and gives helpful examples. It is concise without being a vague tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple zero-parameter metrics tool, the description is mostly sufficient, but the absence of an output schema means the agent still lacks concrete information about response shape. It covers what the tool does but not all an agent might need to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter semantics is not a real burden on the description. The baseline of 4 applies here; the description correctly focuses on what the tool returns rather than input details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning server metrics from system.metrics and even highlights the non-zero filtering and metric families. It does not use an explicit verb, but it is specific enough to distinguish from the database-/table-focused siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to prefer server_metrics versus alternatives like cluster_info or running_queries. The usage context is only implied by the name and metric examples, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and it is clear that the tool reads system.parts, implying a read-only operation. However, it does not disclose how the data is aggregated, whether only active parts are counted, or what the exact 'time range' means. It also doesn't specify the format of the return value, such as whether a single row or list is returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, terse sentence that lists the key result fields and the source, with no redundant wording. It is front-loaded with the most important information and is highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only two required string parameters and no output schema, the description sufficiently conveys what the tool returns, enabling an agent to call it and interpret the result. The only minor gap is the ambiguity of output representation (e.g., a single row vs. multiple rows), but that is a low-stakes for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents both parameters with clear descriptions ('Table name' and 'Database name') and schema description coverage is 100%. Thus the description adds no more than the schema already provides, and the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies concrete outputs (part count, row count, on-disk size, time range) and names the source system.parts, which makes the tool's purpose readily understood. It is clearly different from sibling tools like list_tables, describe_table, and show_create_table, though it lacks an explicit verb like 'retrieve'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to choose this tool over alternatives or when not to use it. There is no mention of prerequisites, exclusions, or whether to prefer it over query when needing these specific metrics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It reveals that the tool reads from system.clusters and reports topology, which implies a read-only metadata operation, but it does not disclose output format, scope, or any limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single tight sentence that names the resource, source, and key output aspects with no filler. It is instantly scannable and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless metadata tool, the description covers the essential purpose and source. It could add a little more detail about the expected return shape or whether it requires a specific cluster context, but the simplicity keeps the risk of misuse low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema requires no explanation. The description adds meaningful context about what the cluster topology covers, which is sufficient for an argument-less tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (cluster topology) and source (system.clusters), with specifics like shards, replicas, and hosts. It does not use an explicit verb like 'retrieve' or 'list', but the intent is unambiguous and distinct from the sibling metadata tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool instead of siblings such as server_metrics or query. The description does not state exclusions or preferred contexts, so the agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must explain behavior. It conveys that this is a snapshot of currently executing queries with a few fields, implying a read-only inspection action. However, it does not explicitly state whether it is safe, whether it can be run without side effects, or how results are ordered or bounded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the subject and then lists the key data fields. Every word contributes useful meaning, and the format is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description covers the essential return fields and data source. It could include a brief note on when to inspect running queries, but it is not missing critical invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description has no obligation to clarify parameter behavior. The baseline of 4 applies because there is simply no parameter information that could be missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a clear subject (currently executing queries), a specific source (system.processes), and the included fields (id, user, elapsed, memory). It is distinct from siblings like query or server_metrics, though it lacks an explicit action verb such as 'List' or 'Returns'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus siblings like server_metrics or query. There are no stated exclusions, alternatives, or 'when to use' hints beyond the description itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full behavioral disclosure burden. It clarifies that the tool lists tables with specific attributes, implying a non-destructive operation, but it does not mention permissions, output structure, or any constraints. This is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence delivers the operation, scope, and output attributes without redundant wording. The most important information is front-loaded, and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and no output schema, the description provides essential information: what is listed and which metadata is returned. It lacks details on edge cases or return formatting, but given the tool's simplicity, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the single parameter fully with a 'Database name' description (100% coverage). The description does not add any additional format, default, or scoping detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'tables in a database' and details the output fields (engine, row count, size). This distinctly differentiates the tool from siblings like list_databases and describe_table, which address different resources or granularity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to select this tool over siblings such as list_databases or table_stats. The description only states what the tool does, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the burden of behavioral disclosure. It conveys an obviously read-only listing operation and reveals the returned information (databases and engines), but it does not mention whether any authorization, result format, or pagination behavior applies. For a zero-parameter list tool this is adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with a clear verb and object, presented up front. It is not padded with redundant language and every word contributes meaning, making it ideal for fast operator scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list operation, the one-line description is close to sufficient: it states the essential output, database names and engines. The lack of an output schema could have been be compensated by a slightly more explicit return format, but the description still covers the main context an agent needs to decide to call this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline of 4 is appropriate. There is no parameter schema information that needs extra explanation, and the description correctly omits parameter guidance because there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly names the action ('List') and resource ('databases'), and adds a specific scope detail ('and their engines'). This directly distinguishes it from sibling tools such as list_tables and describe_table, which operate on table or schema details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance, but the naming of the tool and the sibling list imply it is for database discovery before moving to table-level operations. The description does not tell the agent when to select this instead of list_tables, so it only provides implied rather than explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It clearly states the action (Return) and the exact output scope (full CREATE TABLE statement), making the tool's behavior evident and indicating it is a read-only convenience.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the result first and adds necessary details in parentheses. There is no filler and no repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two well-documented parameters, the description explains what will be returned. It is still missing a few contextual details, such as error behavior for missing tables or database visibility/permissions, and there is no output schema to fill that gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already fully documents both required parameters. The description adds no extra semantics about the database or table parameters, but the 100% coverage justifies the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names the exact verb (Return) and resource (the full CREATE TABLE statement), and specifies its scope (schema, engine, settings). This is more specific than the tool name alone and clearly differentiates it from sibling tools like describe_table.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is given, and no alternative tools are named. The use case is implied by the description, but the agent isn't told how to choose between this and describe_table or list_tables.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It discloses the read-only safety posture, states that non-read statements will be refused, and notes the CLICKHOUSE_MAX_ROWS cap, which is valuable behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The main operation is stated first, the restriction and alternative are second, and the row cap is included without extra prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with one clear schema and no nested objects, the description is quite complete: it states allowed statements, describes the return behavior, clarifies limitations, and routes non-read calls elsewhere. The only minor gap is lack of detail around the exact shape or formatting rows.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the `sql` parameter as a single read-only SQL statement at 100% coverage. The description adds only a minor clarification of allowed statement types, which is helpful but not essential for understanding the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states precisely what the tool executes: SELECT/SHOW/DESCRIBE queries that return rows. It also clearly separates read-only from read-write behavior by naming the non-read alternative, making selection unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly defines when to use this tool (SELECT/SHOW/DESCRIBE) and what to do for non-read statements: use `execute` for read-write mode. This is an explicit when/when-not/alternative pattern.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/dockndevai/mcp-clickhouse'
If you have feedback or need assistance with the MCP directory API, please join our Discord server