ClickHouse/mcp-clickhouse

Подключите ClickHouse к вашим AI-ассистентам.

MCP⭐ 877Pythonпоследний релиз: v0.6.0

Что это за инструмент

Это MCP-сервер для подключения AI-ассистентов к базе данных ClickHouse, позволяющий моделям выполнять SQL-запросы и управлять метаданными.

Зачем нужен

Инструмент решает задачу прямого доступа LLM к данным без написания промежуточного кода. Он полезен для создания систем RAG и аналитических агентов, которым нужно запрашивать актуальные данные из ClickHouse через стандартный протокол MCP.

Что можно реализовать

Запуск произвольных SQL-запросов к кластеру ClickHouse через AI-ассистента
Просмотр списка баз данных и таблиц с фильтрацией и пагинацией
Анализ данных из файлов или URL с помощью встроенного движка chDB без ETL
Интеграция ClickHouse в агенты через HTTP/SSE с поддержкой аутентификации

Ключевые возможности

Инструмент run_query для выполнения SQL с возможностью переключения в режим записи
Инструмент run_chdb_select_query для локального анализа данных через chDB
Детальная работа с метаданными: list_tables с фильтрами, пагинацией и опциональным скрытием метаданных колонок
Гибкая аутентификация: статические токены, OAuth/OIDC (Azure, Google и др.) или отключение для локальной разработки
Эндпоинт /health для проверки доступности сервера без передачи учетных данных

👤 Кому подойдёт: разработчики, инженеры данных, специалисты по AI, работающие с ClickHouse и MCP-инфраструктурой

Релизы

v0.6.0majorbreaking

🕐 18 дн назад · релиз на GitHub ↗

Переход на FastMCP 4 и поддержку MCP 2026-07-28, оптимизация метаданных и исправление ошибок пагинации.

Added: Добавлена поддержка протокола MCP 2026-07-28, включая server/discover и кэширование ответов.
Breaking: Внедрены изменения для совместимости с FastMCP 4, требующие обновления кастомного middleware.
Deprecated: Стандартный HTTP+SSE транспорт объявлен устаревшим, рекомендуется использовать Streamable HTTP.
Fixed: Исправлены гонки токенов пагинации и сохранение курсоров при сбоях и отмене запросов.
Added: Метаданные теперь обрабатываются в отдельном потоке, чтобы не задерживать выполнение запросов.

v0.5.0majorbreaking

🕐 19 дн назад · релиз на GitHub ↗

Релиз v0.5.0: усиление безопасности HTTP, защита от DNS-ребиндинга, кэширование клиентов и новые ограничения на разрушительные запросы.

Breaking: Добавлена валидация заголовков Host и Origin по умолчанию; для wildcard-биндов требуется настройка CLICKHOUSE_MCP_ALLOWED_HOSTS.
Breaking: Переменная CLICKHOUSE_ALLOW_DROP теперь также ограничивает операции DELETE, UPDATE, удаление партиций и столбцов.
Added: Реализована защита от DNS-ребиндинга для HTTP, SSE и режимов запуска fastmcp.
Added: Клиенты ClickHouse переиспользуются между вызовами инструментов, добавлена серверная отмена запросов по таймауту.
Fixed: Большие целые числа возвращаются как строки для избежания ошибок точности в JavaScript.

v0.4.1minor

🕐 2 мес назад · релиз на GitHub ↗

Релиз v0.4.1: добавлена поддержка официальных навыков агентов через FastMCP и публикация в MCP Registry.

Added: Внедрены официальные навыки агентов ClickHouse через инструкции уровня сервера FastMCP, заменившие старую систему рекомендаций на основе инструментов.
Added: Пакет mcp-clickhouse опубликован в официальном MCP Registry (registry.modelcontextprotocol.io) и синхронизирован с репозиторием github.com/mcp.

v0.4.0minorbreaking

🕐 3 мес назад · релиз на GitHub ↗

Релиз v0.4.0: добавлена поддержка OAuth/OIDC, опубликованы официальные образы GHCR и исправлены проблемы с конкурентностью запросов.

Added: Добавлена аутентификация OAuth/OIDC для HTTP/SSE транспортов (Azure Entra, Google, GitHub, WorkOS).
Added: Официальные мультиархитектурные Docker-образы теперь публикуются в GHCR.
Breaking: Режимы аутентификации стали взаимоисключающими: можно использовать только один.
Breaking: Ответы инструментов теперь возвращаются в виде JSON-строк, а не сырых словарей.
Fixed: Долго выполняемые запросы больше не блокируют выполнение других инструментов.