ClickHouse MCP Server

Что умеет сервер

Это MCP-сервер ClickHouse, размещённый в организации ClickHouse и опубликованный в PyPI как mcp-clickhouse. Он даёт агенту три инструмента для ClickHouse: run_query для выполнения SQL, list_databases для списка баз и list_tables для списка таблиц выбранной базы с постраничной выдачей и фильтрами по маске имени. Запросам можно передавать значения отдельно от текста через необязательный объект params с плейсхолдерами вида {name:Type}, так что агенту не нужно подставлять значения в SQL самому.

Кроме ClickHouse, сервер поддерживает chDB, встроенный движок ClickHouse: инструмент run_chdb_select_query позволяет выполнять запросы к файлам, адресам и другим источникам без отдельной загрузки данных. Для chDB нужна установка с дополнением mcp-clickhouse[chdb]. Через run_query работают также DESCRIBE (запрос) и EXPLAIN ESTIMATE: первый показывает столбцы результата и ловит ошибки анализа заранее, второй оценивает, сколько частей, строк и меток прочитает запрос.

Когда использовать

Подключайте сервер, когда агент должен анализировать большие таблицы событий, логов или метрик в ClickHouse: изучить схему, написать аналитический запрос, проверить его стоимость до запуска и свести результат. Вариант с chDB удобен для разового анализа файлов без развёртывания отдельного сервера.

Ограничения и безопасность

По умолчанию запросы выполняются только на чтение, и это обеспечивает сам ClickHouse параметром readonly=1. Запись включается переменной CLICKHOUSE_ALLOW_WRITE_ACCESS=true. Опасные операции, такие как DROP, TRUNCATE, DELETE и UPDATE, требуют ещё и CLICKHOUSE_ALLOW_DROP=true. Авторы подчёркивают, что эта проверка работает на стороне MCP-сервера, является защитой от случайностей и не считается границей безопасности. Граница безопасности это права пользователя ClickHouse, поэтому заведите для агента отдельного пользователя с минимальными грантами. Даже в режиме чтения такой пользователь может отменять собственные запросы, в том числе запросы других соединений под тем же именем.

При запуске по HTTP или SSE аутентификация обязательна: статичный токен в CLICKHOUSE_MCP_AUTH_TOKEN, OAuth/OIDC через FastMCP либо явное отключение только для локальной отладки. Без одного из вариантов сервер не стартует. Значения параметров запроса остаются в аргументах инструмента и могут попасть в сообщения об ошибках ClickHouse и в его системные журналы, поэтому не передавайте через них секреты. Поддерживаются версии Python с 3.10 по 3.14, для локального запуска рекомендуется 3.12.

Claude Desktop

Откройте claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%/Claude/claude_desktop_config.json) и добавьте, подставив параметры своего сервиса ClickHouse:

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

Замените uv в строке command на абсолютный путь к исполняемому файлу uv. На macOS его покажет which uv. Затем перезапустите Claude Desktop.

Демонстрационный сервер

Для проверки без своего сервера можно подключиться к публичному ClickHouse SQL Playground:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

chDB (встроенный движок)

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.12",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Без uv

Установка пакета системным Python:

python3 -m pip install mcp-clickhouse

Для поддержки chDB:

python3 -m pip install 'mcp-clickhouse[chdb]'

Теперь в конфигурации клиента можно вызывать установленный скрипт:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "mcp-clickhouse",
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30"
      }
    }
  }
}

Права записи

По умолчанию сервер только читает. Для записи и опасных операций задайте в env:

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}