mcp-clickhouse

ClickHouse용 Model Context Protocol 서버입니다. MCP를 지원하는 클라이언트(Claude Desktop, Claude Code 등)에서 스키마를 탐색하고, 분석 쿼리를 실행하고, 데이터베이스를 관리할 수 있게 해주며, 그 동작은 전적으로 플래그로 제어됩니다.

보안 모델은 문(statement) 인식 방식입니다. 모든 SQL문은 읽기, 쓰기, 파괴적(destructive)으로 분류되며, 현재 액세스 모드와 대응해 제어됩니다. 읽기 전용 모드에서는 추가로 ClickHouse의 readonly=1 설정으로 쿼리를 실행합니다.

기능

• 탐색 및 모니터링 — 데이터베이스, 테이블, 컬럼, SHOW CREATE, 테이블 통계(파트/행/바이트), 실행 중인 쿼리, 서버 메트릭, 클러스터 토폴로지.

• 읽기 쿼리 — 읽기 문만 허용하는 query 도구이며, CLICKHOUSE_MAX_ROWS로 제한됩니다.

• 관리 — INSERT/CREATE/ALTER(read-write) 및 DROP/TRUNCATE/DELETE(admin)용 execute 도구로, 각각 분류에 따라 제어됩니다.

• 액세스 모드 — read-only → read-write → admin 순으로 계층화되어 있어, 어떤 모드도 바로 위 단계의 문을 노출하지 않습니다.

• 보안 플래그 — 데이터베이스 허용 목록, 보호 데이터베이스, 파괴적 문 제어, 행 제한, dry-run, 그리고 JSON 감사 로깅(아래 참조).

Related MCP server: clickhouse-mcp-server

보안 모델

문 분류는 src/sql.ts에 있으며 안전에 안전을 기하는 방식입니다: 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

게시

이 서버는 공식 MCP 레지스트리를 위한 server.json과 npm 소유권 검증을 위한 mcpName을 포함합니다. npm에 게시하고 MCP 레지스트리, Smithery, Glama, Cursor, PulseMCP에 등록하는 방법은 **PUBLISHING.md**를 참고하세요.

라이선스

MIT