Skip to main content
Glama
deenesjakoruzh
alyiox

mcp-clickhousex

by alyiox
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

MCP ClickHouse Tool

CI PyPI Python 3.13+ License: MIT

Сервер Model Context Protocol (MCP) для ClickHouse, доступный только для чтения, который поддерживает обнаружение метаданных, ресурсы, параметризованные SELECT-запросы, интроспекцию SHOW, анализ запросов и режим снимков для больших наборов результатов, с конфигурацией на основе профилей и строгим запретом операций DML/DDL.

Требования: Python 3.13+, работающий экземпляр ClickHouse и данные для подключения через переменные окружения или файл конфигурации.

Быстрый старт

Задайте DSN и запустите сервер с помощью MCP Inspector:

# Option 1: Run directly with uvx (no clone needed)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector uvx mcp-clickhousex
# Option 2: Run from source (clone repo, then)
export MCP_CLICKHOUSE_DSN="http://default:@localhost:8123/default"
npx -y @modelcontextprotocol/inspector uv run main.py

Related MCP server: io.github.Aguantar/clickhouse-dataops-mcp

Конфигурация

Все настройки используют префикс MCP_CLICKHOUSE. Плоские переменные окружения (например, MCP_CLICKHOUSE_DSN) — это простой способ настроить профиль по умолчанию, когда у вас одно подключение. Для нескольких профилей рекомендуется файл config.json в области пользователя.

Одно подключение: настройка через переменные окружения.

# Connection DSN (required).
export MCP_CLICKHOUSE_DSN="http://user:password@host:8123/database"

# Optional description for the default profile (tooling/AI discovery).
export MCP_CLICKHOUSE_DESCRIPTION="Primary cluster"

# Optional max rows per interactive query (default 500; hard ceiling 1000).
export MCP_CLICKHOUSE_QUERY_MAX_ROWS="500"

# Optional interactive query timeout in seconds (default 30; hard ceiling 300).
export MCP_CLICKHOUSE_QUERY_COMMAND_TIMEOUT_SECONDS="30"

# Optional max rows for snapshot queries (default 10000; hard ceiling 50000).
export MCP_CLICKHOUSE_SNAPSHOT_MAX_ROWS="10000"

# Optional snapshot query timeout in seconds (default 120; hard ceiling 300).
export MCP_CLICKHOUSE_SNAPSHOT_COMMAND_TIMEOUT_SECONDS="120"

Несколько подключений: используйте файл config.json в области пользователя (рекомендуется). Переменные окружения также работают через префикс MCP_CLICKHOUSE_PROFILES_<NAME>_ (например, MCP_CLICKHOUSE_PROFILES_WAREHOUSE_DSN).

  • Unix-like: ~/.config/mcp-clickhousex/config.json

  • Windows: %USERPROFILE%\.config\mcp-clickhousex\config.json

Пример (config.json):

{
  "profiles": {
    "default": {
      "dsn": "http://default:@localhost:8123/default",
      "description": "Primary",
      "query_max_rows": 500,
      "query_command_timeout_seconds": 60,
      "snapshot_max_rows": 10000,
      "snapshot_command_timeout_seconds": 120
    },
    "warehouse": {
      "dsn": "http://user:pass@warehouse:8123/analytics",
      "description": "Warehouse"
    }
  }
}

Специальные символы в учётных данных: если имя пользователя или пароль содержит зарезервированные в URL символы, закодируйте их в процентах в DSN:

Символ

Кодировка

#

%23

?

%3F

/

%2F

@

%40

%

%25

Например, имя пользователя admin@org и пароль p#ss? превращаются в admin%40org:p%23ss%3F в DSN: http://admin%40org:p%23ss%3F@host:8123/database.

Инструменты

Описания инструментов соответствуют docstring'ам инструментов в server.py, за исключением того, что префикс [ClickHouse] здесь опущен (он остаётся в метаданных, доступных через MCP). Текст параметров соответствует каждому Field(description=…) того же инструмента.

Tool

Description

Key params

list_profiles

Список настроенных профилей. Каждая запись включает имя и необязательное описание.

—

get_cluster_properties

Получение свойств кластера и лимитов выполнения. Возвращает версию сервера ClickHouse, а также применяемые лимиты (максимальное количество строк, таймауты) для профиля.

profile — Имя профиля; при отсутствии используется профиль по умолчанию. Источник: profiles.

run_query

Выполнение read-only запроса SELECT или WITH … SELECT. Один оператор; DML, DDL, SET, SYSTEM и подобные отклоняются. Возвращает {data, row_count}, где data — строка CSV в формате RFC 4180. Передайте snapshot=true, чтобы сохранить результат на диск и получить вместо этого {snapshot_uri, row_count}; загрузите CSV через URI ресурса снимка. Ограничение максимального количества строк; при превышении устанавливаются truncated и row_limit. Та же проверка SQL, что и в analyze_query.

sql (обязательный) — Read-only SELECT или WITH … SELECT. Один оператор; используйте полное имя db.table или database. Синтаксис плейсхолдеров драйвера для параметров. parameters — Именованные параметры для плейсхолдеров драйвера (например, %(name)s или {name:Type}). database — База данных по умолчанию для сеанса для неполных имён. Источник: databases. profile — Имя профиля; при отсутствии используется профиль по умолчанию. Источник: profiles. snapshot — Если true, сохраняет полный результат в виде CSV-файла и возвращает URI ресурса (chx://snapshots/{id}) вместо встроенных данных. Используйте для запросов, которые могут превысить интерактивный лимит строк (1 000). Применяются лимиты снимков (по умолчанию 10 000 строк, жёсткий потолок 50 000). Записи истекают через 7 дней.

run_show

Выполнение оператора SHOW для интроспекции. Один оператор за вызов; INTO OUTFILE отклоняется. Применяются интерактивные лимиты строк (по умолчанию 500, жёсткий потолок 1 000). Тот же таймаут, что и у run_query.

sql (обязательный) — Один оператор SHOW (например, SHOW DATABASES, SHOW CREATE TABLE). Без INTO OUTFILE. parameters — Именованные параметры для плейсхолдеров драйвера (например, %(name)s или {name:Type}). database — База данных по умолчанию для сеанса для неполных имён. Источник: databases. profile — Имя профиля; при отсутствии используется профиль по умолчанию. Источник: profiles.

analyze_query

Объяснение read-only запроса SELECT или WITH … SELECT. Возвращает текст плана, конвейера и/или синтаксиса. По умолчанию типы plan и pipeline. Использует таймаут запроса и необязательную базу данных; в отличие от run_query нет ограничения максимального количества строк.

sql (обязательный) — Read-only SELECT или WITH … SELECT для EXPLAIN. Один оператор; та же проверка, что и в run_query. parameters — Именованные параметры для плейсхолдеров драйвера (например, %(name)s или {name:Type}). database — База данных по умолчанию для сеанса для неполных имён. Источник: databases. profile — Имя профиля; при отсутствии используется профиль по умолчанию. Источник: profiles. types — Варианты EXPLAIN: plan (индексы), pipeline, syntax. По умолчанию plan и pipeline, если не указано.

list_databases

Список баз данных. Строки из system.databases, видимые для подключения.

profile — Имя профиля; при отсутствии используется профиль по умолчанию. Источник: profiles.

list_tables

Список таблиц и представлений в базе данных. Строки из system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes для планирования запросов.

database — База данных для перечисления; по умолчанию клиентская, если не указано. Источник: databases. profile — Имя профиля; при отсутствии используется профиль по умолчанию. Источник: profiles.

list_columns

Список столбцов для таблицы или представления. Строки из system.columns для разрешённой базы данных и таблицы.

table (обязательный) — Имя таблицы или представления, или database.table. Источник: tables. database — База данных, если table неполное; игнорируется, если table содержит точку. По умолчанию клиентская, если не указано. Источник: databases. profile — Имя профиля; при отсутствии используется профиль по умолчанию. Источник: profiles.

Ресурсы

Сервер предоставляет те же возможности обнаружения и метаданные, что и инструменты выше, через ресурсы, адресуемые по URI (иерархия, начинающаяся с профиля). description каждого ресурса соответствует соответствующему инструменту (list_profiles, get_cluster_properties, list_databases, list_tables, list_columns), плюс теги Src: для параметров пути URI. Все содержимое ресурсов — JSON (application/json), кроме снимков, которые возвращают CSV (text/csv). Используйте сегмент пути default для профиля или базы данных по умолчанию.

Описания ресурсов соответствуют description=… в @mcp.resource в server.py (такое же опущение префикса, как выше).

URI

Description

chx://profiles

Список настроенных профилей. Каждая запись включает имя и необязательное описание.

chx://profiles/{profile}/cluster-properties

Получить свойства кластера и ограничения выполнения. Возвращает версию сервера ClickHouse и применяемые ограничения (максимальное количество строк, таймауты) для профиля. Src: profiles.

chx://profiles/{profile}/databases

Список баз данных. Строки из system.databases, видимые для подключения. Src: profiles.

chx://profiles/{profile}/databases/{database}/tables

Список таблиц и представлений в базе данных. Строки из system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes для планирования запросов. Src: profiles, dbs.

chx://profiles/{profile}/databases/{database}/tables/{table}/columns

Список столбцов для таблицы или представления. Строки из system.columns для разрешённой базы данных и таблицы. Src: profiles, dbs, tables.

chx://snapshots/{id}

Получить снимок результата запроса по ID. Возвращает полный результат в виде CSV-строки (строка заголовка + строки данных). Записи истекают через 7 дней. Src: run_query with snapshot=true.

Безопасность

Только SQL для чтения: run_query допускает SELECT / WITH … SELECT; run_show допускает один оператор SHOW за вызов. INTO OUTFILE не разрешён в run_show. Интерактивные запросы применяют жёсткий лимит строк (по умолчанию 500, жёсткий потолок 1 000); для больших выгрузок используйте snapshot=true (по умолчанию 10 000, жёсткий потолок 50 000). Параметризованные запросы поддерживаются там, где позволяет драйвер (синтаксис %(name)s или {name:Type}). Используйте переменные окружения для учётных данных подключения — никогда не коммитьте секреты.

Примеры MCP-хостов

Фрагменты для распространённых MCP-клиентов с использованием uvx mcp-clickhousex (клонирование не требуется; убедитесь, что uv есть в вашем PATH). При необходимости замените данные подключения.

Cursor

{
  "mcpServers": {
    "clickhouse": {
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

Codex

[mcp_servers.clickhouse]
command = "uvx"
args = ["mcp-clickhousex"]

[mcp_servers.clickhouse.env]
MCP_CLICKHOUSE_DSN = "http://default:@localhost:8123/default"

OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clickhouse": {
      "type": "local",
      "enabled": true,
      "command": ["uvx", "mcp-clickhousex"],
      "environment": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "clickhouse": {
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

Copilot

{
  "inputs": [],
  "servers": {
    "clickhouse": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-clickhousex"],
      "env": {
        "MCP_CLICKHOUSE_DSN": "http://default:@localhost:8123/default"
      }
    }
  }
}

Расположение файлов конфигурации: Cursor .cursor/mcp.json, Codex/Copilot/OpenCode различаются в зависимости от клиента; см. документацию MCP вашего клиента.

Тесты

Для тестов требуется работающий экземпляр ClickHouse. Тестовый набор создаёт образец таблицы в базе данных по умолчанию, заполняет её и удаляет после.

# Run all tests (unit + functional + e2e)
uv run pytest tests/ -v

Тестовый стенд использует MCP_TEST_CLICKHOUSE_DSN для поиска экземпляра ClickHouse. Если не задано, используется резервное значение http://admin:password123@localhost:8123/default. Установите переменную, чтобы направить тесты на другой сервер, не затрагивая ваш производственный MCP_CLICKHOUSE_DSN:

export MCP_TEST_CLICKHOUSE_DSN="http://user:pass@testhost:8123/default"
uv run pytest tests/ -v

Дорожная карта

На данный момент запланированных функций нет. Откройте issue, чтобы предложить улучшения.

Вклад в проект

Открывайте issues или PR; следуйте существующему стилю и добавляйте тесты, где это уместно.

Лицензия

MIT. См. LICENSE.

Available Tools

8 tools
analyze_queryA
Read-only

[ClickHouse] Explain read-only SELECT or WITH … SELECT.

Returns plan, pipeline, and/or syntax text. Default types plan and pipeline. Uses query timeout and optional database; no max-rows cap unlike run_query.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesRead-only SELECT or WITH … SELECT for EXPLAIN. One statement; same validation as run_query.
typesNoEXPLAIN variants: plan (indexes), pipeline, syntax. Default plan and pipeline if omitted.
profileNoProfile name; uses default profile when omitted. Src: profiles.
databaseNoSession default database for unqualified names. Src: databases.
parametersNoNamed parameters for driver placeholders (e.g. %(name)s or {name:Type}).

Output Schema

ParametersJSON Schema
NameRequiredDescription
planNoEXPLAIN PLAN output.
syntaxNoEXPLAIN SYNTAX output.
pipelineNoEXPLAIN PIPELINE output.

TDQS

A4.6/5.0
Behavior5/5

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

Description adds behavioral context beyond readOnlyHint and openWorldHint annotations, such as query timeout, optional database, and the absence of max-rows cap. No contradiction.

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?

Three concise sentences, front-loaded with core purpose, and each sentence provides distinct information without redundancy.

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 output schema existence and high parameter coverage, description covers key aspects: purpose, defaults, and comparison. Minor missing details like timeout value are acceptable.

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

Parameters4/5

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

Schema coverage is 100%, but description adds value by specifying default types (plan and pipeline) and mentioning query timeout, which is not in schema. Slight improvement over baseline.

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?

Description clearly states the tool performs EXPLAIN on read-only SELECT/WITH SELECT, returning plan/pipeline/syntax. Distinguishes from sibling run_query by noting no max-rows cap.

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

Usage Guidelines4/5

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

Provides context on when to use (for EXPLAIN) and comparison to run_query. Implicitly limits to read-only queries but lacks explicit alternatives for DDL or other analysis tools.

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

get_cluster_propertiesA
Read-only

[ClickHouse] Get cluster properties and execution limits.

Returns ClickHouse server version plus enforced limits (max rows, timeouts) for the profile.

ParametersJSON Schema
NameRequiredDescriptionDefault
profileNoProfile name; uses default profile when omitted. Src: profiles.

Output Schema

ParametersJSON Schema
NameRequiredDescription
limitsYes
versionYesClickHouse server version string.

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already indicate readOnlyHint=true, and the description adds context about specific returned data (version, limits). No contradiction. Does not mention any side effects or authorization needs, but read-only nature covers safety.

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?

Two sentences, no fluff. First sentence states purpose, second describes output. Information is front-loaded and every sentence adds value.

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

Completeness5/5

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

With an output schema present and simple input, the description provides all necessary context. Annotations cover safety, and the description adequately explains the tool's scope and return content.

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?

Schema coverage is 100% and describes the profile parameter well. The description does not add extra details beyond the schema, which is adequate for a single optional parameter.

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?

Description clearly states 'Get cluster properties and execution limits' and specifies it returns 'ClickHouse server version plus enforced limits', which is a specific verb and resource. It distinguishes from sibling tools like run_query and list_profiles.

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?

Implied usage as a read-only check for server properties and limits, but no explicit when-to-use or when-not-to-use guidance compared to siblings like list_profiles.

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

list_columnsA
Read-only

[ClickHouse] List columns for a table or view.

Rows from system.columns for the resolved database and table.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesTable or view name, or database.table. Src: tables.
profileNoProfile name; uses default profile when omitted. Src: profiles.
databaseNoDatabase when table is unqualified; ignored if table contains a dot. Client default when omitted. Src: databases.

Output Schema

ParametersJSON Schema
NameRequiredDescription
rowsYesRow values aligned with the columns list.
columnsYesOrdered list of column names. Each row aligns with these names by index.

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already indicate readOnlyHint=true, so the description's mention of using system.columns adds some context but does not reveal additional behavioral traits beyond what annotations provide.

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 extremely concise with just two sentences, no redundancy, and the key purpose is front-loaded. Every word adds value.

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

Completeness5/5

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

For a simple read-only list tool with full parameter documentation, an output schema, and clear annotations, the description sufficiently covers the context and functionality without needing to explain return values.

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?

Schema description coverage is 100%, and the tool description does not add any extra meaning beyond the existing parameter descriptions, such as explaining the 'Src' references or providing examples.

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 'List columns for a table or view' with a specific verb and resource. It includes the context '[ClickHouse]' and mentions the data source 'Rows from system.columns', making it distinct from sibling tools like list_tables or list_databases.

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 usage for listing columns of a table or view, but it does not provide explicit guidance on when to use this tool vs alternatives, nor does it mention any prerequisites or exclusions.

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

list_databasesB
Read-only

[ClickHouse] List databases.

Rows from system.databases visible to the connection.

ParametersJSON Schema
NameRequiredDescriptionDefault
profileNoProfile name; uses default profile when omitted. Src: profiles.

Output Schema

ParametersJSON Schema
NameRequiredDescription
rowsYesRow values aligned with the columns list.
columnsYesOrdered list of column names. Each row aligns with these names by index.

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true. Description adds the detail that it queries system.databases and depends on connection visibility. No contradictions with annotations.

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?

Two concise sentences, no wasted words, front-loaded with purpose and context.

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?

For a simple read-only tool with one optional parameter and an output schema, the description is adequate. Provides source table and visibility context, but could mention output shape briefly.

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?

Schema coverage is 100% with parameter 'profile' already documented. Description adds no extra meaning beyond the schema.

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

Purpose4/5

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

Clearly states verb 'List' and resource 'databases', includes context '[ClickHouse]' and source 'system.databases'. Differentiates from siblings like 'list_tables' implicitly but no explicit distinction.

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

Usage Guidelines2/5

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

Mentions that rows are from system.databases and visible to the connection, but provides no guidance on when to use this tool vs alternatives like list_tables or run_show. Lacks explicit when-to-use or when-not-to-use.

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

list_profilesA
Read-only

[ClickHouse] List configured profiles.

Each entry includes name and optional description.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

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

The description adds value beyond annotations by specifying that output includes name and optional description. Annotations already declare readOnlyHint=true, so the read-only nature is known. No additional behavioral traits (e.g., ordering, filtering) are disclosed, but the description does not contradict annotations.

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 extremely concise: two sentences that front-load the purpose and follow with a key output detail. Every word earns its place with no redundancy or fluff.

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 zero parameters and the presence of an output schema, the description is mostly complete. It explains what the tool does and what output to expect. It could optionally mention the source of profiles (e.g., system.profiles), but the current level is adequate for a simple listing tool.

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

Parameters4/5

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

The input schema has no parameters, so schema description coverage is 100%. The description does not need to add parameter semantics. It provides a baseline adequate for a parameterless tool.

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

Purpose4/5

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

The description clearly states the action ('List configured profiles') and the resource ('profiles'). The output details are mentioned (name and optional description). However, it does not explicitly differentiate from sibling list tools (e.g., list_databases, list_tables) beyond the resource name, lacking a contrastive statement.

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

Usage Guidelines2/5

Does 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 versus alternatives. There is no mention of prerequisites, common use cases, or when not to use it. The tool is simple, but the description does not help an agent decide between this and other list tools.

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

list_tablesA
Read-only

[ClickHouse] List tables and views in a database.

Rows from system.tables: name, engine, primary_key, sorting_key, partition_key, total_rows, total_bytes for query planning.

ParametersJSON Schema
NameRequiredDescriptionDefault
profileNoProfile name; uses default profile when omitted. Src: profiles.
databaseNoDatabase to list; client default when omitted. Src: databases.

Output Schema

ParametersJSON Schema
NameRequiredDescription
rowsYesRow values aligned with the columns list.
columnsYesOrdered list of column names. Each row aligns with these names by index.

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, and the description adds context about the specific columns returned. However, it does not disclose any behavioral traits beyond that, but given the annotations, this is adequate.

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?

Extremely concise: two sentences that front-load the purpose and return value. No unnecessary words or repetition.

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?

For a simple read-only list tool with an output schema and well-documented parameters, the description is nearly complete. A minor gap: it does not clarify behavior when database is omitted (client default), but overall it is sufficient.

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?

Schema description coverage is 100%, so the schema already documents both parameters (profile, database). The description does not add extra meaning beyond what the schema provides, meeting the baseline.

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 tables and views in a database, specifying the source (system.tables) and the columns returned. It effectively distinguishes from sibling tools like list_databases and list_columns by focusing on tables.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives (e.g., run_show or analyze_query). The description merely states functionality without providing context on preferred scenarios or limitations.

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

run_queryA
Read-only

[ClickHouse] Execute read-only SELECT or WITH … SELECT.

One statement; DML, DDL, SET, SYSTEM, and similar are rejected. Max-rows cap; overflow sets truncated and row_limit. Same SQL validation as analyze_query.

Returns {data, row_count} where data is an RFC 4180 CSV string. Pass snapshot=true to persist the result to disk and receive a {snapshot_uri, row_count} instead; fetch the CSV via the snapshot resource URI.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesRead-only SELECT or WITH … SELECT. One statement; use qualified db.table or database. Driver placeholder syntax for parameters.
profileNoProfile name; uses default profile when omitted. Src: profiles.
databaseNoSession default database for unqualified names. Src: databases.
snapshotNoWhen true, persist the full result as a CSV file and return a resource URI (chx://snapshots/{id}) instead of inline data. Use for queries that may exceed the interactive row limit (1 000). Snapshot limits apply (default 10 000 rows, hard ceiling 50 000). Entries expire after 7 days.
parametersNoNamed parameters for driver placeholders (e.g. %(name)s or {name:Type}).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

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

Annotations declare readOnlyHint=true and openWorldHint=true. Description aligns fully and adds rich behavioral details: max-rows cap, truncation with row_limit flag, CSV return format, snapshot persistence with expiration and limits. No contradictions.

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?

Description is a single, well-structured paragraph with each sentence serving a distinct purpose: resource and verb, constraints, limits, return format, and snapshot alternative. No fluff.

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

Completeness5/5

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

For a tool with 5 parameters, 100% schema coverage, and an output schema (not shown but indicated), the description covers purpose, constraints, limits, return format, and snapshot behavior comprehensively. No gaps given the context.

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

Parameters4/5

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

Input schema has 100% description coverage, but description adds value by explaining the return format (CSV string and snapshot URI pattern) which is not in the input schema. Also reiterates constraints on sql parameter. Overall meaningfully supplements schema.

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?

Description clearly states it executes read-only SELECT or WITH SELECT on ClickHouse. It specifies the resource ([ClickHouse] queries) and verb (execute read-only). Distinguishes from siblings like run_show and analyze_query by stating specific SQL types and validation.

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

Usage Guidelines4/5

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

Explicitly states that only read-only queries are allowed, and DML/DDL/SET etc. are rejected. Mentions same validation as analyze_query, linking to a sibling. Clear context for when to use, but does not explicitly exclude alternatives or provide when-not-to-use guidance.

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

run_showA
Read-only

[ClickHouse] Execute SHOW introspection statement.

One statement per call; INTO OUTFILE rejected. Interactive row limits apply (default 500, hard ceiling 1 000). Same timeout as run_query.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesSingle SHOW statement (e.g. SHOW DATABASES, SHOW CREATE TABLE). No INTO OUTFILE.
profileNoProfile name; uses default profile when omitted. Src: profiles.
databaseNoSession default database for unqualified names. Src: databases.
parametersNoNamed parameters for driver placeholders (e.g. %(name)s or {name:Type}).

Output Schema

ParametersJSON Schema
NameRequiredDescription
rowsYesRow values aligned with the columns list.
columnsYesOrdered list of column names. Each row aligns with these names by index.
row_limitNoThe enforced maximum number of rows returned for this query.
truncatedNoWhether the result set was truncated due to the enforced row limit.

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already mark as read-only, and the description adds critical behavioral details: row limits (500 default, 1000 hard ceiling), INTO OUTFILE rejection, and timeout alignment with run_query. No contradictions.

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?

Three sentences, each earning its place: purpose, constraints on statement, limits. Front-loaded and efficient with zero redundancy.

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

Completeness5/5

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

Given the presence of an output schema, the description sufficiently covers all behavioral aspects for a read-only introspection tool. Includes limits, timeout, and statement restrictions.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the sql parameter constraint (single statement, no INTO OUTFILE) and implicitly relates to row limits. Modest but helpful addition.

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 it executes SHOW introspection statements, distinguishing from siblings like run_query. It specifies constraints (single statement, no INTO OUTFILE), making the purpose specific and unambiguous.

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

Usage Guidelines4/5

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

Provides clear context for when to use (SHOW statements) and constraints (row limits, timeout). Lacks explicit when-not-to-use alternatives, but the sibling tool names imply run_query for other queries.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv0.8.0
    • First observedanalyze_query
    • First observedget_cluster_properties
    • First observedlist_columns
    • First observedlist_databases
    • First observedlist_profiles
    • First observedlist_tables
    • First observedrun_query
    • First observedrun_show
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Scored across 8 tools

Disambiguation5/5

Each tool has a distinct purpose: listing profiles, cluster properties, running SELECT queries, running SHOW statements, analyzing queries, and listing databases, tables, and columns. No overlap in functionality.

Naming Consistency4/5

Uses snake_case consistently, but mixes verb prefixes: 'list_', 'get_', 'run_', 'analyze_'. The pattern is somewhat predictable within categories (metadata listing uses 'list_', execution uses 'run_'), but not fully uniform.

Tool Count5/5

8 tools is well-scoped for a read-only ClickHouse client. Covers metadata discovery, query execution, and analysis without unnecessary tools.

Completeness4/5

Covers essential read-only operations: metadata listing, SELECT, SHOW, and EXPLAIN. Lacks DDL/DML support, but that is intentional. Minor gap: no tool to retrieve table DDL or status.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-clickhouse

    stiproot
    A
    license
    A
    quality
    C
    maintenance
    An MCP server for ClickHouse with enhanced filtering for database and table discovery, supporting LIKE/NOT LIKE patterns and both ClickHouse and chDB tools.
    3
    Apache 2.0

  • io.github.Aguantar/clickhouse

    Aguantar
    A
    license
    A
    quality
    D
    maintenance
    A DataOps-focused MCP server for ClickHouse that provides query optimization advice, pipeline latency analysis, and data quality monitoring, with read-only safety.
    8
    MIT

  • db-connect-mcp

    yugui923
    A
    license
    A
    quality
    A
    maintenance
    A read-only MCP server for exploratory data analysis across PostgreSQL, MySQL, and ClickHouse databases, providing safe, read-only access with comprehensive analysis capabilities.
    10
    6
    MIT