1. Клонируем репозиторий из github для clickhouse

git clone git@github.com:ClickHouse/mcp-clickhouse.git

2. В json-конфиг claude_desktop_config.json в корень добавить секцию mcpServers и в ней mcp-clickhouse:

"mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "--directory",
        "/var/projects/mcp-clickhouse",
        "run",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "clickhouse.host.example.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "username",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_DATABASE": "default"
      }
    }

Где:

• /var/projects/mcp-clickhouse — путь к проекту mcp-clickhouse, который склонировали в п.1.
• валидные креденшиалы проставить в env CLICKHOUSE_ переменных.

MCP для clickhouse будет запускаться как standalone Python-процесс, который Claude Desktop/Cowork запускает локально и общается с ним по stdio. Альтернативный вариант

Креды живут в переменных окружения этого процесса — не в чате. 

Через Claude Desktop аналогичное действие можно сделать через UI меню: Settings → Developer → Edit Config.

Итоговый вид конфига claude_desktop_config.json примет примерно такой вид:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "--directory",
        "/var/projects/mcp-clickhouse",
        "run",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "your-clickhouse.host.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "user",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_DATABASE": "default",
        "CLICKHOUSE_READ_ONLY": "true"
      }
    }
  },
  "preferences": {
    "coworkScheduledTasksEnabled": true,
    "ccdScheduledTasksEnabled": true,
    "sidebarMode": "task",
    "coworkWebSearchEnabled": true,
    "remoteToolsDeviceName": "by-xdevicex",
    "epitaxyPrefs": {
      "starred-local-code-sessions": [],
      "starred-cowork-spaces": [],
      "starred-session-groups": [],
      "dframe-local-slice": {
        "pinnedOrder": [],
        "customGroupAssignments": {},
        "customGroupOrder": {}
      }
    },
    "bypassPermissionsGateByAccount": {
      "xxxxxxxx-3bfa-4284-b5ad-xxxxxxxxxxxx": false
    }
  }
}

3. Сделайте рестарт сессии Claude.

Теперь агент может самостоятельно отправлять запросы в clickhouse через ваш локальный MCP-сервер. Попросите его что-то проанализировать.

Если MCP ClickHouse после перезапуска (рестарта сессии) Claude или другого AI агента не стартует:

Failed to spawn process: No such file or directory

2026-05-18T08:40:55.869Z [mcp-clickhouse] [info] Server started and connected successfully { metadata: undefined }
Failed to spawn process: No such file or directory
2026-05-18T08:40:55.875Z [mcp-clickhouse] [info] Server transport closed { metadata: undefined }
2026-05-18T08:40:55.875Z [mcp-clickhouse] [info] Server transport closed unexpectedly, this is likely due to the process exiting early. If you are developing this MCP server you can add output to stderr (i.e. console.error('...') in JavaScript, print('...', file=sys.stderr) in python) and it will appear in this log. { metadata: undefined }
2026-05-18T08:40:55.875Z [mcp-clickhouse] [error] Server disconnected. For troubleshooting guidance, please visit our [debugging documentation](https://modelcontextprotocol.io/docs/tools/debugging) { metadata: { context: 'connection', stack: undefined } }
2026-05-18T08:40:55.876Z [mcp-clickhouse] [info] Client transport closed { metadata: undefined }

То AI агент сообщит сразу на старте сессии. Убедитесь что на MacOS установлен uv — быстрый менеджер пакетов и проектов для Python, написанный на Rust. which uv.

Если uv нет, то поставьте:

# 1. Поставить uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Поставить uv
brew install uv

И убедитесь что есть в PATH: which uv. 

Сделайте рестарт сессии AI агента чтобы проверить mcp Clichouse снова.

Агент не ходит напрямую в clickhouse, только через прослойку в виде MCP.

Максимальный timeout запросов режется MCP оберткой и будет ограничен в 30 секунд, больше не получится. Агент сам увидит что получает timeouts, подрезает, сужает выборки, адаптирует запросы соответственно.