Настройка MCP-сервера ClickHouse

MCP-сервер ClickHouse позволяет совместимым AI-ассистентам просматривать базы данных, изучать таблицы и выполнять SQL-запросы к ClickHouse. В этом руководстве описывается настройка локального сервера stdio с помощью uv и его подключение к популярному MCP-клиенту.

По умолчанию сервер разрешает только запросы на чтение. Используйте отдельного пользователя ClickHouse только с необходимыми ассистенту разрешениями; не используйте пользователя default или пользователя с правами администратора.

В этом пошаговом руководстве настройка показана на примере Claude Desktop. Те же сведения о подключении ClickHouse применимы и к другим клиентам, рассматриваемым в этом руководстве.

Предварительные требования

Перед началом работы:

Установите uv.
Установите MCP-клиент, который хотите использовать.
Подготовьте имя хоста, имя пользователя и пароль для вашего сервиса ClickHouse.

В примерах ниже используются следующие значения-заполнители:

Переменная окружения	Значение
`CLICKHOUSE_HOST`	`your-clickhouse-host`
`CLICKHOUSE_USER`	`your-clickhouse-user`
`CLICKHOUSE_PASSWORD`	`your-clickhouse-password`

Замените их своими сведениями о подключении. Для сервиса ClickHouse Cloud по умолчанию используется HTTPS на порту 8443. Для самоуправляемого сервиса, использующего обычный HTTP, также установите CLICKHOUSE_SECURE=false и при необходимости CLICKHOUSE_PORT=8123.

Настройка MCP-клиента

Выполните следующую команду в терминале:

claude mcp add \
  --transport stdio \
  --env CLICKHOUSE_HOST=your-clickhouse-host \
  --env CLICKHOUSE_USER=your-clickhouse-user \
  --env CLICKHOUSE_PASSWORD=your-clickhouse-password \
  --scope user \
  mcp-clickhouse -- \
  uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

Выполните claude mcp list, чтобы проверить подключение, или введите /mcp в Claude Code, чтобы просмотреть сервер и доступные инструменты.

В Claude Desktop откройте Settings, выберите Developer, затем Edit config. Добавьте следующий сервер в файл claude_desktop_config.json:

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

Сохраните файл и перезапустите Claude Desktop. Откройте Connectors в поле ввода чата и убедитесь, что mcp-clickhouse доступен.

Добавьте сервер через Codex CLI:

codex mcp add mcp-clickhouse \
  --env CLICKHOUSE_HOST=your-clickhouse-host \
  --env CLICKHOUSE_USER=your-clickhouse-user \
  --env CLICKHOUSE_PASSWORD=your-clickhouse-password \
  -- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse

Выполните codex mcp list, чтобы проверить подключение, или введите /mcp в терминальном интерфейсе Codex. Codex CLI, расширение Codex для IDE и настольное приложение ChatGPT используют общую конфигурацию MCP из ~/.codex/config.toml.

Настольное приложение ChatGPT настраивает локальные MCP-серверы для хоста Codex. Эта конфигурация также используется Codex CLI и расширением Codex для IDE.

В настольном приложении ChatGPT:

Откройте Settings, затем выберите MCP servers.
Выберите Add server, затем STDIO.
В качестве имени укажите mcp-clickhouse, а в качестве команды — uv.
Добавьте аргументы run, --with, mcp-clickhouse, --python, 3.10 и mcp-clickhouse в указанном порядке.
Добавьте CLICKHOUSE_HOST, CLICKHOUSE_USER и CLICKHOUSE_PASSWORD, указав сведения о подключении.
Сохраните сервер и перезапустите приложение.

После перезапуска приложения откройте Codex и введите /mcp в поле ввода, чтобы проверить подключённый сервер.

Добавьте следующий сервер в файл .cursor/mcp.json текущего проекта или в глобальную конфигурацию Cursor MCP:

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

Перезапустите Cursor, затем откройте настройки MCP и убедитесь, что сервер включён.

Добавьте следующий сервер в файл ~/.codeium/windsurf/mcp_config.json:

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

Перезапустите Windsurf, затем откройте настройки MCP и убедитесь, что сервер включён.

Проверьте подключение

Когда клиент сообщит, что mcp-clickhouse подключён, попросите его:

List the databases available in ClickHouse, then show me the tables in one of them.

Клиент может попросить вас подтвердить первые вызовы инструментов. Проверяйте каждый запрос, прежде чем предоставлять доступ.

Устранение неполадок

Если клиент сообщает, что не удаётся найти uv, замените uv в команде или конфигурации его абсолютным путём. Чтобы узнать этот путь, выполните which uv в macOS или Linux либо where uv в Windows.

Дополнительные настройки подключения, необязательная поддержка chDB, HTTP-транспорт и аутентификация описаны в README mcp-clickhouse.