클릭하우스 MCP 서버

Clickhouse 데이터베이스 MCP 서버 프로젝트.

설치

uv 사용하여 패키지를 설치할 수 있습니다:

지엑스피1

또는 pip 사용하면:

pip install clickhouse-mcp-server

구성 요소

도구

서버는 두 가지 도구를 제공합니다.

connect_database : 특정 Clickhouse 데이터베이스에 연결합니다.
- database 매개변수: 연결할 데이터베이스의 이름(문자열)
- 연결이 성공하면 확인 메시지를 반환합니다.
execute_query : Clickhouse 쿼리를 실행합니다.
- query 매개변수: 실행할 SQL 쿼리(문자열)
- JSON 형식으로 쿼리 결과를 반환합니다.
- 여러 개의 쿼리를 세미콜론으로 구분하여 보낼 수 있습니다.

구성

서버는 다음과 같은 환경 변수를 사용합니다.

CLICKHOUSE_HOST : Clickhouse 서버 주소(기본값: "localhost")
CLICKHOUSE_USER : Clickhouse 사용자 이름(기본값: "root")
CLICKHOUSE_PASSWORD : Clickhouse 비밀번호(기본값: "")
CLICKHOUSE_DATABASE : 초기 데이터베이스(선택 사항)
CLICKHOUSE_READONLY : 읽기 전용 모드(활성화하려면 1/true로 설정, 기본값: false)

빠른 시작

설치

클로드 데스크탑

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json

윈도우: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/burakdirin/Projects/clickhouse-mcp-server",
        "run",
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "clickhouse-mcp-server": {
      "command": "uvx",
      "args": [
        "clickhouse-mcp-server"
      ],
      "env": {
        "CLICKHOUSE_HOST": "localhost",
        "CLICKHOUSE_USER": "root",
        "CLICKHOUSE_PASSWORD": "password",
        "CLICKHOUSE_DATABASE": "[optional]",
        "CLICKHOUSE_READONLY": "true"
      }
    }
  }
}

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Clickhouse Database Integration Server를 자동으로 설치하려면:

npx -y @smithery/cli install @burakdirin/clickhouse-mcp-server --client claude

개발

건축 및 출판

배포를 위해 패키지를 준비하려면:

종속성 동기화 및 잠금 파일 업데이트:

uv sync

패키지 배포 빌드:

uv build

이렇게 하면 dist/ 디렉토리에 소스와 휠 배포판이 생성됩니다.

PyPI에 게시:

uv publish

참고: 환경 변수나 명령 플래그를 통해 PyPI 자격 증명을 설정해야 합니다.

토큰: --token 또는 UV_PUBLISH_TOKEN
또는 사용자 이름/비밀번호: --username / UV_PUBLISH_USERNAME 및 --password / UV_PUBLISH_PASSWORD

디버깅

MCP 서버는 stdio를 통해 실행되므로 디버깅이 어려울 수 있습니다. 최상의 디버깅 환경을 위해서는 MCP Inspector 사용을 강력히 권장합니다.

다음 명령을 사용하여 npm 통해 MCP Inspector를 시작할 수 있습니다.

npx @modelcontextprotocol/inspector uv --directory /Users/burakdirin/Projects/clickhouse-mcp-server run clickhouse-mcp-server

Inspector를 실행하면 브라우저에서 접근하여 디버깅을 시작할 수 있는 URL이 표시됩니다.

clickhouse-mcp-server

Integrations