chmonitor MCP
chmonitor — панель мониторинга ClickHouse со встроенным MCP-сервером: агент читает состояние кластера запросами только на чтение
- 304 ★ репозитория
- Последний коммит
- GPL-3.0
Расширенный доступ
Почему такой уровень
- Агент читает запросы, имена таблиц и состояние рабочего кластера, а там могут быть данные клиентов
- Без `CHM_API_KEY_SECRET` и без Clerk эндпоинт `/api/mcp` открыт всем, кто его видит в сети
- Панели нужны адрес и пароль пользователя ClickHouse в переменных контейнера
Установка
- Работает в
Ручная установка
docker run -d --name chmonitor -p 3000:3000 -e CLICKHOUSE_HOST=https://clickhouse.example.com:8443 -e CLICKHOUSE_USER=default -e CLICKHOUSE_PASSWORD=change-me ghcr.io/chmonitor/chmonitor:0.3.11Панель на порту 3000. В production закрепите тег версии, адрес MCP-сервера будет `<хост>/api/mcp`.
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- Агент читает запросы, имена таблиц и состояние рабочего кластера, а там могут быть данные клиентов
- Без `CHM_API_KEY_SECRET` и без Clerk эндпоинт `/api/mcp` открыт всем, кто его видит в сети
- Панели нужны адрес и пароль пользователя ClickHouse в переменных контейнера
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
chmonitor — панель для ClickHouse, которую запускают одним контейнером против любого доступного кластера: OSS, Altinity или ClickHouse Cloud. Она показывает обзор и топологию, проверки здоровья и больше 30 графиков, выполняющиеся, медленные, упавшие и исторические запросы, размеры таблиц, части, сжатие и TTL. Для реплик есть слияния, мутации, очередь репликации и Keeper. Встроенный совет по запросам разбирает проекции, skip-индексы, PREWHERE и материализованные представления. В терминале работает CLI `chm` с живым интерфейсом и командой `chm doctor`. Для агентов панель открывает MCP-сервер по адресу `/api/mcp`. Он называется clickhouse-monitor, говорит по Streamable HTTP без сессий и выполняет в ClickHouse запросы только на чтение, теми же правами, что и панель. Параметр `hostId` (по умолчанию 0) выбирает хост из `CLICKHOUSE_HOST`. Карточка сервера лежит по адресу `/.well-known/mcp/server-card.json`. Подключаются Claude Desktop, Claude Code, Cursor и любой клиент MCP. Если на сервере задан `CHM_API_KEY_SECRET`, каждый запрос несет токен `chm_`. Его выдает `POST /api/v1/auth/api-key`, срок жизни по умолчанию 30 дней. Браузерные клиенты могут входить через OAuth Clerk, когда включен `CHM_AUTH_PROVIDER=clerk`.
Для кого. Администраторам ClickHouse и инженерам данных, которые хотят спрашивать агента о медленных запросах, отстающих репликах и размерах таблиц.
Подходит, если
- Запрос тормозит, и агент должен найти его среди выполняющихся, медленных и упавших
- Реплики отстают, и надо посмотреть слияния, мутации и очередь репликации
- Таблица разрослась, и нужно оценить размер, части, сжатие и TTL
- Хочется совета по проекциям, skip-индексам и PREWHERE на основе реальных запросов
- Агент должен смотреть сразу несколько хостов ClickHouse через одну панель (параметр `hostId`)
Не подходит, если
- Нужен MCP-сервер без отдельной панели: здесь он живет внутри chmonitor, а напрямую к ClickHouse агента подключает официальный clickhouse-mcp-server
- Требуются записи и DDL: MCP-сервер chmonitor только читает
- Контейнер негде запустить рядом с кластером, а открывать порт кластера наружу нельзя
Пример запроса к агенту
Подключи chmonitor к Claude Code и покажи, какие запросы на хосте 0 сейчас выполняются дольше всехMCP
- Транспорт
- http
- Авторизация
- ключ необязателен
Переменные окружения
CHM_API_KEY_SECRETсекрет- Серверный секрет для выдачи токенов `chm_`. Если не задан, эндпоинт принимает анонимные запросы
Ограничения
- MCP-сервер входит в панель: сначала разверните chmonitor (Docker, Kubernetes или Cloudflare Workers), адрес сервера будет `<ваш-хост>/api/mcp`.
- Без `CHM_API_KEY_SECRET` и без Clerk эндпоинт принимает анонимные запросы, это годится только для доверенной локальной установки.
- Токены `chm_` выдаются запросом на сервере и по умолчанию живут 30 дней, потом нужен новый.
- Доступ ограничен чтением: изменить данные или схему через MCP нельзя.
Как отключить. Команда `claude mcp remove clickhouse-monitor` убирает сервер из Claude Code. В Claude Desktop и Cursor удалите запись `clickhouse-monitor` из файла настроек. Контейнер панели останавливает `docker stop chmonitor`.
Частые вопросы
Как подключить chmonitor к Claude Code?
Командой `claude mcp add --transport http clickhouse-monitor https://<адрес>/api/mcp`. Если на сервере включена авторизация, добавьте `--header "Authorization: Bearer chm_..."`, затем проверьте результат через `claude mcp list`.
Может ли агент менять данные через chmonitor?
Нет. MCP-сервер выполняет только запросы на чтение, как и сама панель.
Как выдать токен MCP-клиенту?
Задайте на сервере `CHM_API_KEY_SECRET`, затем отправьте `POST /api/v1/auth/api-key` с телом `{"label": "my-mcp-client", "days": 30}` и этим секретом в заголовке Authorization. В ответе придет токен с префиксом `chm_`.
Как проверить, что сервер отвечает?
`curl -s https://<адрес>/.well-known/mcp/server-card.json` вернет карточку сервера. Список инструментов отдает запрос `tools/list` на `/api/mcp`.
С какими версиями ClickHouse он работает?
С OSS, Altinity и ClickHouse Cloud: подойдет любой достижимый кластер. Несколько хостов собираются в одну панель, в MCP нужный выбирает параметр `hostId`.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
MCP-серверыОфициальный MCP-сервер ClickHouse: агент смотрит базы и таблицы и выполняет SQL, по умолчанию только на чтение
MCP-сервер на Go для запросов к ClickHouse: схемы, SQL, инструменты из представлений, OAuth и развертывание в Kubernetes
Официальные скиллы ClickHouse: правила схем и запросов, архитектурные решения, chDB для Python и работа с ClickHouse Cloud
Нативный клиент ClickHouse выполняет SQL и выгружает результат для аналитических запросов, подготовленных агентом.
MCP-сервер глобальной аналитики: новости, геополитические риски, рынки и инфраструктура как инструменты для агента
Графовая база с ветвями как в git: сервер отдает ее агентам по MCP на /mcp, а встроенный скилл учит агента схемам, запросам и политикам
Сравнение с похожими
Карточки с тем же главным запросом: чем они отличаются.
| Инструмент | Официальный | Авторизация | Звезды репозитория | Главное отличие |
|---|---|---|---|---|
| chmonitor (эта карточка) | да | ключ необязателен | 304 | |
| ClickHouse MCP Server | нет | API-ключ | 903 | официальный MCP-сервер ClickHouse: смотрит базы и выполняет SQL, а панели мониторинга и совета по индексам у него нет |
| ClickHouse Agent Skills | нет | 564 | официальные скиллы про схемы и запросы, к живому кластеру они не подключаются |
Коротко о README
README показывает, что делает панель, в таблице потребностей: от обзора кластера до совета по индексам и MCP для Claude и Cursor. Быстрый старт состоит из команды `docker run` с тремя переменными подключения и установки CLI `chm`. Дальше идут таблица способов развертывания (Docker, Kubernetes, Cloudflare Workers, Railway, Render, Fly), галерея скриншотов и ссылки на документацию.