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 개요

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

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
MCP Alchemy
runekaagaard
-
security
A
license
-
quality
Connects Claude Desktop directly to databases, allowing it to explore database structures, write SQL queries, analyze datasets, and create reports through an API layer with tools for table exploration and query execution.
Last updated -
263
Python
Mozilla Public License 2.0
CockroachDB MCP Server
dhartunian
-
security
F
license
-
quality
Connects to CockroachDB instances and exposes database structures as resources, enabling SQL query execution and analysis through Claude's interface.
Last updated -
2
TypeScript
Knowledge Base MCP Server
jeanibarz
A
security
A
license
A
quality
Provides tools for listing and retrieving content from different knowledge bases using semantic search capabilities.
Last updated -
2
18
TypeScript
The Unlicense

View all related MCP servers

mcp-clickhouse

ClickHouse MCP 서버

특징

도구

구성

개발

환경 변수

필수 변수

선택 변수

구성 예

테스트 실행

YouTube 개요

Tools

Related Resources

Related MCP Servers

ClickHouse MCP Server

MCP Alchemy

CockroachDB MCP Server

Knowledge Base MCP Server

Appeared in Searches

New MCP Servers

MCP directory API