ClickHouse MCP

ClickHouse/mcp-clickhouse· Проверено 12.11.2026· 904на GitHub

Подключает агента к ClickHouse: посмотреть базы и таблицы, выполнить SQL, оценить объём чтения до запуска. По умолчанию запросы только на чтение.

Как подключить

Что сделать до подключения

Менеджер пакетов uv; Python 3.12 рекомендуется для локального запуска

CLICKHOUSE_HOST

адрес вашего сервера ClickHouse или ClickHouse Cloud

CLICKHOUSE_USER

отдельный пользователь ClickHouse с минимальными правами

CLICKHOUSE_PASSWORD

пароль этого пользователя

CLICKHOUSE_PORT

HTTP-порт: 8443 с TLS или 8123 без него; нативные порты 9000 и 9440 не подходят

Конфиг для вашего клиента

Команда в терминале, в папке проекта. Флаг --scope user подключит сервер для всех проектов. Подробно о Claude Code

claude mcp add --env 'CLICKHOUSE_HOST=<clickhouse-host>' --env 'CLICKHOUSE_USER=<clickhouse-user>' --env 'CLICKHOUSE_PASSWORD=<clickhouse-password>' --env CLICKHOUSE_SECURE=true --transport stdio clickhouse \
  -- uv run --with mcp-clickhouse --python 3.12 mcp-clickhouse

Проверка: claude mcp list показывает статус рядом с каждым сервером: ✔ Connected, ! Needs authentication или ✘ Failed to connect. Внутри сессии то же видно по команде /mcp.

Файл ~/.codex/config.toml или .codex/config.toml в доверенном проекте. Можно и командой codex mcp add. Подробно о Codex

[mcp_servers.clickhouse]
command = "uv"
args = ["run", "--with", "mcp-clickhouse", "--python", "3.12", "mcp-clickhouse"]

[mcp_servers.clickhouse.env]
CLICKHOUSE_HOST = "<clickhouse-host>"
CLICKHOUSE_USER = "<clickhouse-user>"
CLICKHOUSE_PASSWORD = "<clickhouse-password>"
CLICKHOUSE_SECURE = "true"

Проверка: В интерфейсе codex введите /mcp: появится список активных серверов. Из терминала то же покажет codex mcp list.

Файл ~/.cursor/mcp.json для всех проектов или .cursor/mcp.json в папке проекта. Подробно о Cursor

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}

Проверка: Откройте Customize в боковой панели: там список серверов с переключателями. Ошибки подключения смотрите в панели Output (Cmd+Shift+U), пункт MCP Logs в выпадающем списке.

Файл .mcp.json в корне проекта или ~/.copilot/mcp-config.json для всех проектов. Подробно о VS Code

{
  "mcpServers": {
    "clickhouse": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}

Проверка: Попросите Copilot выполнить безобидную задачу через сервер и раскройте вызов инструмента в чате. Одна запись в конфиге подключение не подтверждает.

Файл ~/.qwen/settings.json или .qwen/settings.json в проекте. Подробно о Qwen Code

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}

Проверка: Запустите qwen и введите /mcp: откроется окно управления серверами. Из терминала статус покажет qwen mcp list.

Файл ~/.gemini/settings.json или .gemini/settings.json в проекте. Подробно о Gemini CLI

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}

Проверка: gemini mcp list показывает каждый сервер, его настройки и статус Connected или Disconnected. В сессии /mcp выводит CONNECTED, CONNECTING или DISCONNECTED и список инструментов.

Файл opencode.json в папке проекта или ~/.config/opencode/opencode.json. Подробно о OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "clickhouse": {
        "type": "local",
        "command": [
          "uv",
          "run",
          "--with",
          "mcp-clickhouse",
          "--python",
          "3.12",
          "mcp-clickhouse"
        ],
        "environment": {
          "CLICKHOUSE_HOST": "<clickhouse-host>",
          "CLICKHOUSE_USER": "<clickhouse-user>",
          "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
          "CLICKHOUSE_SECURE": "true"
        }
      }
    }
  }
}

Проверка: opencode mcp list показывает состояние каждого сервера, подключённый выглядит как ✓ context7 connected. Внутри OpenCode то же видно в /mcps.

Настройки → Разработчик → Изменить конфиг: файл claude_desktop_config.json. После правки перезапустите приложение. Подробно о Claude Desktop

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}

Проверка: Нажмите «Add files, connectors, and more /» в левом нижнем углу поля ввода, наведите на Connectors и откройте Manage connectors. Выберите сервер, чтобы увидеть его инструменты.

Вкладка Program → Install → Edit mcp.json. Подробно о LM Studio

{
  "mcpServers": {
    "clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true"
      }
    }
  }
}

Проверка: Попросите модель в чате выполнить задачу через инструмент сервера. Через API сервер из mcp.json вызывают по id в integrations, например mcp/playwright.

Инструменты сервера

run_queryвыполняет SQL-запрос

list_databasesпоказывает базы

list_tablesпоказывает таблицы с колонками

run_chdb_select_queryвыполняет запрос во встроенном chDB

Что попросить агента

«Какие базы и таблицы есть в нашем ClickHouse? Покажи колонки таблицы <events>»Перечислит базы через list_databases и таблицы с колонками через list_tables

«Сколько разных пользователей заходило по дням за последние 30 дней в <events>»Напишет SELECT и выполнит его через run_query

«Прикинь, сколько строк прочитает этот запрос, прежде чем его запускать: <SQL>»Отправит EXPLAIN ESTIMATE через run_query и покажет оценку

«Посчитай средний чек прямо из файла <orders.parquet>»Выполнит запрос во встроенном chDB через run_chdb_select_query

Для каких задач

Ответить на аналитический вопрос готовым SQL-запросом

Оценить через EXPLAIN ESTIMATE объём чтения до запуска тяжёлого запроса

Разобраться в схеме незнакомого кластера: базы, таблицы, колонки

Прочитать файлы и URL без загрузки в базу через встроенный движок chDB

Попробовать сервер на демо-базе ClickHouse SQL Playground без своего кластера

Ограничения

Запись выключена по умолчанию; INSERT и CREATE включаются через CLICKHOUSE_ALLOW_WRITE_ACCESS=true, а DROP, TRUNCATE и DELETE ещё и через CLICKHOUSE_ALLOW_DROP=true

Защита от удаления на стороне сервера MCP не заменяет права: реальную границу задают гранты пользователя ClickHouse

Сервер ходит только в HTTP-интерфейс ClickHouse, нативный протокол clickhouse-client не поддерживается

chDB ставится отдельно: pip install 'mcp-clickhouse[chdb]', на Python 3.15 он не устанавливается

Если не работает

Тяжёлые запросы падают с «Query timed out after ...»

Увеличьте CLICKHOUSE_MCP_QUERY_TIMEOUT, по умолчанию 30 секунд.

Сервер не соединяется с ClickHouse на порту 9000 или 9440

Эти порты для нативного протокола clickhouse-client; в CLICKHOUSE_PORT укажите HTTP-порт, по умолчанию 8123 или 8443.

INSERT, CREATE и ALTER отклоняются

По умолчанию запросы только на чтение: задайте CLICKHOUSE_ALLOW_WRITE_ACCESS=true; для DROP, TRUNCATE, DELETE и UPDATE нужен ещё CLICKHOUSE_ALLOW_DROP=true.

Сервер с транспортом http или sse не стартует

Для этих транспортов нужна авторизация: задайте CLICKHOUSE_MCP_AUTH_TOKEN, OAuth через FASTMCP_SERVER_AUTH или для локальной разработки CLICKHOUSE_MCP_AUTH_DISABLED=true.

Частые вопросы

Как попробовать без своей базы?

Укажите CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com, порт 8443, пользователя demo с пустым паролем и CLICKHOUSE_SECURE=true. Это публичный ClickHouse SQL Playground.

Можно ли разрешить агенту запись?

Да: CLICKHOUSE_ALLOW_WRITE_ACCESS=true разрешает INSERT, CREATE и ALTER ADD COLUMN. Для удаления нужен ещё CLICKHOUSE_ALLOW_DROP=true. Заведите для агента отдельного пользователя только с нужными грантами.

Как использовать только chDB без кластера?

Задайте CHDB_ENABLED=true и CLICKHOUSE_ENABLED=false. chDB по умолчанию работает в памяти, папку хранения задаёт CHDB_DATA_PATH.

Работает ли сервер с ClickHouse Cloud?

Да, через логин и пароль в CLICKHOUSE_USER и CLICKHOUSE_PASSWORD с CLICKHOUSE_SECURE=true. Вход по клиентскому сертификату X.509 ClickHouse Cloud не поддерживает.

Работает ли сервер из России?

Сервер запускается на вашем компьютере и подключается к тому ClickHouse, адрес которого вы указали; ключи сторонних сервисов не нужны.