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.

Integrations

Allows executing SQL queries on a ClickHouse cluster and retrieving information about databases and tables. It provides tools to run SELECT queries, list databases, and list tables in a database.

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>"
      }
    }
  }
}

YouTube 개요

You must be authenticated.

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

Tools

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

Related Resources

Reddit Discussion about this server