ClickHouse

공식

ClickHouse 데이터베이스 서버에 쿼리합니다.

GitHub

839

Click House MCP(으)로 무엇을 할 수 있나요?

읽기 전용 SQL 쿼리 실행 — 어시스턴트에게 run_query를 사용하여 ClickHouse 클러스터에 대해 SELECT 쿼리를 실행하도록 요청합니다.
데이터베이스 및 테이블 나열 — list_databases로 모든 데이터베이스를 나열하거나 list_tables로 특정 데이터베이스의 테이블을 페이지 단위로 탐색하여 스키마를 살펴봅니다.
chDB를 통해 파일 및 URL 직접 쿼리 — run_chdb_select_query를 사용하여 로컬 파일이나 원격 데이터 소스에 대해 먼저 ClickHouse에 로드하지 않고 SQL을 실행합니다.
쓰기 및 파괴적 작업 제어 — DDL/DML에 대해 CLICKHOUSE_ALLOW_WRITE_ACCESS를 활성화하고, 선택적으로 CLICKHOUSE_ALLOW_DROP을 활성화하여 AI 지원 세션 중 DROP 또는 TRUNCATE 문을 허용합니다.

문서

ClickHouse MCP 서버

ClickHouse용 MCP 서버입니다.

기능

ClickHouse 도구

run_query
- ClickHouse 클러스터에서 SQL 쿼리를 실행합니다.
- 입력: query (문자열): 실행할 SQL 쿼리입니다.
- 쿼리는 기본적으로 읽기 전용 모드로 실행되지만(CLICKHOUSE_ALLOW_WRITE_ACCESS=false), 필요한 경우 명시적으로 쓰기를 활성화할 수 있습니다.
list_databases
- ClickHouse 클러스터의 모든 데이터베이스를 나열합니다.
list_tables
- 페이지네이션을 통해 데이터베이스의 테이블을 나열합니다.
- 필수 입력: database (문자열).
- 선택적 입력:
  - like / not_like (문자열): 테이블 이름에 LIKE 또는 NOT LIKE 필터를 적용합니다.
  - page_token (문자열): 다음 페이지를 가져오기 위해 이전 호출에서 반환된 토큰입니다.
  - page_size (정수, 기본값 50): 페이지당 반환되는 테이블 수입니다.
  - include_detailed_columns (부울, 기본값 true): false인 경우, 전체 create_table_query을 유지하면서 더 가벼운 응답을 위해 열 메타데이터를 생략합니다.
- 응답 형태:
  - tables: 현재 페이지의 테이블 객체 배열입니다.
  - next_page_token: 다음 페이지를 가져오려면 이 값을 다시 전달하거나, 더 이상 테이블이 없으면 null입니다.
  - total_tables: 제공된 필터와 일치하는 총 테이블 수입니다.

chDB 도구

run_chdb_select_query
- chDB의 내장 ClickHouse 엔진을 사용하여 SQL 쿼리를 실행합니다.
- 입력: query (문자열): 실행할 SQL 쿼리입니다.
- ETL 프로세스 없이 다양한 소스(파일, URL, 데이터베이스)에서 직접 데이터를 쿼리합니다.
- 선택적 chdb 추가 기능 필요: pip install 'mcp-clickhouse[chdb]'

상태 확인 엔드포인트

HTTP 또는 SSE 전송으로 실행할 때 /health에서 상태 확인 엔드포인트를 사용할 수 있습니다. 이 엔드포인트는:

서버가 정상이고 ClickHouse에 연결할 수 있으면 200 OK (본문: OK)을 반환합니다.
서버가 ClickHouse에 연결할 수 없으면 일반 오류 메시지와 함께 503 Service Unavailable을 반환합니다.

이 엔드포인트는 오케스트레이터 프로브(예: Kubernetes 활성/준비 상태 프로브, 로드 밸런서)가 자격 증명 없이 접근할 수 있도록 의도적으로 인증되지 않았습니다. 응답 본문은 백엔드 버전 문자열이나 오류 세부 정보가 노출되지 않도록 의도적으로 최소화되어 있으며, 서버 로그를 통해 오류를 디버그하십시오.

예시:

curl http://localhost:8000/health
# Response: OK

보안

HTTP/SSE 전송을 위한 인증

HTTP 또는 SSE 전송을 사용하는 경우 인증이 기본적으로 필요합니다. stdio 전송(기본값)은 표준 입출력을 통해서만 통신하므로 인증이 필요하지 않습니다.

세 가지 인증 모드가 지원됩니다. 하나를 선택하십시오:

모드	사용 시기	환경 변수
정적 베어러 토큰	간단한 배포, 내부 서비스	`CLICKHOUSE_MCP_AUTH_TOKEN`
OAuth / OIDC (FastMCP 경유)	Azure Entra, Google, GitHub, WorkOS 등	`FASTMCP_SERVER_AUTH=<provider-class-path>` (+ 공급자별 `FASTMCP_SERVER_AUTH_*` 변수)
비활성화	로컬 개발 전용	`CLICKHOUSE_MCP_AUTH_DISABLED=true`

HTTP/SSE 전송에 대해 이 중 아무것도 구성되지 않으면 시작이 실패합니다.

인증 설정

보안 토큰을 생성합니다(임의의 문자열 가능):

# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

토큰으로 서버를 구성합니다:

export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

요청에 토큰을 포함하도록 MCP 클라이언트를 구성합니다:

HTTP/SSE 전송을 사용하는 Claude Desktop의 경우:
```
{
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}
```
참고: /health 엔드포인트는 의도적으로 인증되지 않았습니다(위의 상태 확인 엔드포인트 참조). 베어러 토큰 인증이 실제로 인증되지 않은 요청을 거부하는지 확인하려면 MCP 인스펙터를 사용하거나 Authorization 헤더 유무에 따라 /mcp에 JSON-RPC 요청을 POST하여 인증되지 않은 호출이 401을 반환하는지 확인하십시오.

FastMCP를 통한 OAuth / OIDC

ID 공급자(Azure Entra, Google, GitHub, WorkOS 등)를 사용하는 프로덕션 배포의 경우 정적 토큰을 사용하는 대신 FastMCP의 내장 인증 공급자에 인증을 위임하십시오. FASTMCP_SERVER_AUTH을 FastMCP 인증 공급자의 전체 클래스 경로로 설정하고 공급자별 FASTMCP_SERVER_AUTH_* 변수를 함께 설정하며 CLICKHOUSE_MCP_AUTH_TOKEN는 설정하지 않은 상태로 둡니다.

예시 (Azure Entra):

export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.azure.AzureProvider
export FASTMCP_SERVER_AUTH_AZURE_TENANT_ID="<tenant-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_ID="<client-id>"
export FASTMCP_SERVER_AUTH_AZURE_CLIENT_SECRET="<client-secret>"

전체 공급자 목록과 필요한 환경 변수는 FastMCP 문서를 참조하십시오.

개발 모드 (인증 비활성화)

로컬 개발 및 테스트 전용으로 다음을 설정하여 인증을 비활성화할 수 있습니다:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

경고: 로컬 개발에만 사용하십시오. 서버가 네트워크에 노출된 경우 인증을 비활성화하지 마십시오.

구성

이 MCP 서버는 ClickHouse와 chDB를 모두 지원합니다. 필요에 따라 둘 중 하나 또는 둘 다 활성화할 수 있습니다.

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

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_ROLE": "<clickhouse-role>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

환경 변수를 자신의 ClickHouse 서비스를 가리키도록 업데이트하십시오.

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

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "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"
      }
    }
  }
}

chDB(내장 ClickHouse 엔진)의 경우 다음 구성을 추가합니다:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CHDB_ENABLED": "true",
        "CLICKHOUSE_ENABLED": "false",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

ClickHouse와 chDB를 동시에 활성화할 수도 있습니다:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

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

선택적 쓰기 액세스

기본적으로 이 MCP는 탐색 중에 실수로 변경이 발생하지 않도록 읽기 전용 쿼리를 강제합니다. DDL 또는 INSERT/UPDATE 문을 허용하려면 CLICKHOUSE_ALLOW_WRITE_ACCESS 환경 변수를 true으로 설정하십시오. ClickHouse 인스턴스 자체가 쓰기를 허용하지 않는 경우 서버는 계속 읽기 전용 모드를 강제합니다.

파괴적 작업 보호

쓰기 액세스가 활성화된 경우(CLICKHOUSE_ALLOW_WRITE_ACCESS=true)에도 파괴적 작업(DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)은 안전을 위해 추가적인 옵트인 플래그가 필요합니다. 이는 AI 탐색 중 실수로 데이터가 삭제되는 것을 방지합니다.

파괴적 작업을 활성화하려면 두 플래그를 모두 설정하십시오:

"env": {
  "CLICKHOUSE_ALLOW_WRITE_ACCESS": "true",
  "CLICKHOUSE_ALLOW_DROP": "true"
}

이 2단계 접근 방식은 실수로 인한 삭제를 매우 어렵게 만듭니다:

쓰기 작업 (INSERT, UPDATE, CREATE)에는 CLICKHOUSE_ALLOW_WRITE_ACCESS=true가 필요합니다.
파괴적 작업 (DROP, TRUNCATE)에는 추가로 CLICKHOUSE_ALLOW_DROP=true이 필요합니다.

uv 없이 실행하기 (시스템 Python 사용)

uv 대신 시스템 Python 설치를 사용하려면 PyPI에서 패키지를 설치하고 직접 실행할 수 있습니다:

pip를 사용하여 패키지를 설치합니다:

python3 -m pip install mcp-clickhouse

chDB 지원도 설치하려면:

python3 -m pip install 'mcp-clickhouse[chdb]'

최신 버전으로 업그레이드하려면:

python3 -m pip install --upgrade mcp-clickhouse

Python을 직접 사용하도록 Claude Desktop 구성을 업데이트합니다:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "python3",
      "args": [
        "-m",
        "mcp_clickhouse.main"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

또는 설치된 스크립트를 직접 사용할 수 있습니다:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "mcp-clickhouse",
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_PORT": "<clickhouse-port>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_SECURE": "true",
        "CLICKHOUSE_VERIFY": "true",
        "CLICKHOUSE_CONNECT_TIMEOUT": "30",
        "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

참고: 시스템 PATH에 없는 경우 Python 실행 파일 또는 mcp-clickhouse 스크립트의 전체 경로를 사용해야 합니다. 다음을 사용하여 경로를 찾을 수 있습니다:

Python 실행 파일의 경우 which python3
설치된 스크립트의 경우 which mcp-clickhouse

사용자 정의 미들웨어

소스 코드를 수정하지 않고 MCP 서버에 사용자 정의 미들웨어를 추가할 수 있습니다. FastMCP는 MCP 프로토콜 메시지(도구 호출, 리소스 읽기, 프롬프트 등)를 가로채고 처리할 수 있는 미들웨어 시스템을 제공합니다.

사용 방법

Middleware을 확장하는 미들웨어 클래스와 setup_middleware(mcp) 함수가 있는 Python 모듈을 만듭니다:

# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())

MCP_MIDDLEWARE_MODULE 환경 변수를 모듈 이름으로 설정합니다(.py 확장자 제외):

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.10", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}

미들웨어 모듈이 Python의 가져오기 경로에 있는지 확인합니다(예: MCP 서버가 실행되는 동일한 디렉터리 또는 패키지로 설치).

예제 미들웨어

일반적인 패턴을 보여주는 예제 미들웨어 모듈이 example_middleware.py에 제공됩니다:

모든 MCP 요청 로깅
도구 호출 구체적 로깅
요청 처리 시간 측정

예제를 사용하려면:

"env": {
  "MCP_MIDDLEWARE_MODULE": "example_middleware"
}

미들웨어 기능

Middleware 기본 클래스는 다양한 MCP 작업에 대한 후크를 제공합니다:

on_message(context, call_next) - 모든 메시지에 대해 호출됨
on_request(context, call_next) - 모든 요청에 대해 호출됨
on_notification(context, call_next) - 모든 알림에 대해 호출됨
on_call_tool(context, call_next) - 도구가 실행될 때 호출됨
on_read_resource(context, call_next) - 리소스를 읽을 때 호출됨
on_get_prompt(context, call_next) - 프롬프트를 검색할 때 호출됨
on_list_tools(context, call_next) - 도구를 나열할 때 호출됨
on_list_resources(context, call_next) - 리소스를 나열할 때 호출됨
on_list_resource_templates(context, call_next) - 리소스 템플릿을 나열할 때 호출됨
on_list_prompts(context, call_next) - 프롬프트를 나열할 때 호출됨

각 후크는 메시지와 메타데이터를 포함하는 MiddlewareContext 객체와 파이프라인을 계속 진행하기 위한 call_next 함수를 받습니다.

컨텍스트 상태를 통한 동적 클라이언트 구성

미들웨어는 CLIENT_CONFIG_OVERRIDES_KEY 컨텍스트 상태 키를 사용하여 요청별로 ClickHouse 클라이언트 구성을 재정의할 수 있습니다. 서버는 이러한 재정의를 환경 변수의 기본 구성과 병합합니다.

from fastmcp.server.dependencies import get_context
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY

ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, {
    "connect_timeout": 60,
    "send_receive_timeout": 120
})

이를 통해 동적 시간 초과 조정, 테넌트별 라우팅 또는 사용자별 연결 설정과 같은 고급 사용 사례가 가능합니다.

개발

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 인스펙터로 쉽게 테스트하려면 fastmcp dev mcp_clickhouse/mcp_server.py을 실행하여 MCP 서버를 시작합니다.

HTTP 전송 및 상태 확인 엔드포인트로 테스트하려면:

# For development, disable authentication
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true python -m mcp_clickhouse.main

# Or with authentication (generate a token first)
CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_TOKEN="your-token" python -m mcp_clickhouse.main

# Then in another terminal:
curl http://localhost:8000/health

환경 변수

구성은 독립적인 그룹으로 나뉩니다. 이들을 혼동하는 것은 디버깅하기 어려운 연결 실패의 일반적인 원인입니다:

그룹	변수	제어 대상
ClickHouse 데이터베이스 연결	`CLICKHOUSE_HOST`, `CLICKHOUSE_PORT`, `CLICKHOUSE_SECURE`, `CLICKHOUSE_VERIFY`, …	이 MCP 서버가 HTTP 인터페이스를 통해 ClickHouse 클러스터에 연결하는 방법
MCP 서버 / 전송	`CLICKHOUSE_MCP_`, `FASTMCP_SERVER_AUTH`, `FASTMCP_SERVER_AUTH_`	MCP 전송, 인증 및 쿼리 도구 실행 제한
미들웨어 / chDB	`MCP_MIDDLEWARE_MODULE`, `CHDB_*`	선택적 확장

[!IMPORTANT] CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY 및 CLICKHOUSE_PORT과 같은 변수는 ClickHouse 데이터베이스 연결에만 적용됩니다. MCP 프로토콜 엔드포인트에 대한 TLS, 포트 또는 인증을 구성하지 않습니다.

예: MCP 서버가 TLS를 종료하는 인그레스 뒤의 Kubernetes에서 실행되는 경우 이는 MCP 전송 문제입니다. 파드가 ClickHouse 자체에 연결하는 방식에 맞게 CLICKHOUSE_SECURE을 유지하십시오(HTTPS → true, 일반 HTTP → false). MCP 서버가 인그레스 뒤에 있기 때문에 CLICKHOUSE_SECURE=false를 설정하면 서버가 HTTP를 통해 ClickHouse에 연결하게 되어 종종 HTTPS 전용 포트에 대해 연결이 이루어지고 서버 로그에 불투명한 HTTP/TLS 오류가 발생합니다.

ClickHouse 데이터베이스 연결

이 변수들은 clickhouse-connect HTTP 클라이언트와 run_query, list_databases, list_tables 같은 ClickHouse 기반 도구의 동작을 구성합니다.

필수 변수

CLICKHOUSE_HOST: ClickHouse 서버의 호스트명 (MCP 서버 바인드 주소가 아닌 데이터베이스 엔드포인트)
CLICKHOUSE_USER: ClickHouse 인증을 위한 사용자 이름
CLICKHOUSE_PASSWORD: ClickHouse 인증을 위한 비밀번호

[!CAUTION] MCP 데이터베이스 사용자를 데이터베이스에 연결하는 외부 클라이언트처럼 취급하여, 작업에 필요한 최소한의 권한만 부여하는 것이 중요합니다. 기본 사용자나 관리자 사용자의 사용은 항상 엄격히 피해야 합니다.

선택적 변수

CLICKHOUSE_PORT: ClickHouse 서버의 HTTP 인터페이스 포트
- 기본값: CLICKHOUSE_SECURE=true인 경우 8443, CLICKHOUSE_SECURE=false인 경우 8123
- 비표준 포트를 사용하지 않는 한 보통 설정할 필요가 없습니다
- HTTP 인터페이스 포트여야 하며, clickhouse-client에서 사용하는 네이티브 TCP 프로토콜 포트가 아닙니다
- 일반적인 값:
  - HTTP: 8123 (일반) / 8443 (TLS) — 이 서버와 ClickHouse Cloud HTTPS에서 사용
  - 네이티브 TCP (여기서는 지원되지 않음): 9000 (일반) / 9440 (TLS) — clickhouse-client에서 사용
- 서버가 Port 9000 is for clickhouse-client program로 응답하면 네이티브 프로토콜을 가리키는 것이므로 HTTP 포트(8123/8443 또는 배포 환경의 HTTP 매핑)로 전환하세요
CLICKHOUSE_ROLE: 인증에 사용할 ClickHouse 역할
- 기본값: 없음
- 사용자에게 특정 역할이 필요한 경우 설정하세요
CLICKHOUSE_SECURE: ClickHouse 데이터베이스 연결에 HTTPS 활성화 (MCP 클라이언트용이 아님)
- 기본값: "true"
- MCP 서버가 일반 HTTP를 통해 ClickHouse에 연결할 때만 "false"로 설정하세요 (로컬 Docker Compose에서 8123 포트를 사용하는 경우가 일반적)
- ClickHouse Cloud 및 모든 HTTPS 데이터베이스 엔드포인트의 경우 "true"로 두세요. MCP 서버 자체가 HTTP, stdio 또는 TLS를 별도로 종료하는 인그레스를 통해 노출되더라도 마찬가지입니다
- 이 플래그를 데이터베이스 포트와 잘못 일치시키는 것(예: CLICKHOUSE_SECURE=false를 포트 8443에 대해 사용)은 흔한 설정 실수이며, 보통 명확한 "잘못된 스킴" 메시지 대신 혼란스러운 HTTP 클라이언트 오류로 나타납니다
CLICKHOUSE_VERIFY: ClickHouse HTTPS 연결에 대한 SSL 인증서 검증 활성화/비활성화
- 기본값: "true"
- 인증서 검증을 비활성화하려면 "false"로 설정하세요 (프로덕션 환경에는 권장되지 않음)
- TLS 인증서: 이 패키지는 truststore를 통해 TLS 인증서 검증을 위해 운영 체제 신뢰 저장소를 사용합니다. 적절한 인증서 처리를 보장하기 위해 시작 시 truststore.inject_into_ssl()를 호출합니다. 예상치 못한 오류가 발생하는 경우에만 Python의 기본 SSL 동작이 폴백으로 사용됩니다.
CLICKHOUSE_SERVER_HOST_NAME: ClickHouse 연결에 대한 SNI 재정의 및 인증서 검증을 위한 서버 호스트명
- 기본값: 없음 (연결 호스트명 사용)
- 프록시나 로드 밸런서를 통해 연결할 때 인증서 호스트명이 연결 호스트명과 다른 경우 유용합니다. 설정하면 이 호스트명이 TLS 핸드셰이크 중 SNI(서버 이름 표시)와 인증서 호스트명 검증에 사용됩니다.
CLICKHOUSE_PROXY_PATH: ClickHouse HTTP 엔드포인트의 URL 경로 접두사
- 기본값: 없음
- ClickHouse HTTP 인터페이스가 경로 접두사(예: /clickhouse) 아래의 리버스 프록시 뒤에 노출될 때 설정하세요
CLICKHOUSE_CONNECT_TIMEOUT: ClickHouse 클라이언트의 연결 타임아웃(초)
- 기본값: "30"
- 연결 타임아웃이 발생하면 이 값을 늘리세요
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: ClickHouse 클라이언트의 송수신 타임아웃(초)
- 기본값: "300"
- 오래 실행되는 쿼리의 경우 이 값을 늘리세요
CLICKHOUSE_DATABASE: 사용할 기본 ClickHouse 데이터베이스
- 기본값: 없음 (서버 기본값 사용)
- 특정 데이터베이스에 자동으로 연결하려면 설정하세요
CLICKHOUSE_ENABLED: ClickHouse 데이터베이스 도구 활성화/비활성화
- 기본값: "true"
- chDB만 사용할 때 ClickHouse 도구를 비활성화하려면 "false"로 설정하세요
CLICKHOUSE_ALLOW_WRITE_ACCESS: ClickHouse에 대한 쓰기 작업(DDL 및 DML) 허용
- 기본값: "false"
- DDL(CREATE, ALTER, DROP) 및 DML(INSERT, UPDATE, DELETE) 작업을 허용하려면 "true"로 설정하세요
- 비활성화된 경우(기본값), 데이터 수정을 방지하기 위해 쿼리가 readonly=1 설정으로 실행됩니다
CLICKHOUSE_ALLOW_DROP: 파괴적인 작업(DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) 허용
- 기본값: "false"
- CLICKHOUSE_ALLOW_WRITE_ACCESS=true도 설정된 경우에만 적용됩니다
- 파괴적인 DROP 및 TRUNCATE 작업을 명시적으로 허용하려면 "true"로 설정하세요
- 이는 AI 탐색 중 실수로 데이터가 삭제되는 것을 방지하기 위한 안전 기능입니다

MCP 서버 및 전송

이 변수들은 전송, 인증, 쿼리 도구 실행 제한을 포함하여 MCP 프로세스 자체를 제어합니다. 위의 ClickHouse 데이터베이스 설정과는 독립적입니다. HTTP/SSE 전송을 위한 인증도 참조하세요.

CLICKHOUSE_MCP_SERVER_TRANSPORT: MCP 서버의 전송 방법 설정
- 기본값: "stdio"
- 유효한 옵션: "stdio", "http", "sse". MCP Inspector와 같은 도구를 사용한 로컬 개발에 유용합니다.
- stdio는 Claude Desktop에 일반적이며, http/sse는 네트워크 리스너를 노출합니다(아래의 바인드 호스트/포트)
CLICKHOUSE_MCP_BIND_HOST: HTTP 또는 SSE 전송 사용 시 MCP 서버를 바인딩할 호스트
- 기본값: "127.0.0.1"
- 모든 네트워크 인터페이스에 바인딩하려면 "0.0.0.0"로 설정하세요 (Docker 또는 원격 액세스에 유용)
- 전송이 "http" 또는 "sse"인 경우에만 사용됩니다 — CLICKHOUSE_HOST과는 관련 없음
CLICKHOUSE_MCP_BIND_PORT: HTTP 또는 SSE 전송 사용 시 MCP 서버를 바인딩할 포트
- 기본값: "8000"
- 전송이 "http" 또는 "sse"인 경우에만 사용됩니다 — CLICKHOUSE_PORT과는 관련 없음
CLICKHOUSE_MCP_QUERY_TIMEOUT: 쿼리 도구의 타임아웃(초)
- 기본값: "30"
- 무거운 쿼리에 대해 Query timed out after ... 오류가 발생하면 이 값을 늘리세요
CLICKHOUSE_MCP_AUTH_TOKEN: HTTP/SSE 전송을 위한 정적 베어러 토큰
- 기본값: 없음
- HTTP/SSE 전송에는 CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH, 또는 CLICKHOUSE_MCP_AUTH_DISABLED=true 중 하나가 필수입니다
- uuidgen 또는 openssl rand -hex 32를 사용하여 생성하세요
- 클라이언트는 이 토큰을 Authorization: Bearer <token> 헤더에 보내야 합니다
FASTMCP_SERVER_AUTH: FastMCP 인증 제공자에게 인증 위임
- 기본값: 없음
- 값은 AuthProvider 하위 클래스의 전체 클래스 경로입니다 (예: fastmcp.server.auth.providers.azure.AzureProvider 또는 fastmcp.server.auth.providers.google.GoogleProvider)
- 설정하면 FastMCP가 자체 FASTMCP_SERVER_AUTH_* 환경 변수에서 제공자를 자동으로 로드합니다. 이 모드에서는 CLICKHOUSE_MCP_AUTH_TOKEN을 설정하지 않은 상태로 두세요
CLICKHOUSE_MCP_AUTH_DISABLED: HTTP/SSE 전송에 대한 인증 비활성화
- 기본값: "false" (인증 활성화됨)
- 로컬 개발/테스트용으로만 인증을 비활성화하려면 "true"로 설정하세요
- 경고: 로컬 개발에만 사용하세요. 네트워크에 노출될 때는 비활성화하지 마세요

미들웨어 변수

MCP_MIDDLEWARE_MODULE: MCP 서버에 주입할 사용자 정의 미들웨어가 포함된 Python 모듈 이름
- 기본값: 없음 (미들웨어 로드되지 않음)
- 미들웨어 모듈의 모듈 이름(.py 확장자 없이)으로 설정하세요
- 모듈은 setup_middleware(mcp) 함수를 제공해야 합니다
- 자세한 내용과 예제는 사용자 정의 미들웨어를 참조하세요

chDB 변수

CHDB_ENABLED: chDB 기능 활성화/비활성화
- 기본값: "false"
- chDB 도구를 활성화하려면 "true"로 설정하세요
- 선택적 추가 설치 필요: mcp-clickhouse[chdb]
CHDB_DATA_PATH: chDB 데이터 디렉터리 경로
- 기본값: ":memory:" (인메모리 데이터베이스)
- 인메모리 데이터베이스에는 :memory:을 사용하세요
- 영구 저장소에는 파일 경로를 사용하세요 (예: /path/to/chdb/data)

일반적인 설정 함정

CLICKHOUSE_SECURE vs MCP / 인그레스 TLS — MCP 서버가 Kubernetes 인그레스, 리버스 프록시 뒤에 있거나 일반 HTTP를 통해 연결된다고 해서 CLICKHOUSE_SECURE를 끄는 것은 데이터베이스 TLS를 비활성화하지 않습니다. 이 프로세스가 ClickHouse에 연결하는 방식만 변경할 뿐입니다. 인그레스 TLS는 데이터베이스 클라이언트 설정과 별도로 구성하세요.
네이티브 프로토콜 포트 — CLICKHOUSE_PORT는 ClickHouse의 HTTP 인터페이스(기본적으로 8123/8443)를 대상으로 해야 합니다. 9000/9440 포트는 네이티브 TCP 프로토콜(clickhouse-client)용이며 이 서버에서는 작동하지 않습니다.
호스트 혼동 — CLICKHOUSE_HOST은 데이터베이스 호스트명입니다. CLICKHOUSE_MCP_BIND_HOST는 MCP HTTP/SSE 서버가 수신 대기하는 주소일 뿐입니다.

설정 예시

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)

chDB 전용(인메모리):

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
# CHDB_DATA_PATH defaults to :memory:

영구 저장소를 사용하는 chDB:

# chDB configuration
CHDB_ENABLED=true
CLICKHOUSE_ENABLED=false
CHDB_DATA_PATH=/path/to/chdb/data

HTTP 전송을 사용한 MCP Inspector 또는 원격 액세스:

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
CLICKHOUSE_MCP_BIND_PORT=4200  # Custom port (default: 8000)
CLICKHOUSE_MCP_AUTH_TOKEN=your-generated-token  # One auth mode required for HTTP/SSE (or FASTMCP_SERVER_AUTH, or CLICKHOUSE_MCP_AUTH_DISABLED=true)

HTTP 전송을 사용한 로컬 개발(인증 비활성화):

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!

HTTP 전송을 사용할 때 서버는 구성된 포트(기본값 8000)에서 실행됩니다. 예를 들어 위 구성의 경우:

MCP 엔드포인트: http://localhost:4200/mcp
상태 확인: http://localhost:4200/health

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

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.10",
        "mcp-clickhouse"
      ],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "CLICKHOUSE_DATABASE": "<optional-database>",
        "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio",
        "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1",
        "CLICKHOUSE_MCP_BIND_PORT": "8000"
      }
    }
  }
}

참고: 바인드 호스트 및 포트 설정은 전송이 "http" 또는 "sse"로 설정된 경우에만 사용됩니다.

테스트 실행

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 -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only