ClickHouse MCP Server

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

Возможности

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

• run_query

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

  • Входные данные: query (string): SQL-запрос для выполнения.

  • По умолчанию запросы выполняются в режиме только для чтения (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), но при необходимости запись можно явно включить.

• list_databases

  • Выводит список всех баз данных в вашем кластере ClickHouse.

• list_tables

  • Выводит список таблиц в базе данных с постраничной навигацией.

  • Обязательный входной параметр: database (string).

  • Необязательные входные параметры:

    • like / not_like (string): применяет фильтры LIKE или NOT LIKE к именам таблиц.

    • page_token (string): токен, возвращённый предыдущим вызовом для получения следующей страницы.

    • page_size (int, по умолчанию 50): количество таблиц, возвращаемых на одной странице.

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

  • Формат ответа:

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

    • next_page_token: передайте это значение обратно, чтобы получить следующую страницу, или null, если таблиц больше нет.

    • total_tables: общее количество таблиц, соответствующих указанным фильтрам.

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

• run_chdb_select_query

  • Выполняет SQL-запросы с использованием встроенного движка ClickHouse от chDB.

  • Входные данные: query (string): SQL-запрос для выполнения.

  • Запрашивает данные напрямую из различных источников (файлов, URL, баз данных) без ETL-процессов.

  • Требуется дополнительный пакет chdb: pip install 'mcp-clickhouse[chdb]'

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

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

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

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

GET- и HEAD-запросы к этой конечной точке намеренно не требуют аутентификации и освобождены от проверки Host и Origin, чтобы проверки оркестратора (например, liveness/readiness в Kubernetes, балансировщики нагрузки) могли использовать назначенные во время выполнения IP-адреса подов или целевые IP-адреса без дополнительной настройки. /health зарезервирована и не может использоваться как путь MCP-транспорта. Тело ответа намеренно минимально, чтобы не раскрывать строки версий бэкенда или детали ошибок; диагностируйте сбои через журналы сервера.

Пример:

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

Related MCP server: ClickHouse MCP Server

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

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

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

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

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

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

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

   # Using uuidgen (macOS/Linux)
   uuidgen
   
   # Using openssl
   openssl rand -hex 32

2. Настройте сервер с этим токеном:

   export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

3. Настройте ваш MCP-клиент на включение токена в запросы:

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

   {
     "mcpServers": {
       "mcp-clickhouse": {
         "url": "http://127.0.0.1:8000",
         "headers": {
           "Authorization": "Bearer your-generated-token"
         }
       }
     }
   }

   Примечание: конечная точка /health намеренно не требует аутентификации (см. Конечная точка проверки состояния выше). Чтобы убедиться, что аутентификация по bearer-токену действительно отклоняет запросы без аутентификации, обратитесь к самой 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
export CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

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

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

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

1. Откройте файл конфигурации Claude Desktop, расположенный по адресу:

   • На macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • На Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Добавьте следующее:

{
  "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"
      }
    }
  }
}

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

4. Перезапустите Claude Desktop, чтобы изменения вступили в силу.

Необязательный доступ на запись

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

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

Даже когда доступ на запись включён (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), разрушительные операции требуют дополнительного флага явного согласия для безопасности. Проверка охватывает любой оператор DROP (включая предложения ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN), любые TRUNCATE, DELETE и UPDATE (как лёгкие операторы, так и мутации ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE), REPLACE TABLE, CREATE OR REPLACE, ALTER TABLE ... REPLACE PARTITION, ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION, а также DETACH ... PERMANENTLY. Ключевые слова внутри строковых литералов, идентификаторов в кавычках и SQL-комментариев игнорируются, поэтому они не запускают проверку и не скрывают оператор от неё.

Эта проверка выполняется на MCP-сервере и является защитой от случайностей по принципу best-effort. Она не является границей безопасности. Границей безопасности являются привилегии пользователя ClickHouse. Режим только для чтения (по умолчанию) обеспечивается на стороне сервера через readonly=1. Ограничение разрушительных операций не обеспечивается на стороне сервера.

Для режима записи предоставьте MCP-серверу отдельного пользователя ClickHouse только с необходимыми привилегиями:

CREATE USER mcp_agent IDENTIFIED BY '...';
GRANT SELECT, INSERT, CREATE TABLE, ALTER ADD COLUMN ON mydb.* TO mcp_agent;

Любой оператор за пределами этих привилегий затем завершится ошибкой на стороне сервера с ACCESS_DENIED, независимо от флагов MCP. Серверные настройки max_table_size_to_drop и max_partition_size_to_drop также могут ограничить радиус поражения, если их зафиксировать ограничениями настроек.

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

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

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

• Операции записи (INSERT, CREATE, ALTER ADD COLUMN) требуют CLICKHOUSE_ALLOW_WRITE_ACCESS=true

• Разрушительные операции (DROP, TRUNCATE, DELETE, UPDATE и остальные из списка выше) дополнительно требуют CLICKHOUSE_ALLOW_DROP=true

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

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

1. Установите пакет с помощью pip:

   python3 -m pip install mcp-clickhouse

   Чтобы также установить поддержку chDB:

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

   Чтобы обновиться до последней версии:

   python3 -m pip install --upgrade mcp-clickhouse

2. Обновите конфигурацию 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 (вызовы инструментов, чтение ресурсов, подсказки и т. д.).

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

1. Создайте 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())

2. Установите переменную окружения 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"
      }
    }
  }
}

3. Убедитесь, что ваш модуль промежуточного ПО находится в пути импорта 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
})

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

Значение состояния должно быть словарём. Вложенные значения settings и generic_args должны быть сопоставлениями (mappings) и объединяются с базовой конфигурацией. Недопустимые значения приводят к ошибке вызова инструмента до создания клиента ClickHouse. CLICKHOUSE_ROLE остаётся активной, если только переопределение явно не задаёт settings.role. Ключи верхнего уровня role и ch_role, а также те же ключи в generic_args, отклоняются.

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

Разработка

1. В каталоге test-services выполните docker compose up -d, чтобы запустить кластер ClickHouse.

2. Добавьте следующие переменные в файл .env в корне репозитория.

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

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

3. Выполните uv sync для установки зависимостей. Чтобы установить uv, следуйте инструкциям здесь. Затем выполните source .venv/bin/activate.

4. Для удобного тестирования с помощью MCP Inspector запустите fastmcp dev mcp_clickhouse/mcp_server.py, чтобы запустить MCP-сервер.

5. Чтобы проверить HTTP-транспорт и эндпоинт проверки работоспособности:

   # For development, disable authentication
   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000 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

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

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

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

Пример: если MCP-сервер работает в Kubernetes за ingress, который завершает TLS, это вопрос транспорта MCP. Держите CLICKHOUSE_SECURE согласованным с тем, как под достигает самого ClickHouse (HTTPS → true, обычный HTTP → false). Установка CLICKHOUSE_SECURE=false только потому, что MCP-сервер находится за ingress, приведёт к тому, что сервер будет подключаться к 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 (без TLS) / 8443 (TLS) — используются этим сервером и ClickHouse Cloud HTTPS

    • Нативный TCP (здесь не поддерживается): 9000 (без TLS) / 9440 (TLS) — используется clickhouse-client

  • Если сервер отвечает Port 9000 is for clickhouse-client program, вы указали на нативный протокол; переключитесь на HTTP-порт (8123/8443 или HTTP-сопоставление вашего развёртывания)

• CLICKHOUSE_ROLE: роль ClickHouse для аутентификации

  • По умолчанию: None

  • Установите это, если вашему пользователю требуется конкретная роль

• 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", чтобы отключить проверку сертификата (не рекомендуется для производственной среды)

  • TLS-сертификаты: пакет использует хранилище доверия вашей операционной системы для проверки TLS-сертификатов через truststore. Мы вызываем truststore.inject_into_ssl() при запуске, чтобы обеспечить корректную обработку сертификатов. Поведение SSL по умолчанию в Python используется только как запасной вариант при возникновении непредвиденной ошибки.

• CLICKHOUSE_SERVER_HOST_NAME: имя сервера для переопределения SNI и проверки сертификата при подключении к ClickHouse

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

  • Это полезно при подключении через прокси или балансировщики нагрузки, когда имя хоста в сертификате отличается от имени хоста подключения. Если задано, это имя будет использоваться как для SNI (Server Name Indication) во время TLS-рукопожатия, так и для проверки имени хоста в сертификате.

• CLICKHOUSE_PROXY_PATH: префикс пути URL для HTTP-эндпоинта ClickHouse

  • По умолчанию: None

  • Установите это, когда HTTP-интерфейс ClickHouse доступен за обратным прокси с префиксом пути (например, /clickhouse)

• CLICKHOUSE_CONNECT_TIMEOUT: таймаут подключения в секундах для клиента ClickHouse

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

  • Увеличьте это значение, если возникают таймауты подключения

• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: таймаут отправки/получения в секундах для клиента ClickHouse

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

  • Увеличьте это значение для длительных запросов

• CLICKHOUSE_DATABASE: база данных ClickHouse по умолчанию

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

  • Установите это, чтобы автоматически подключаться к конкретной базе данных

• CLICKHOUSE_ENABLED: включение/отключение инструментов базы данных ClickHouse

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

  • Установите "false", чтобы отключить инструменты ClickHouse при использовании только chDB

• CLICKHOUSE_ALLOW_WRITE_ACCESS: разрешение операций записи (DDL и DML) в ClickHouse

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

  • Установите "true", чтобы разрешить неразрушающие DDL и DML (CREATE, INSERT, ALTER ADD COLUMN). Разрушающие операторы дополнительно требуют CLICKHOUSE_ALLOW_DROP=true

  • Когда отключено (по умолчанию), запросы выполняются с настройкой readonly=1 для предотвращения изменений данных

• CLICKHOUSE_ALLOW_DROP: разрешение разрушающих операций (любой DROP или TRUNCATE, DELETE и UPDATE, включая варианты ALTER TABLE, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION, а также DETACH ... PERMANENTLY)

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

  • Действует только при установленном CLICKHOUSE_ALLOW_WRITE_ACCESS=true

  • Этот предохранитель — всего лишь попытка защитить от случайных действий в MCP-сервере, а не граница безопасности. Для реального обеспечения ограничьте гранты пользователя ClickHouse (см. Защита от разрушающих операций)

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: Статический bearer-токен для HTTP/SSE транспортов

  • По умолчанию: None

  • Один из 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

  • По умолчанию: None

  • Значение — это полный путь к классу подкласса 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", чтобы отключить аутентификацию только для локальной разработки/тестирования

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

• CLICKHOUSE_MCP_ALLOWED_HOSTS: Разделенные запятыми значения заголовка Host, на которые отвечает HTTP/SSE сервер

  • По умолчанию для loopback-привязки: формы без порта и с любым портом для 127.0.0.1, localhost и [::1]

  • Если задано, значение должно содержать как минимум одну запись Host.

  • Конкретный не-loopback адрес привязки по умолчанию использует этот адрес и настроенный порт. Привязка с подстановочным знаком, такая как 0.0.0.0 или ::, требует явного непустого значения, поскольку публичный Host не может быть выведен.

  • Проверка Host — это эшелонированная защита от DNS rebinding. Проверка Origin, описанная ниже, требуется отдельно согласно MCP.

  • Записи являются точными (localhost:8000) или принимают любой порт (localhost:*). Пример: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

  • Форма host:* соответствует только значениям, содержащим порт. Host без порта (развертывание на стандартном порту, когда клиент опускает :80/:443) также должен быть указан как точная запись без порта (example.com).

  • Запросы с несовпадающим или отсутствующим заголовком Host получают 421 Misdirected Request. GET и HEAD запросы к /health освобождаются от проверки Host и Origin, чтобы проверки оркестратора продолжали работать.

  • За обратным прокси укажите значение Host, которое прокси передает дальше. Задайте явный список, когда лаунчер, такой как fastmcp run, переопределяет адрес привязки для удаленного доступа.

• CLICKHOUSE_MCP_ALLOWED_ORIGINS: Разделенные запятыми значения заголовка Origin, принимаемые по HTTP/SSE

  • По умолчанию: None, что отклоняет каждый запрос, содержащий заголовок Origin

  • MCP требует проверку Origin для HTTP/SSE транспортных соединений. Запросы без Origin принимаются, поскольку небраузерные MCP-клиенты обычно его опускают. Несовпадающий Origin получает 403 Forbidden. Конечная точка /health освобождается от проверки, как описано выше.

  • Записи являются точными (http://localhost:3000) или принимают любой порт (http://localhost:*). Как и в случае с хостами, форма с любым портом соответствует только тем origin, которые содержат порт; origin на стандартном порту (https://app.example.com) должен быть указан точно.

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

• MCP_MIDDLEWARE_MODULE: Имя Python-модуля, содержащего пользовательское промежуточное ПО для внедрения в MCP-сервер

  • По умолчанию: None (промежуточное ПО не загружается)

  • Установите имя модуля (без расширения .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-сервер находится за Kubernetes ingress, обратным прокси или доступен по обычному HTTP, не отключает TLS базы данных; это лишь меняет способ подключения данного процесса к ClickHouse. Настройте ingress TLS отдельно от настроек клиента базы данных.

• Порты нативного протокола — CLICKHOUSE_PORT должен указывать на HTTP-интерфейс ClickHouse (8123/8443 по умолчанию). Порты 9000/9440 предназначены для нативного TCP-протокола (clickhouse-client) и не будут работать с этим сервером.

• Путаница с Host — 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)
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:4200,localhost:4200,mcp.example.com:4200  # Include every Host value clients and proxies send

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

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

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

• Эндпоинт MCP: http://localhost:8000/mcp

• Проверка работоспособности: http://localhost:8000/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

Обзор YouTube