Как подключить ClickHouse к Claude через MCP

💡 Без установки? Используйте cloud.anythingmcp.com напрямую. Войдите, нажмите Connectors → ClickHouse, вставьте учётные данные, создайте MCP API key, и готово. Без Docker, без git clone, без локального сервера.

ClickHouse + Claude

Любой AI-агент может обращаться к серверу ClickHouse или сервису ClickHouse Cloud в режиме только для чтения через HTTP-интерфейс: список баз данных, таблиц и столбцов, операторы CREATE, размеры таблиц, выполняющиеся и недавние запросы и любой SELECT. Каждый запрос несёт readonly=1, поэтому запись отклоняет сам ClickHouse.

Предварительные требования

Полные инструкции по настройке встроены в коннектор (видны в магазине при выборе коннектора). Требуемые переменные окружения:

CLICKHOUSE_URL, CLICKHOUSE_USER, CLICKHOUSE_PASSWORD

Шаг 1 — Получите учётные данные

Настройка занимает около 3 минут. Нужен HTTPS-адрес сервера ClickHouse или сервиса ClickHouse Cloud и пользователь с правом чтения.

1. Укажите адрес HTTP-интерфейса с портом в CLICKHOUSE_URL. В ClickHouse Cloud откройте сервис, нажмите Connect, выберите HTTPS и скопируйте хост, например https://abc123xyz.europe-west4.gcp.clickhouse.cloud:8443. Для собственного сервера: https://your-host:8443 или http://your-host:8123 в частной сети. Только схема, хост и порт, без пути.
2. Создайте отдельного пользователя, который может только читать, например CREATE USER mcp_reader IDENTIFIED BY '...'; GRANT SELECT ON analytics.* TO mcp_reader;. Для clickhouse_table_sizes, clickhouse_running_queries и clickhouse_recent_queries выдайте также GRANT SELECT ON system.parts, system.processes, system.query_log TO mcp_reader. Встроенный пользователь ClickHouse Cloud называется default.
3. Не назначайте этому пользователю профиль настроек с readonly = 2: коннектор ставит readonly=1 в каждом запросе, а при readonly = 2 ClickHouse такое изменение отклоняет. readonly = 0 и 1 работают оба.
4. Укажите имя пользователя в CLICKHOUSE_USER, а его пароль в CLICKHOUSE_PASSWORD. Они передаются как HTTP Basic auth.
5. Только ClickHouse Cloud: IP access list сервиса должен разрешать адрес, с которого обращается AnythingMCP.
6. Установите коннектор и вызовите clickhouse_server_info: он покажет версию, время работы, часовой пояс сервера, подключённого пользователя, его базу данных по умолчанию и действующий уровень readonly.

Что он читает: базы данных, видимые пользователю, с движком и комментарием; таблицы и представления одной базы (движок, общее число строк и байт, читаемый размер, комментарий); столбцы таблицы с типом, выражением по умолчанию и признаком вхождения в ключ партиционирования, сортировки или первичный ключ; оператор CREATE таблицы или представления (движок, ORDER BY, PARTITION BY, TTL, настройки или SELECT, стоящий за представлением); столбцы, которые clickhouse_search_columns находит по имени во всех базах. Для эксплуатации: объём хранения по таблицам по активным частям, выполняющиеся сейчас запросы и завершённые или упавшие запросы из журнала запросов. clickhouse_query выполняет один оператор типа SELECT, WITH, SHOW, DESCRIBE, EXPLAIN или EXISTS.

Что он пишет: ничего. Каждый запрос несёт настройку readonly=1, поэтому ClickHouse отклоняет INSERT, ALTER, CREATE, DROP и SET независимо от прав пользователя. Инструментов записи нет, поэтому при установке ни один инструмент не отключён.

Как ИИ строит запросы: он изучает структуру через clickhouse_list_databases, clickhouse_list_tables, clickhouse_describe_table и clickhouse_show_create_table, затем фильтрует по ключу сортировки и столбцам партиционирования, агрегирует в SQL (count(), sum(), uniq(), quantile(0.95)(x), toStartOfDay(ts)) и всегда заканчивает запрос LIMIT. Перед запросом, который может просканировать большую таблицу, он может выполнить EXPLAIN или EXPLAIN ESTIMATE. Запрос должен быть одним оператором без конструкции FORMAT и без точки с запятой в конце; database задаёт базу по умолчанию для имён таблиц без указания базы.

Форматы данных: формат JSON возвращает meta (имена и типы столбцов), data (строки), rows (число строк) и statistics (прошедшие секунды, прочитанные строки и байты). clickhouse_query может отвечать также в JSONCompact (строки как массивы, компактнее), CSVWithNames или TabSeparatedWithNames. 64-битные целые (UInt64, Int64) приходят строками, так что "12345678901" означает число. Значения DateTime имеют вид YYYY-MM-DD hh:mm:ss в часовом поясе сервера из clickhouse_server_info, если тип столбца не задаёт другой. Размеры из formatReadableSize указаны в двоичных единицах (KiB, MiB, GiB).

Постраничный вывод и ограничения: постраничного вывода нет, и ограничения на число строк тоже нет, кроме вашего LIMIT и предела размера ответа коннектора; весь результат приходит одним ответом, поэтому лучше агрегировать, чем выгружать сырые строки. clickhouse_search_columns возвращает до 500 совпадений. clickhouse_recent_queries возвращает последние 100 запросов за minutes (по умолчанию 60). clickhouse_running_queries показывает только ответивший узел, в ClickHouse Cloud это одна реплика сервиса. Простаивающий сервис Cloud просыпается при первом запросе, и это может занять до минуты.

Частые ошибки: тело ответа содержит Code: <n>. DB::Exception: .... Код 164 (READONLY) означает, что оператор пишет данные или меняет настройку. 497 (ACCESS_DENIED, HTTP 403) означает отсутствующий GRANT или, в ClickHouse Cloud, IP access list, который не пропускает этот сервер. 60 (UNKNOWN_TABLE) и 81 (UNKNOWN_DATABASE) означают неверное имя, 62 (SYNTAX_ERROR) ошибку в SQL, 159 или 241 тайм-аут или предел памяти: сузьте запрос. 401 или 516 (AUTHENTICATION_FAILED) означает неверного пользователя или пароль. Если по адресу ничего не отвечает, обычно неверен порт или в CLICKHOUSE_URL есть путь.

Коннектор не вставляет, не изменяет и не удаляет данные, не создаёт и не меняет таблицы и не управляет сервисами ClickHouse Cloud (запуск, остановка, масштабирование, резервные копии, расходы): для этого установите отдельный коннектор ClickHouse Cloud.

Шаг 2 — Установите адаптер

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Шаг 3 — Добавьте коннектор в Claude

URL вашего сервера: в AnythingMCP откройте MCP Servers → сервер, на котором находится этот коннектор, и скопируйте его URL (https://cloud.anythingmcp.com/mcp/…). Используйте его везде, где в этом руководстве указано YOUR_SERVER_ID.

Рекомендуемый путь: работает в claude.ai web без редактирования конфигурационных файлов.

1. Открой в Claude Customize → Connectors.
2. Нажми +, затем Add custom connector.
3. Введи название, например ClickHouse, и URL удалённого MCP-сервера https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID, затем нажми Add.
4. Нажми Connect и войди в AnythingMCP (OAuth), чтобы разрешить доступ.

Все инструменты ниже появятся в чате: начинайте писать промпты.

Доступные инструменты

Примеры запросов

• «Какие есть базы данных и таблицы, и какие таблицы занимают больше всего места на диске?»
• «Сколько событий в день было в analytics.events за последние 30 дней?»
• «Где лежит столбец вроде customer_id? Поищи во всех базах данных.»
• «Покажи запросы, которые упали за последний час, с кодом ошибки.»
• «Какие 10 стран дали больше всего выручки в этом месяце? Сначала проверь ключ сортировки, чтобы запрос был дешёвым.»

FAQ

Работает ли с Claude Code так же как с Claude Desktop? Да, оба указывайте на https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID.

Следующие шаги

• Страница коннектора
• Подключить к ChatGPT
• Подключить к Cursor
• Подключить к Gemini
• Подключить к Meta Muse
• Подключить к Microsoft Copilot