de en es ja ko ru zh

mcp-clickhousex

Name: mcp-clickhousex
Author: alyiox

by alyiox

Overview Schema Source Related Servers Discussions Admin

Python

Remote

MCP ClickHouse Tool

Сервер 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.

Inputs: sql (required), types, profile, database, +1 more. Returns: Structured EXPLAIN text output keyed by explain type.

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.

Inputs: profile. Returns: ClickHouse cluster metadata safe to surface to MCP clients.

list_columnsA

Read-only

[ClickHouse] List columns for a table or view.

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

Inputs: table (required), profile, database. Returns: Generic tabular result with ordered columns and aligned row values.

list_databasesB

Read-only

[ClickHouse] List databases.

Rows from system.databases visible to the connection.

Inputs: profile. Returns: Generic tabular result with ordered columns and aligned row values.

list_profilesA

Read-only

[ClickHouse] List configured profiles.

Each entry includes name and optional description.

Inputs: no named parameters. Returns: result

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.

Inputs: profile, database. Returns: Generic tabular result with ordered columns and aligned row values.

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.

Inputs: sql (required), profile, database, snapshot, +1 more. Returns: result

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.

Inputs: sql (required), profile, database, parameters. Returns: Result of a SHOW introspection statement (columns + rows + optional truncation).

Tool Schema Changelog

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

Loading tool schema changelog…

Deploy Server

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

A4/5.0

Scored 2026-07-28 14:40 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

ActivitySlowing

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Lemonado
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
https://mcp.lemonado.io/mcp
The Quiet Protocol Growth Offense MCPA
com.thequietprotocol.www
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Databases Research & Data Finance
292
https://www.thequietprotocol.com/api/mcp
classquill-mcp
io.github.EquateItAu
Read-only MCP server for ClassQuill, a tutoring-business-management platform.
Education & Learning Tools CRM
2
https://mcp.classquill.com/mcp
BigQuery MCP by InsightfulPipeA
com.insightfulpipe
Hosted BigQuery MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Databases Data Platforms Cloud Platforms
41
https://bigquery.insightfulmcp.com/

Related MCP Servers

mcp-clickhouse
Databases Developer Tools
stiproot
A
license
A
quality
D
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.
Updated 10 months ago (2026-01-13 13:17 UTC)
3
Apache 2.0
io.github.Aguantar/clickhouse
Databases Monitoring
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.
Updated 8 months ago (2026-03-19 03:49 UTC)
8
32 PyPI
MIT
db-connect-mcp
Databases Developer Tools
yugui923
A
license
A
quality
B
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.
Updated 14 days ago (2026-11-01 02:33 UTC)
10
84 PyPI
6
MIT
clickhouse-mcp-server
Databases Developer Tools
reiple
F
license
A
quality
D
maintenance
Read-only MCP server for ClickHouse that allows listing databases and tables, describing schemas, and running SELECT queries.
Updated 4 months ago (2026-07-07 15:08 UTC)
4
-

MCP ClickHouse Tool

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

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

Инструменты

Ресурсы

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

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

Cursor

Codex

OpenCode

Claude Code

Copilot

Тесты

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

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

Лицензия

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-clickhouse

io.github.Aguantar/clickhouse

db-connect-mcp

clickhouse-mcp-server