mcp-clickhouse

Сервер Model Context Protocol для ClickHouse. Он позволяет MCP-клиенту (Claude Desktop, Claude Code и т.п.) исследовать схемы, выполнять аналитические запросы и управлять базой данных — а поведение полностью контролируется флагами.

Модель безопасности базируется на осведомлённости о типе оператора: каждый SQL-оператор классифицируется как чтение, запись или деструктивный и проверяется в соответствии с текущим режимом доступа. Режим read-only дополнительно выполняет запросы под readonly=1 самого ClickHouse.

Возможности

• Обзор и мониторинг — базы данных, таблицы, колонки, SHOW CREATE, статистика таблиц (parts/rows/bytes), выполняющиеся запросы, метрики сервера, топология кластера

• Чтение запросов — инструмент query, который принимает только операторы чтения и ограничен параметром CLICKHOUSE_MAX_ROWS

• Управление — инструмент execute для INSERT/CREATE/ALTER (read-write) и DROP/TRUNCATE/DELETE (admin), каждое действие классифицируется

• Режимы доступа — read-only → read-write → admin, они выстроены уровнями, чтобы режим никогда не открывал операторы, превышающие его уровень

• Флаги безопасности — разрешённые базы данных, защищённые базы данных, блокировка деструктивных операций, лимит строк, dry-run и JSON-журнал аудита (см. ниже)

Related MCP server: clickhouse-mcp-server

Модель безопасности

Классификация операторов находится в src/sql.ts и построена по принципу fail-safe: ALTER … DELETE/UPDATE считается деструктивным, и всё, что не удаётся разобрать, также деструктивно.

Инструменты

Чтение (read-only+): list_databases, list_tables, describe_table, show_create_table, table_stats, running_queries, server_metrics, cluster_info, query.

Запись/Администрирование (read-write+): execute — запускает одну команду после классификации; для записи требуется режим read-write, для деструктивных — admin + CLICKHOUSE_ALLOW_DELETE.

Использование с вашим MCP-клиентом

Работает с Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code (Copilot) и любым другим MCP-клиентом — см. docs/CLIENTS.md для настройки под каждого клиента.

Установка

npm install
npm run build

Запуск с Claude Desktop / Claude Code

{
  "mcpServers": {
    "clickhouse": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-clickhouse/dist/index.js"],
      "env": {
        "CLICKHOUSE_URL": "http://clickhouse:8123",
        "CLICKHOUSE_USER": "readonly",
        "CLICKHOUSE_PASSWORD": "…",
        "CLICKHOUSE_MODE": "read-only",
        "CLICKHOUSE_DATABASE_ALLOWLIST": "analytics"
      }
    }
  }
}

Примеры запросов

• "Какие таблицы самые большие в базе данных analytics?"

• "Покажи схему для events и выполни запрос по ежедневным количествам за эту неделю."

• "Какие запросы сейчас выполняются и потребляют больше всего памяти?"

Разработка

npm run dev
npm test          # SQL classification + security policy (30 tests)
npm run typecheck

Публикация

Сервер поставляется с server.json для официального реестра MCP и содержит поле mcpName для проверки владельца npm. См. PUBLISHING.md для публикации на npm и в реестре MCP, Smithery, Glama, Cursor и PulseMCP.

Лицензия-бесплатно

MIT-ия.