ClickHouse

официальный

Запросы к вашему серверу базы данных ClickHouse.

GitHub

839

Что можно делать с Click House MCP?

Выполнение read-only SQL-запросов — Попросите ассистента выполнить любой SELECT запрос к вашему кластеру ClickHouse с помощью run_query.
Список баз данных и таблиц — Исследуйте схему, перечисляя все базы данных с помощью list_databases или пролистывая таблицы в конкретной базе данных с помощью list_tables.
Запросы к файлам и URL напрямую через chDB — Используйте run_chdb_select_query для выполнения SQL к локальным файлам или удаленным источникам данных без предварительной загрузки в ClickHouse.
Контроль операций записи и деструктивных операций — Включите CLICKHOUSE_ALLOW_WRITE_ACCESS для DDL/DML и опционально CLICKHOUSE_ALLOW_DROP, чтобы разрешить операторы DROP или TRUNCATE во время сессий с AI-ассистентом.

Документация

ClickHouse MCP Server

MCP-сервер для ClickHouse.

Возможности

Инструменты ClickHouse

run_query
- Выполнение SQL-запросов к вашему кластеру ClickHouse.
- Входные данные: query (строка): SQL-запрос для выполнения.
- По умолчанию запросы выполняются в режиме только для чтения (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), но при необходимости запись можно включить явно.
list_databases
- Вывод списка всех баз данных в вашем кластере ClickHouse.
list_tables
- Вывод списка таблиц в базе данных с постраничной навигацией.
- Обязательный ввод: database (строка).
- Необязательные входные данные:
  - like / not_like (строка): Применение фильтров LIKE или NOT LIKE к именам таблиц.
  - page_token (строка): Токен, возвращенный предыдущим вызовом для получения следующей страницы.
  - page_size (целое число, по умолчанию 50): Количество таблиц, возвращаемых на странице.
  - include_detailed_columns (логическое, по умолчанию true): Если false, исключает метаданные столбцов для облегченных ответов, сохраняя при этом полный create_table_query.
- Формат ответа:
  - tables: Массив объектов таблиц для текущей страницы.
  - next_page_token: Передайте это значение обратно для получения следующей страницы или null, если таблиц больше нет.
  - total_tables: Общее количество таблиц, соответствующих примененным фильтрам.

Инструменты chDB

run_chdb_select_query
- Выполнение SQL-запросов с использованием встроенного движка ClickHouse chDB.
- Входные данные: query (строка): SQL-запрос для выполнения.
- Запрос данных напрямую из различных источников (файлы, URL-адреса, базы данных) без процессов ETL.
- Требуется дополнительный пакет chdb: pip install 'mcp-clickhouse[chdb]'

Конечная точка проверки работоспособности

При работе с транспортом HTTP или SSE конечная точка проверки работоспособности доступна по адресу /health. Эта конечная точка:

Возвращает 200 OK (тело: OK), если сервер работоспособен и может подключиться к ClickHouse
Возвращает 503 Service Unavailable с общим сообщением об ошибке, если сервер не может подключиться к ClickHouse

Конечная точка намеренно не аутентифицирована, чтобы проверки оркестратора (например, проверки живучести/готовности Kubernetes, балансировщики нагрузки) могли обращаться к ней без учетных данных. Тело ответа намеренно минимально, чтобы избежать утечки строк версий бэкенда или деталей ошибок; отлаживайте сбои через журналы сервера.

Пример:

curl http://localhost:8000/health
# Response: OK

Безопасность

Аутентификация для транспорта HTTP/SSE

При использовании транспорта HTTP или SSE аутентификация обязательна по умолчанию. Транспорт stdio (по умолчанию) не требует аутентификации, так как он взаимодействует только через стандартный ввод/вывод.

Поддерживаются три режима аутентификации. Выберите один:

Режим	Когда использовать	Переменная окружения
Статический токен носителя	Простые развертывания, внутренние сервисы	`CLICKHOUSE_MCP_AUTH_TOKEN`
OAuth / OIDC (через FastMCP)	Azure Entra, Google, GitHub, WorkOS и т.д.	`FASTMCP_SERVER_AUTH=<provider-class-path>` (+ переменные `FASTMCP_SERVER_AUTH_*`, специфичные для провайдера)
Отключено	Только для локальной разработки	`CLICKHOUSE_MCP_AUTH_DISABLED=true`

Запуск завершится ошибкой, если ни один из них не настроен для транспорта HTTP/SSE.

Настройка аутентификации

Сгенерируйте безопасный токен (может быть любой случайной строкой):
```
# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32
```
Настройте сервер с этим токеном:
```
export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"
```
Настройте ваш MCP-клиент на включение токена в запросы:

Для Claude Desktop с транспортом HTTP/SSE:
```
{
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}
```
Примечание: конечная точка /health намеренно не аутентифицирована (см. Конечная точка проверки работоспособности выше). Чтобы убедиться, что аутентификация по токену носителя действительно отклоняет неаутентифицированные запросы, обратитесь к самой конечной точке MCP, например, с помощью MCP Inspector, или отправив POST-запрос JSON-RPC на /mcp с заголовком Authorization и без него, и подтвердив, что неаутентифицированный вызов возвращает 401.

OAuth / OIDC через FastMCP

Для производственных развертываний с поставщиками удостоверений (Azure Entra, Google, GitHub, WorkOS и т.д.) делегируйте аутентификацию встроенным провайдерам аутентификации FastMCP вместо использования статического токена. Установите FASTMCP_SERVER_AUTH в полный путь к классу провайдера аутентификации FastMCP вместе с переменными FASTMCP_SERVER_AUTH_*, специфичными для провайдера, и оставьте CLICKHOUSE_MCP_AUTH_TOKEN неустановленным.

Пример (Azure Entra):

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"

См. документацию FastMCP для получения полного списка провайдеров и необходимых им переменных окружения.

Режим разработки (Отключение аутентификации)

Только для локальной разработки и тестирования вы можете отключить аутентификацию, установив:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

ПРЕДУПРЕЖДЕНИЕ: Используйте это только для локальной разработки. Не отключайте аутентификацию, если сервер доступен из какой-либо сети.

Конфигурация

Этот MCP-сервер поддерживает как ClickHouse, так и chDB. Вы можете включить любой из них или оба в зависимости от ваших потребностей.

Откройте файл конфигурации Claude Desktop, расположенный по адресу:
- В macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- В Windows: %APPDATA%/Claude/claude_desktop_config.json
Добавьте следующее:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Обновите переменные окружения, чтобы они указывали на ваш собственный сервис ClickHouse.

Или, если вы хотите попробовать его с ClickHouse SQL Playground, вы можете использовать следующую конфигурацию:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Для chDB (встроенный движок ClickHouse) добавьте следующую конфигурацию:

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

Вы также можете одновременно включить и ClickHouse, и chDB:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

Найдите запись команды для uv и замените ее абсолютным путем к исполняемому файлу uv. Это гарантирует, что при запуске сервера будет использоваться правильная версия uv. На Mac вы можете найти этот путь с помощью which uv.
Перезапустите Claude Desktop, чтобы применить изменения.

Дополнительный доступ на запись

По умолчанию этот MCP-сервер принудительно выполняет запросы только для чтения, чтобы случайные изменения не могли произойти во время исследования. Чтобы разрешить операторы DDL или INSERT/UPDATE, установите переменную окружения CLICKHOUSE_ALLOW_WRITE_ACCESS в значение true. Сервер продолжит принудительно использовать режим только для чтения, если сам экземпляр ClickHouse запрещает запись.

Защита от деструктивных операций

Даже если доступ на запись включен (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), деструктивные операции (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) требуют дополнительного флага согласия для безопасности. Это предотвращает случайное удаление данных во время исследования ИИ.

Чтобы включить деструктивные операции, установите оба флага:

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

Этот двухуровневый подход гарантирует, что случайное удаление крайне маловероятно:

Операции записи (INSERT, UPDATE, CREATE) требуют CLICKHOUSE_ALLOW_WRITE_ACCESS=true
Деструктивные операции (DROP, TRUNCATE) дополнительно требуют CLICKHOUSE_ALLOW_DROP=true

Запуск без uv (с использованием системного Python)

Если вы предпочитаете использовать системную установку Python вместо uv, вы можете установить пакет из PyPI и запустить его напрямую:

Установите пакет с помощью pip:
```
python3 -m pip install mcp-clickhouse
```
Чтобы также установить поддержку chDB:
```
python3 -m pip install 'mcp-clickhouse[chdb]'
```
Чтобы обновить до последней версии:
```
python3 -m pip install --upgrade mcp-clickhouse
```
Обновите конфигурацию Claude Desktop для использования Python напрямую:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

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

{
  "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",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

Примечание: Обязательно используйте полный путь к исполняемому файлу Python или скрипту mcp-clickhouse, если они отсутствуют в вашем системном PATH. Вы можете найти пути с помощью:

which python3 для исполняемого файла Python
which mcp-clickhouse для установленного скрипта

Пользовательское промежуточное ПО

Вы можете добавить пользовательское промежуточное ПО на MCP-сервер без изменения исходного кода. FastMCP предоставляет систему промежуточного ПО, которая позволяет перехватывать и обрабатывать сообщения протокола MCP (вызовы инструментов, чтение ресурсов, подсказки и т.д.).

Как использовать

Создайте модуль Python с классами промежуточного ПО, расширяющими Middleware, и функцией setup_middleware(mcp):

# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())

Установите переменную окружения MCP_MIDDLEWARE_MODULE в имя модуля (без расширения .py):

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

Убедитесь, что ваш модуль промежуточного ПО находится в пути импорта Python (например, в том же каталоге, где работает MCP-сервер, или установлен как пакет).

Пример промежуточного ПО

Пример модуля промежуточного ПО находится в example_middleware.py и демонстрирует общие шаблоны:

Ведение журнала всех MCP-запросов
Ведение журнала конкретно вызовов инструментов
Измерение времени обработки запроса

Чтобы использовать пример:

"env": {
  "MCP_MIDDLEWARE_MODULE": "example_middleware"
}

Возможности промежуточного ПО

Базовый класс Middleware предоставляет хуки для различных операций MCP:

on_message(context, call_next) - Вызывается для всех сообщений
on_request(context, call_next) - Вызывается для всех запросов
on_notification(context, call_next) - Вызывается для всех уведомлений
on_call_tool(context, call_next) - Вызывается при выполнении инструмента
on_read_resource(context, call_next) - Вызывается при чтении ресурса
on_get_prompt(context, call_next) - Вызывается при получении подсказки
on_list_tools(context, call_next) - Вызывается при выводе списка инструментов
on_list_resources(context, call_next) - Вызывается при выводе списка ресурсов
on_list_resource_templates(context, call_next) - Вызывается при выводе списка шаблонов ресурсов
on_list_prompts(context, call_next) - Вызывается при выводе списка подсказок

Каждый хук получает объект MiddlewareContext, содержащий сообщение и метаданные, и функцию call_next для продолжения конвейера.

Динамическая конфигурация клиента через состояние контекста

Промежуточное ПО может переопределять конфигурацию клиента ClickHouse для каждого запроса, используя ключ состояния контекста CLIENT_CONFIG_OVERRIDES_KEY. Сервер объединяет эти переопределения с базовой конфигурацией из переменных окружения.

from fastmcp.server.dependencies import get_context
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

Это позволяет реализовать расширенные сценарии использования, такие как динамическая настройка тайм-аутов, маршрутизация для конкретных арендаторов или настройки подключения для отдельных пользователей.

Разработка

В каталоге test-services выполните docker compose up -d, чтобы запустить кластер ClickHouse.
Добавьте следующие переменные в файл .env в корне репозитория.

Примечание: Использование пользователя default в данном контексте предназначено исключительно для целей локальной разработки.

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

Выполните uv sync, чтобы установить зависимости. Чтобы установить uv, следуйте инструкциям здесь. Затем выполните source .venv/bin/activate.
Для удобного тестирования с помощью MCP Inspector выполните fastmcp dev mcp_clickhouse/mcp_server.py, чтобы запустить MCP-сервер.

Для тестирования с транспортом HTTP и конечной точкой проверки работоспособности:

# For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main

# Or with authentication (generate a token first)
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main

# Then in another terminal:
curl http://localhost:8000/health

Переменные окружения

Конфигурация разделена на независимые группы. Их смешивание является частой причиной трудно отлаживаемых сбоев подключения:

Группа	Переменные	Управляет
Подключение к базе данных ClickHouse	`CLICKHOUSE_HOST`, `CLICKHOUSE_PORT`, `CLICKHOUSE_SECURE`, `CLICKHOUSE_VERIFY`, …	Как этот MCP-сервер подключается к вашему кластеру ClickHouse через интерфейс HTTP
MCP-сервер / транспорт	`CLICKHOUSE_MCP_`, `FASTMCP_SERVER_AUTH`, `FASTMCP_SERVER_AUTH_`	Транспорт MCP, аутентификация и ограничения выполнения инструментов запросов
Промежуточное ПО / chDB	`MCP_MIDDLEWARE_MODULE`, `CHDB_*`	Дополнительные расширения

[!IMPORTANT] Такие переменные, как CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY и CLICKHOUSE_PORT, применяются только к подключению к базе данных ClickHouse. Они не настраивают TLS, порты или аутентификацию для конечной точки протокола MCP.

Пример: если MCP-сервер работает в Kubernetes за входным контроллером, который терминирует TLS, это проблема транспорта MCP. Держите CLICKHOUSE_SECURE в соответствии с тем, как под обращается к самому ClickHouse (HTTPS → true, простой HTTP → false). Установка CLICKHOUSE_SECURE=false из-за того, что MCP-сервер находится за входным контроллером, заставит сервер обращаться к ClickHouse по HTTP — часто к порту, предназначенному только для HTTPS — и приведет к неясным ошибкам HTTP/TLS в журналах сервера.

Подключение к базе данных ClickHouse

Эти переменные настраивают HTTP-клиент clickhouse-connect и поведение инструментов, работающих с ClickHouse, таких как run_query, list_databases и list_tables.

Обязательные переменные

CLICKHOUSE_HOST: Имя хоста вашего сервера ClickHouse (конечная точка базы данных, а не адрес привязки MCP-сервера)
CLICKHOUSE_USER: Имя пользователя для аутентификации в ClickHouse
CLICKHOUSE_PASSWORD: Пароль для аутентификации в ClickHouse

[!CAUTION] Важно относиться к пользователю базы данных MCP так же, как к любому внешнему клиенту, подключающемуся к вашей базе данных, предоставляя только минимально необходимые для его работы привилегии. Использование пользователей по умолчанию или административных пользователей следует строго избегать во всех случаях.

Необязательные переменные

CLICKHOUSE_PORT: Порт HTTP-интерфейса вашего сервера ClickHouse
- По умолчанию: 8443, если CLICKHOUSE_SECURE=true, 8123, если CLICKHOUSE_SECURE=false
- Обычно не требует установки, если не используется нестандартный порт
- Должен быть портом HTTP-интерфейса, а не портом нативного протокола TCP, используемого clickhouse-client
- Распространенные значения:
  - HTTP: 8123 (обычный) / 8443 (TLS) — используется этим сервером и ClickHouse Cloud HTTPS
  - Нативный TCP (здесь не поддерживается): 9000 (обычный) / 9440 (TLS) — используется clickhouse-client
- Если сервер отвечает Port 9000 is for clickhouse-client program, вы подключены к нативному протоколу; переключитесь на HTTP-порт (8123/8443 или HTTP-сопоставление вашего развертывания)
CLICKHOUSE_ROLE: Роль ClickHouse для аутентификации
- По умолчанию: Нет
- Установите, если вашему пользователю требуется определенная роль
CLICKHOUSE_SECURE: Включить HTTPS для подключения к базе данных ClickHouse (не для MCP-клиентов)
- По умолчанию: "true"
- Установите в "false" только тогда, когда MCP-сервер подключается к ClickHouse по обычному HTTP (характерно для локального Docker Compose на порту 8123)
- Оставьте "true" для ClickHouse Cloud и любых конечных точек базы данных HTTPS — даже если сам MCP-сервер доступен через HTTP, stdio или ingress, который терминирует TLS отдельно
- Несоответствие этого флага порту базы данных (например, CLICKHOUSE_SECURE=false для порта 8443) — частая ошибка настройки, которая обычно проявляется в виде запутанных ошибок HTTP-клиента, а не четкого сообщения «неверная схема»
CLICKHOUSE_VERIFY: Включить/отключить проверку SSL-сертификата для HTTPS-подключения к ClickHouse
- По умолчанию: "true"
- Установите в "false", чтобы отключить проверку сертификата (не рекомендуется для production)
- TLS-сертификаты: Пакет использует хранилище доверенных сертификатов вашей операционной системы для проверки TLS-сертификатов через truststore. Мы вызываем truststore.inject_into_ssl() при запуске, чтобы обеспечить корректную обработку сертификатов. Стандартное поведение SSL в Python используется в качестве запасного варианта только в случае непредвиденной ошибки.
CLICKHOUSE_SERVER_HOST_NAME: Имя хоста сервера для переопределения SNI и проверки сертификата при подключении к ClickHouse
- По умолчанию: Нет (используется имя хоста подключения)
- Это полезно при подключении через прокси или балансировщики нагрузки, где имя хоста сертификата отличается от имени хоста подключения. При установке это имя хоста будет использоваться как для SNI (Server Name Indication) во время рукопожатия TLS, так и для проверки имени хоста сертификата.
CLICKHOUSE_PROXY_PATH: Префикс URL-пути для конечной точки HTTP ClickHouse
- По умолчанию: Нет
- Установите, когда HTTP-интерфейс ClickHouse доступен за обратным прокси с префиксом пути (например, /clickhouse)
CLICKHOUSE_CONNECT_TIMEOUT: Тайм-аут подключения в секундах для клиента ClickHouse
- По умолчанию: "30"
- Увеличьте это значение, если возникают тайм-ауты подключения
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Тайм-аут отправки/получения в секундах для клиента ClickHouse
- По умолчанию: "300"
- Увеличьте это значение для долго выполняющихся запросов
CLICKHOUSE_DATABASE: База данных ClickHouse по умолчанию
- По умолчанию: Нет (используется серверная по умолчанию)
- Установите для автоматического подключения к определенной базе данных
CLICKHOUSE_ENABLED: Включить/отключить инструменты базы данных ClickHouse
- По умолчанию: "true"
- Установите в "false", чтобы отключить инструменты ClickHouse при использовании только chDB
CLICKHOUSE_ALLOW_WRITE_ACCESS: Разрешить операции записи (DDL и DML) в ClickHouse
- По умолчанию: "false"
- Установите в "true", чтобы разрешить операции DDL (CREATE, ALTER, DROP) и DML (INSERT, UPDATE, DELETE)
- При отключении (по умолчанию) запросы выполняются с настройкой readonly=1 для предотвращения модификации данных
CLICKHOUSE_ALLOW_DROP: Разрешить деструктивные операции (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
- По умолчанию: "false"
- Действует только при установленном CLICKHOUSE_ALLOW_WRITE_ACCESS=true
- Установите в "true", чтобы явно разрешить деструктивные операции DROP и TRUNCATE
- Это функция безопасности для предотвращения случайного удаления данных при исследовании ИИ

MCP-сервер и транспорт

Эти переменные управляют самим процессом MCP, включая транспорт, аутентификацию и ограничения выполнения инструментов запросов. Они не зависят от настроек базы данных ClickHouse, описанных выше. См. также Аутентификация для транспортов HTTP/SSE.

CLICKHOUSE_MCP_SERVER_TRANSPORT: Устанавливает метод транспорта для MCP-сервера
- По умолчанию: "stdio"
- Допустимые варианты: "stdio", "http", "sse". Это полезно для локальной разработки с такими инструментами, как MCP Inspector.
- stdio типичен для Claude Desktop; http/sse открывают сетевой прослушиватель (хост/порт привязки ниже)
CLICKHOUSE_MCP_BIND_HOST: Хост для привязки MCP-сервера при использовании транспорта HTTP или SSE
- По умолчанию: "127.0.0.1"
- Установите в "0.0.0.0" для привязки ко всем сетевым интерфейсам (полезно для Docker или удаленного доступа)
- Используется только при транспорте "http" или "sse" — не связано с CLICKHOUSE_HOST
CLICKHOUSE_MCP_BIND_PORT: Порт для привязки MCP-сервера при использовании транспорта HTTP или SSE
- По умолчанию: "8000"
- Используется только при транспорте "http" или "sse" — не связано с CLICKHOUSE_PORT
CLICKHOUSE_MCP_QUERY_TIMEOUT: Тайм-аут в секундах для инструментов запросов
- По умолчанию: "30"
- Увеличьте, если видите ошибки Query timed out after ... для тяжелых запросов
CLICKHOUSE_MCP_AUTH_TOKEN: Статический токен-носитель для транспортов HTTP/SSE
- По умолчанию: Нет
- Один из CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH или CLICKHOUSE_MCP_AUTH_DISABLED=true обязателен для транспортов HTTP/SSE
- Сгенерируйте с помощью uuidgen или openssl rand -hex 32
- Клиенты должны отправлять этот токен в заголовке Authorization: Bearer <token>
FASTMCP_SERVER_AUTH: Делегировать аутентификацию провайдеру аутентификации FastMCP
- По умолчанию: Нет
- Значение — полный путь к классу подкласса AuthProvider, например, fastmcp.server.auth.providers.azure.AzureProvider или fastmcp.server.auth.providers.google.GoogleProvider
- При установке FastMCP автоматически загружает провайдера из собственных переменных окружения FASTMCP_SERVER_AUTH_*; оставьте CLICKHOUSE_MCP_AUTH_TOKEN неустановленным в этом режиме
CLICKHOUSE_MCP_AUTH_DISABLED: Отключить аутентификацию для транспортов HTTP/SSE
- По умолчанию: "false" (аутентификация включена)
- Установите в "true", чтобы отключить аутентификацию только для локальной разработки/тестирования
- ПРЕДУПРЕЖДЕНИЕ: Используйте только для локальной разработки. Не отключайте при доступе к сетям

Переменные промежуточного ПО

MCP_MIDDLEWARE_MODULE: Имя модуля Python, содержащего пользовательское промежуточное ПО для внедрения в MCP-сервер
- По умолчанию: Нет (промежуточное ПО не загружается)
- Установите имя модуля (без расширения .py) вашего модуля промежуточного ПО
- Модуль должен предоставлять функцию setup_middleware(mcp)
- Подробности и примеры см. в разделе Пользовательское промежуточное ПО

Переменные chDB

CHDB_ENABLED: Включить/отключить функциональность chDB
- По умолчанию: "false"
- Установите в "true", чтобы включить инструменты chDB
- Требуется установка дополнительного пакета: mcp-clickhouse[chdb]
CHDB_DATA_PATH: Путь к каталогу данных chDB
- По умолчанию: ":memory:" (база данных в памяти)
- Используйте :memory: для базы данных в памяти
- Используйте путь к файлу для постоянного хранилища (например, /path/to/chdb/data)

Распространенные ошибки конфигурации

CLICKHOUSE_SECURE против MCP / ingress TLS — Отключение CLICKHOUSE_SECURE из-за того, что MCP-сервер находится за ingress Kubernetes, обратным прокси или доступен по обычному HTTP, не отключает TLS базы данных; это только меняет способ подключения этого процесса к ClickHouse. Настройте ingress TLS отдельно от настроек клиента базы данных.
Порты нативного протокола — CLICKHOUSE_PORT должен быть нацелен на HTTP-интерфейс ClickHouse (8123/8443 по умолчанию). Порты 9000/9440 предназначены для нативного протокола TCP (clickhouse-client) и не будут работать с этим сервером.
Путаница с хостами — CLICKHOUSE_HOST — это имя хоста базы данных. CLICKHOUSE_MCP_BIND_HOST — это только адрес, который прослушивает MCP HTTP/SSE сервер.

Примеры конфигураций

Для локальной разработки с Docker:

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

Для ClickHouse Cloud:

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

Для ClickHouse SQL Playground:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

Только для chDB (в памяти):

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH defaults to :memory:

Для chDB с постоянным хранилищем:

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
CHDB_DATA_PATH=/path/to/chdb/data

Для MCP Inspector или удаленного доступа с транспортом HTTP:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)

Для локальной разработки с транспортом HTTP (аутентификация отключена):

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!

При использовании транспорта HTTP сервер будет работать на настроенном порту (по умолчанию 8000). Например, с указанной выше конфигурацией:

Конечная точка MCP: http://localhost:4200/mcp
Проверка работоспособности: http://localhost:4200/health

Вы можете установить эти переменные в вашем окружении, в файле .env или в конфигурации Claude Desktop:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
        "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
        "CLICKHOUSE_MCP_BIND_PORT": "8000"
      }
    }
  }
}

Примечание: Настройки хоста и порта привязки используются только при установке транспорта в "http" или "sse".

Запуск тестов

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only