mcp-clickhouse

Official

Overview Schema Source Related Servers Discussions Admin

List Tables

list_tables

List tables in a ClickHouse database with schema, row count, and column count. Filter by name patterns and paginate results.

Instructions

List available ClickHouse tables in a database, including schema, comment, row count, and column count.

Integers outside [-9007199254740991, 9007199254740991] in table metadata are returned as decimal strings. Pagination tokens are single-use and retained for up to one hour.

Input Schema

TableJSON Schema

Name	Required	Description
`like`	No	Optional LIKE pattern to filter table names
`database`	Yes	The database to list tables from
`not_like`	No	Optional NOT LIKE pattern to exclude table names
`page_size`	No	Number of tables to return per page (default: 50, must be greater than 0)
`page_token`	No	Single-use token from a previous call, retained for up to one hour
`include_detailed_columns`	No	Whether to include detailed column metadata (default: True). When False, the columns array will be empty but create_table_query still contains all column information. This reduces payload size for large schemas.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.7.0Sep 22, 2026
Removedv0.4.1Jul 24, 2026
Changed5 schema fields changedv0.2.0Apr 29, 2026
- removedOutput schema / additionalProperties
```
Removed value: -true
```
- addedOutput schema / description
```
Added value: +"Generic wrapper for non-object return types."
```
- addedOutput schema / properties
```
Added value: +{
+  "result": {
+    "type": "string"
+  }
+}
```
- addedOutput schema / required
```
Added value: +[
+  "result"
+]
```
- addedOutput schema / x-fastmcp-wrap-result
```
Added value: +true
```
First observedv1.0.0Jan 2, 2026

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose two non-obvious behaviors: large integers become decimal strings, and pagination tokens are single-use and retained for one hour. This is meaningful transparency, though it does not address all potential behaviors such as sorting or default pagination size.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no filler. The first sentence states the core purpose and output, and the following two sentences provide essential behavioral quirks. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema made available and 100% parameter coverage, the description does not need to restate return structures or parameter details. It adequately covers the non-obvious behaviors around large integers and pagination tokenshare tokens, making it largely complete for an agent to invoke correctly. It falls short of 5 because it lacks any guidance on when to prefer this over list_databases or run_query.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameter descriptions in the schema already cover 100% of parameters, including defaults and semantics. The description adds minor context around pagination token behavior and output metadata, but does not need to compensate for schema gaps. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists ClickHouse tables in a database and includes specific metadata fields (schema, comment, row count, column count). This distinguishes it from sibling tools list_databases and run_query based on the resource being operated on and the nature of the operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for discovering table metadata, which contrasts with list_databases and run_query, but it never explicitly states when to use this tool over its siblings. There is no direct mention of alternatives or exclusion conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server