> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Настройка MCP-сервера ClickHouse
> Подключите MCP-сервер ClickHouse к Claude Code, Claude Desktop, Codex, ChatGPT, Cursor или Windsurf.
[MCP-сервер ClickHouse](https://github.com/ClickHouse/mcp-clickhouse) позволяет совместимым AI-ассистентам просматривать базы данных, изучать таблицы и выполнять SQL-запросы к ClickHouse.
В этом руководстве описывается настройка локального сервера `stdio` с помощью `uv` и его подключение к популярному MCP-клиенту.
По умолчанию сервер разрешает только запросы на чтение.
Используйте отдельного пользователя ClickHouse только с необходимыми ассистенту разрешениями; не используйте пользователя default или пользователя с правами администратора.
В этом пошаговом руководстве настройка показана на примере Claude Desktop.
Те же сведения о подключении ClickHouse применимы и к другим клиентам, рассматриваемым в этом руководстве.
## Предварительные требования
Перед началом работы:
1. [Установите `uv`](https://docs.astral.sh/uv/getting-started/installation/).
2. Установите MCP-клиент, который хотите использовать.
3. Подготовьте имя хоста, имя пользователя и пароль для вашего сервиса 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-клиента
Выполните следующую команду в терминале:
```bash theme={null}
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`:
```json theme={null}
{
"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:
```bash theme={null}
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:
1. Откройте **Settings**, затем выберите **MCP servers**.
2. Выберите **Add server**, затем **STDIO**.
3. В качестве имени укажите `mcp-clickhouse`, а в качестве команды — `uv`.
4. Добавьте аргументы `run`, `--with`, `mcp-clickhouse`, `--python`, `3.10` и `mcp-clickhouse` в указанном порядке.
5. Добавьте `CLICKHOUSE_HOST`, `CLICKHOUSE_USER` и `CLICKHOUSE_PASSWORD`, указав сведения о подключении.
6. Сохраните сервер и перезапустите приложение.
После перезапуска приложения откройте Codex и введите `/mcp` в поле ввода, чтобы проверить подключённый сервер.
Эти действия настраивают локальный сервер `stdio` для Codex в настольном приложении ChatGPT.
Веб-версия ChatGPT использует удалённые инструменты с поддержкой MCP, предоставляемые плагинами.
Чтобы использовать инструменты ClickHouse в веб-версии ChatGPT, см. [Удалённый MCP-сервер в ClickHouse Cloud](/ru/products/cloud/features/ai-ml/remote-mcp).
Добавьте следующий сервер в файл `.cursor/mcp.json` текущего проекта или в глобальную конфигурацию Cursor MCP:
```json theme={null}
{
"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`:
```json theme={null}
{
"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` подключён, попросите его:
```text theme={null}
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`](https://github.com/ClickHouse/mcp-clickhouse).