Сервер MCP для ClickHouse

Сервер MCP для ClickHouse.

Особенности

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

run_query

Выполняет SQL-запросы в вашем кластере ClickHouse.

Ввод: query (строка): SQL-запрос для выполнения.
Запросы по умолчанию выполняются в режиме только для чтения (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), но запись можно явно включить при необходимости.
list_databases

Перечислить все базы данных в вашем кластере ClickHouse.

Ввод: database (строка).
Необязательные параметры:

like / not_like (строка): фильтры на имена таблиц с использованием LIKE или NOT LIKE.

page_token (строка): токен, возвращённый предыдущим вызовом, для получения следующей страницы.
page_size (int, по умолчанию 50): количество таблиц на странице.
include_detailed_columns (bool, по умолчанию true): если false, пропускает метаданные столбцов для более лёгкого ответа, сохраняя при этом полный create_table_query.
Формат ответа:

tables: массив объектов таблиц на текущей странице.

next_page_token: передайте это значение обратно для получения следующей страницы, или null, если таблиц больше нет.
total_tables: общее количество таблиц, удовлетворяющих заданным фильтрам.

chDB Tools

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 liveness/readiness, балансировщики нагрузки) могли достигать его без учётных данных. Тело ответа минималистично, чтобы не сообщать версию бэкенда или детали ошибок; для диагностики используйте логи сервера.

Пример:

curl http://localhost:8000/health
# Ответ: OK

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

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

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

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

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

При запуске не должны быть задействованы более одного метода аутентификации для HTTP/SSE транспорта.

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

Сгенерируйте безопасный токен (может быть любым случайным набором):

# Использование uuidgen (macOS/Linux)
uuidgen

# Использование openssl
openssl rand -hex 32

Настройте сервер с токеном:

export CLICKHOUSE_MCP_AUTH_TOKEN="ваш-сгенерированный-токен"

Настройте клиента MCP так, чтобы токен отправлялся в запросах:

Для Claude Desktop с HTTP/SSE-транспортом:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer ваш-сгенерированный-токен"
      }
    }
  }
}

Примечание: эндпойнт /health намеренно не требует аутентификации (см. выше раздел Health Check Endpoint). Чтобы проверить, действительно ли авторизацияBearer-token отбрасывает неавторизованные запросы, попробуйте обратиться к MCP-эндпойнту самим (например, через MCP Inspector) или отправить 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_AZURE_CLIENT_ID=""
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET=""
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"
      }
    }
  }
}

Можно также запускать оба варианта одновременно:

{
  "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_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 при запуске сервера. На macOS путь можно узнать командой 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 и запускать напрямую:

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

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 — путь к установленному скрипту

Пользовательский middleware

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

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

Создайте Python-модуль с классами middleware, наследующимися от 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):
    """Логирование всех вызовов инструментов."""

    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"Вызов инструмента: {tool_name}")
        result = await call_next(context)
        logger.info(f"Инструмент {tool_name} завершил работу")
        return result

def setup_middleware(mcp):
    """Зарегистрировать middleware в MCP-сервере."""
    mcp.add_middleware(LoggingMiddleware())

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

"env": {
  "MCP_MIDDLEWARE_MODULE": "my_middleware"
}

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

Пример middleware

В файле example_middleware.py приведён пример модуля middleware, демонстрирующий распространённые паттерны:

Логирование всех запросов MCP
Логирование вызовов инструментов
Замер времени обработки запроса

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

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

Возможности 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 для продолжения конвейера.

Динамическая настройка клиента через состояние контекста

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

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-транспорт и эндпойнт проверки работоспособности:

# Для разработки отключить аутентификацию
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main

# Или с аутентификацией (сначала сгенерируйте токен)
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="ваш-токен" python -m mcp_clickhouse.main

# Затем в другом терминале:
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, аутентификация и лимиты на выполнение инструментов
Middleware / chDB	MCP_MIDDLEWARE_MODULE, CHDB_*	Опциональные расширения

Важно

Переменные вроде CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY и CLICKHOUSE_PORT относятся к соединению с базой ClickHouse и не конфигурируют TLS, порты или аутентификацию MCP-протокола.

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

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

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

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

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

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

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

CLICKHOUSE_PORT: Порт HTTP-интерфейса вашего ClickHouse

По умолчанию: 8443, если CLICKHOUSE_SECURE=true, 8123 если CLICKHOUSE_SECURE=false

Обычно не требуется указывать, если используете нестандартный порт
Должен быть HTTP-порт, а не TCP-порт, который используется clickhouse-client
Распространённые значения:

HTTP: 8123 (без TLS) / 8443 (с TLS)

Нативный TCP-порт (не поддерживается здесь): 9000 / 9440
Если сервер отвечает "Port 9000 is for clickhouse-client program", значит вы попали на нативный протокол; переключитесь на HTTP-порт
CLICKHOUSE_ROLE: Роль ClickHouse для аутентификации

По умолчанию: нет

Укажите, если нужна конкретная роль
CLICKHOUSE_SECURE: Включить HTTPS для соединения с ClickHouse (а не для MCP-клиентов)

По умолчанию: "true"

Установите в "false" только если MCP-сервер обращается к ClickHouse по HTTP без TLS
Оставляйте "true" для ClickHouse Cloud и любых HTTPS-эндпойнтов базы, даже если MCP-сервер доступен по HTTP, stdio или через ingress, который завершает TLS отдельно
Несоответствие этому флагу порта базы (например, CLICKHOUSE_SECURE=false на порту 8443) приводит к частым ошибкам и непонятным сообщениям об ошибке
CLICKHOUSE_VERIFY: Включить/отключить проверку SSL-сертификатов для HTTPS-соединения с ClickHouse

По умолчанию: "true"

Установите в "false", чтобы отключить проверку сертификатов (не рекомендуется в продакшене)
TLS-сертификаты: пакет использует системный trust store для верификации TLS через truststore. Мы вызываем truststore.inject_into_ssl() при старте, чтобы корректно обрабатывать сертификаты. В качестве запасного варианта используется поведение SSL по умолчанию Python, если возникает непредвиденная ошибка.
CLICKHOUSE_SERVER_HOST_NAME: Имя сервера для переопределения SNI и проверки сертификата на соединении с ClickHouse

По умолчанию: отсутствует (используется имя хоста подключения)

Это полезно, когда вы подключаетесь через прокси или балансировщик нагрузки, где имя сертификата отличается от имени подключения. Если задать, это имя будет использоваться и для SNI, и для проверки соответствия имени сертификата.
CLICKHOUSE_PROXY_PATH: префикс пути URL для HTTP-интерфейса ClickHouse

По умолчанию: отсутствует

Устанавливайте, если HTTP-интерфейс ClickHouse выступает за прокси с префиксом пути (например, /clickhouse)
CLICKHOUSE_CONNECT_TIMEOUT: тайм-аут соединения в секундах для клиента ClickHouse

По умолчанию: "30"

Увеличивайте при возникновении тайм-аутов
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: тайм-аут отправки/получения для клиента ClickHouse

По умолчанию: "300"

Увеличивайте для длительных запросов
CLICKHOUSE_DATABASE: База данных по умолчанию для использования

По умолчанию: None (используется база сервера по умолчанию)

Установите, чтобы автоматически подключаться к определённой базе данных
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.

CLICKHOUSE_MCP_SERVER_TRANSPORT: Устанавливает транспорт MCP-сервера

По умолчанию: "stdio"

Допустимые значения: "stdio", "http", "sse"
stdio типично для Claude Desktop; http/sse открывают сетевой слушатель (bind-хост/порт ниже)
CLICKHOUSE_MCP_BIND_HOST: Хост, на котором bind 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_MCP_QUERY_TIMEOUT: Тайм-аут запросов для инструментов

По умолчанию: "30"

Увеличивайте при длительных запросах
CLICKHOUSE_MCP_AUTH_TOKEN: Статический Bearer-токен для 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

По умолчанию: отсутствует

Значение — полный путь к классу провайдера аутентификации, например 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" для отключения аутентификации только для локальной разработки/тестирования
ВНИМАНИЕ: используйте только для локальной разработки. Не отключайте аутентификацию в сетевых окружениях

Переменные middleware

MCP_MIDDLEWARE_MODULE: Имя Python-модуля, содержащего ваш собственный middleware для внедрения в MCP-сервер

По умолчанию: нет ( middleware не загружен)

Укажите имя модуля (без .py), например my_middleware
Модуль должен предоставлять функцию setup_middleware(mcp)
См. раздел Custom Middleware для деталей и примеров

Переменные chDB

CHDB_ENABLED: Включить/выключить функциональность chDB

По умолчанию: "false"

Установите в "true", чтобы включить инструменты chDB
Требуется установка дополнительного пакета: mcp-clickhouse[chdb]
CHDB_DATA_PATH: Путь к директории данных chDB

По умолчанию: ":memory:" (в память)

Используйте :memory: для работы в памяти
Используйте путь к файлу для постоянного хранения (например, /path/to/chdb/data)

Общие подводные камни конфигурации

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

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

Локальная разработка с Docker:

# Обязательные переменные
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# По желанию: переопределение настроек для локальной разработки
CLICKHOUSE_SECURE=false  # по умолчанию использует порт 8123
CLICKHOUSE_VERIFY=false

Для ClickHouse Cloud:

# Обязательные переменные
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# По желанию: безопасные значения по умолчанию
# CLICKHOUSE_SECURE=true  # использует порт 8443
# CLICKHOUSE_DATABASE=your_database

Для ClickHouse SQL Playground:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# По умолчанию используется безопасное соединение (HTTPS на порту 8443)

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

# конфигурация chDB
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH по умолчанию :memory:

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

# конфигурация chDB
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  # Привязка ко всем интерфейсам
CLICKHOUSE_MCP_BIND_PORT=4200  # Пользовательский порт (по умолчанию: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # Один режим аутентификации для HTTP/SSE
# или FASTMCP_SERVER_AUTH, или 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  # Только для локальной разработки!

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

MCP-ендпойнт: http://localhost:4200/mcp
Health: http://localhost:4200/health

Задавайте эти переменные через окружение, в файле .env или в конфигурации Claude Desktop:

CLICKHOUSE_HOST=<адрес>
CLICKHOUSE_USER=<пользователь>
CLICKHOUSE_PASSWORD=<пароль>
CLICKHOUSE_DATABASE=<база данных> (необязательно)
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0
CLICKHOUSE_MCP_BIND_PORT=4200
CLICKHOUSE_MCP_AUTH_TOKEN=<токен>  # Или FASTMCP_SERVER_AUTH, или 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

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

uv sync --all-extras --dev # установка dev-зависимостей
uv run ruff check . # запуск линтинга

docker compose up -d test_services # запуск ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # только ClickHouse
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB только

Сервер MCP для ClickHouse

Особенности

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

chDB Tools

Эндпойнт проверки работоспособности

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

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

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

OAuth / OIDC через FastMCP

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

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

Опциональный доступ на запись

Защита от разрушительных операций

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

Пользовательский middleware

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

Пример middleware

Возможности middleware

Динамическая настройка клиента через состояние контекста

Разработка

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

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

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

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

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

Переменные middleware

Переменные chDB

Общие подводные камни конфигурации

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

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

Обзор на YouTube