mcp-클릭하우스

ClickHouse MCP 서버

ClickHouse용 MCP 서버.

특징

도구

run_select_query
- ClickHouse 클러스터에서 SQL 쿼리를 실행합니다.
- 입력: sql (문자열): 실행할 SQL 쿼리.
- 모든 ClickHouse 쿼리는 안전을 보장하기 위해 readonly = 1 로 실행됩니다.
list_databases
- ClickHouse 클러스터에 있는 모든 데이터베이스를 나열합니다.
list_tables
- 데이터베이스의 모든 테이블을 나열합니다.
- 입력: database (문자열): 데이터베이스의 이름입니다.

구성

다음 위치에 있는 Claude Desktop 구성 파일을 엽니다.
- macOS의 경우: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows의 경우: %APPDATA%/Claude/claude_desktop_config.json
다음을 추가합니다.

지엑스피1

환경 변수를 업데이트하여 사용자의 ClickHouse 서비스를 가리키도록 합니다.

또는 ClickHouse SQL Playground 에서 시도해 보려면 다음 구성을 사용할 수 있습니다.

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com",
        "CLICKHOUSE_PORT": "8443",
        "CLICKHOUSE_USER": "demo",
        "CLICKHOUSE_PASSWORD": "",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

uv 명령 항목을 찾아 uv 실행 파일의 절대 경로로 바꾸세요. 이렇게 하면 서버를 시작할 때 올바른 버전의 uv 사용됩니다. Mac에서는 which uv 사용하여 이 경로를 찾을 수 있습니다.
변경 사항을 적용하려면 Claude Desktop을 다시 시작하세요.

개발

test-services 디렉토리에서 docker compose up -d 실행하여 ClickHouse 클러스터를 시작합니다.
저장소 루트에 있는 .env 파일에 다음 변수를 추가합니다.

참고: 이 컨텍스트에서 default 사용자를 사용하는 것은 로컬 개발 목적으로만 사용됩니다.

CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

uv sync 실행하여 종속성을 설치하세요. uv 설치하려면 여기의 지침을 따르세요. 그런 다음 source .venv/bin/activate 실행하세요.
간편하게 테스트하려면 mcp dev mcp_clickhouse/mcp_server.py 실행하여 MCP 서버를 시작할 수 있습니다.

환경 변수

다음 환경 변수는 ClickHouse 연결을 구성하는 데 사용됩니다.

필수 변수

CLICKHOUSE_HOST : ClickHouse 서버의 호스트 이름
CLICKHOUSE_USER : 인증을 위한 사용자 이름
CLICKHOUSE_PASSWORD : 인증을 위한 비밀번호

[!주의] MCP 데이터베이스 사용자는 데이터베이스에 연결하는 외부 클라이언트와 동일하게 취급하고, 운영에 필요한 최소한의 권한만 부여해야 합니다. 기본 사용자나 관리자 권한은 절대 사용하지 마십시오.

선택 변수

CLICKHOUSE_PORT : ClickHouse 서버의 포트 번호
- 기본값: HTTPS가 활성화된 경우 8443 , 비활성화된 경우 8123
- 비표준 포트를 사용하지 않는 한 일반적으로 설정할 필요가 없습니다.
CLICKHOUSE_SECURE : HTTPS 연결 활성화/비활성화
- 기본값: "true"
- 보안되지 않은 연결의 경우 "false" 로 설정
CLICKHOUSE_VERIFY : SSL 인증서 검증 활성화/비활성화
- 기본값: "true"
- 인증서 검증을 비활성화하려면 "false" 로 설정합니다(프로덕션에는 권장하지 않음).
CLICKHOUSE_CONNECT_TIMEOUT : 연결 시간 초과(초)
- 기본값: "30"
- 연결 시간 초과가 발생하면 이 값을 늘리십시오.
CLICKHOUSE_SEND_RECEIVE_TIMEOUT : 송수신 시간 초과(초)
- 기본값: "300"
- 장기 실행 쿼리의 경우 이 값을 늘리십시오.
CLICKHOUSE_DATABASE : 사용할 기본 데이터베이스
- 기본값: 없음(서버 기본값 사용)
- 특정 데이터베이스에 자동으로 연결하려면 이것을 설정하세요.

구성 예

Docker를 사용한 로컬 개발의 경우:

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

ClickHouse Cloud의 경우:

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

ClickHouse SQL Playground의 경우:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

다음 변수는 환경, .env 파일 또는 Claude Desktop 구성에서 설정할 수 있습니다.

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.13",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>"
      }
    }
  }
}

테스트 실행

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest tests

YouTube 개요

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

스키마 검사 및 쿼리 기능을 갖춘 ClickHouse 데이터베이스 통합

Related Resources

Reddit Discussion about this server

Related MCP Servers

ClickHouse MCP Server
iskakaushik
A
security
A
license
A
quality
An MCP server for ClickHouse.
Last updated -
3
3
Python
Apache 2.0
ClickHouse MCP Server
ThomAub
-
security
A
license
-
quality
A Model Context Protocol server that enables Large Language Models to seamlessly interact with ClickHouse databases, supporting resource listing, schema retrieval, and query execution.
Last updated -
1
Python
MIT License
clickhouse-mcp-server
burakdirin
-
security
A
license
-
quality
An MCP server implementation that enables Claude AI to interact with Clickhouse databases. Features include secure database connections, query execution, read-only mode support, and multi-query capabilities.
Last updated -
Python
MIT License
ClickHouse MCP Server
dubin555
-
security
-
license
-
quality
A Model Context Protocol server that enables AI assistants to securely interact with ClickHouse databases, supporting table exploration and SQL query execution through a controlled interface.
Last updated -
6
Python
Apache 2.0

View all related MCP servers

mcp-clickhouse

ClickHouse MCP 서버

특징

도구

구성

개발

환경 변수

필수 변수

선택 변수

구성 예

테스트 실행

YouTube 개요

Tools

Related Resources

Related MCP Servers

ClickHouse MCP Server

ClickHouse MCP Server

clickhouse-mcp-server

ClickHouse MCP Server

Appeared in Searches

New MCP Servers

MCP directory API