ClickHouse MCP Server

ClickHouse용 MCP 서버입니다.

기능

ClickHouse 도구

• run_query

  • ClickHouse 클러스터에서 SQL 쿼리를 실행합니다.

  • 입력: query (string): 실행할 SQL 쿼리입니다.

  • 쿼리는 기본적으로 읽기 전용 모드로 실행되지만(CLICKHOUSE_ALLOW_WRITE_ACCESS=false), 필요 시 쓰기를 명시적으로 활성화할 수 있습니다.

• list_databases

  • ClickHouse 클러스터의 모든 데이터베이스를 나열합니다.

• list_tables

  • 데이터베이스의 테이블을 페이지네이션으로 나열합니다.

  • 필수 입력: database (string).

  • 선택 입력:

    • like / not_like (string): 테이블 이름에 LIKE 또는 NOT LIKE 필터를 적용합니다.

    • page_token (string): 다음 페이지를 가져오기 위해 이전 호출에서 반환된 토큰입니다.

    • page_size (int, 기본값 50): 페이지당 반환되는 테이블 수입니다.

    • include_detailed_columns (bool, 기본값 true): false로 설정하면 전체 create_table_query는 유지하면서 응답을 가볍게 하기 위해 컬럼 메타데이터를 생략합니다.

  • 응답 형태:

    • tables: 현재 페이지의 테이블 객체 배열입니다.

    • next_page_token: 다음 페이지를 가져오려면 이 값을 다시 전달하거나, 더 이상 테이블이 없으면 null입니다.

    • total_tables: 제공된 필터와 일치하는 테이블의 총 개수입니다.

chDB 도구

• run_chdb_select_query

  • chDB의 임베디드 ClickHouse 엔진을 사용하여 SQL 쿼리를 실행합니다.

  • 입력: query (string): 실행할 SQL 쿼리입니다.

  • ETL 프로세스 없이 다양한 소스(파일, URL, 데이터베이스)의 데이터를 직접 쿼리합니다.

  • 선택적 chdb 확장이 필요합니다: pip install 'mcp-clickhouse[chdb]'

헬스 체크 엔드포인트

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

• 서버가 정상이고 ClickHouse에 연결할 수 있으면 200 OK(본문: OK)를 반환합니다.

• 서버가 ClickHouse에 연결할 수 없으면 일반 오류 메시지와 함께 503 Service Unavailable을 반환합니다.

이 엔드포인트에 대한 GET 및 HEAD 요청은 의도적으로 인증 없이 허용되며 Host 및 Origin 검증에서 제외됩니다. 따라서 오케스트레이터 프로브(예: Kubernetes liveness/readiness, 로드 밸런서)가 추가 구성 없이 런타임에 할당된 파드 또는 대상 IP를 사용할 수 있습니다. /health는 예약되어 있으며 MCP 전송 경로로 사용할 수 없습니다. 응답 본문은 백엔드 버전 문자열이나 오류 세부 정보가 유출되지 않도록 의도적으로 최소화되어 있습니다. 실패 디버깅은 서버 로그를 통해 수행하세요.

예시:

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

Related MCP server: ClickHouse MCP Server

보안

HTTP/SSE 전송 인증

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

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

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

인증 설정

1. 보안 토큰을 생성합니다(임의의 문자열이어도 됩니다):

# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

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

export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

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

HTTP/SSE 전송을 사용하는 Claude Desktop의 경우:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}

참고: /health 엔드포인트는 의도적으로 인증 없이 접근할 수 있습니다(위의 헬스 체크 엔드포인트 참조). 베어러 토큰 인증이 실제로 인증되지 않은 요청을 거부하는지 확인하려면 MCP Inspector 등으로 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
export CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

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

구성

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

1. 다음 위치에 있는 Claude Desktop 구성 파일을 엽니다:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%/Claude/claude_desktop_config.json

2. 다음을 추가합니다:

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

3. uv의 명령 항목을 찾아 uv 실행 파일의 절대 경로로 바꿉니다. 이렇게 하면 서버 시작 시 올바른 버전의 uv가 사용됩니다. Mac에서는 which uv를 사용하여 이 경로를 찾을 수 있습니다.

4. 변경 사항을 적용하려면 Claude Desktop을 다시 시작합니다.

선택적 쓰기 액세스

기본적으로 이 MCP는 읽기 전용 쿼리를 강제하므로 탐색 중에 실수로 데이터가 변경되는 일이 없습니다. DDL 또는 INSERT 문을 허용하려면 CLICKHOUSE_ALLOW_WRITE_ACCESS 환경 변수를 true로 설정하세요. ClickHouse 인스턴스 자체에서 쓰기를 허용하지 않으면 서버는 계속 읽기 전용 모드를 강제합니다.

파괴적 작업 보호

쓰기 액세스가 활성화된 경우(CLICKHOUSE_ALLOW_WRITE_ACCESS=true)에도 파괴적 작업은 안전을 위해 추가 옵트인 플래그가 필요합니다. 이 검사는 모든 DROP 문(ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN 절 포함), 모든 TRUNCATE, DELETE 및 UPDATE(경량 문과 ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE 뮤테이션 모두), REPLACE TABLE, CREATE OR REPLACE, ALTER TABLE ... REPLACE PARTITION, ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION, DETACH ... PERMANENTLY를 포함합니다. 문자열 리터럴, 따옴표로 묶인 식별자, SQL 주석 안의 키워드는 무시되므로 검사를 트리거하지도 않고 문장을 검사에서 숨기지도 않습니다.

이 검사는 MCP 서버에서 실행되며 사고를 방지하기 위한 최선의 노력(best-effort) 가드입니다. 보안 경계는 아닙니다. 보안 경계는 ClickHouse 사용자의 권한(grants)입니다. 읽기 전용 모드(기본값)는 readonly=1을 통해 서버 측에서 강제됩니다. 파괴적 작업 게이트는 서버 측에서 강제되지 않습니다.

쓰기 모드의 경우 MCP 서버에 필요한 권한만 가진 전용 ClickHouse 사용자를 부여하세요:

CREATE USER mcp_agent IDENTIFIED BY '...';
GRANT SELECT, INSERT, CREATE TABLE, ALTER ADD COLUMN ON mydb.* TO mcp_agent;

그러면 이러한 권한 밖의 모든 문은 MCP 플래그와 관계없이 서버 측에서 ACCESS_DENIED로 실패합니다. 서버 설정 max_table_size_to_drop 및 max_partition_size_to_drop도 설정 제약 조건으로 고정하면 피해 범위를 제한할 수 있습니다.

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

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

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

• 쓰기 작업(INSERT, CREATE, ALTER ADD COLUMN)에는 CLICKHOUSE_ALLOW_WRITE_ACCESS=true가 필요합니다.

• 파괴적 작업(DROP, TRUNCATE, DELETE, UPDATE 및 위 목록의 나머지)에는 추가로 CLICKHOUSE_ALLOW_DROP=true가 필요합니다.

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

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

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

python3 -m pip install mcp-clickhouse

chDB 지원도 함께 설치하려면:

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

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

python3 -m pip install --upgrade mcp-clickhouse

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

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

• which python3: Python 실행 파일 경로

• which mcp-clickhouse: 설치된 스크립트 경로

사용자 정의 미들웨어

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

사용 방법

1. 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())

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

3. 미들웨어 모듈이 Python의 import 경로에 있는지 확인합니다(예: 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
})

이를 통해 동적 타임아웃 조정, 테넌트별 라우팅, 사용자별 연결 설정과 같은 고급 사용 사례가 가능합니다.

상태 값은 딕셔너리여야 합니다. 중첩된 settings 및 generic_args 값은 매핑이어야 하며 기본 구성과 병합됩니다. 잘못된 값이 있으면 ClickHouse 클라이언트가 생성되기 전에 도구 호출이 실패합니다. CLICKHOUSE_ROLE은 재정의가 명시적으로 settings.role을 제공하지 않는 한 계속 활성 상태로 유지됩니다. 최상위 role 및 ch_role 키와 generic_args 아래의 동일한 키는 거부됩니다.

이러한 재정의를 신뢰할 수 있는 미들웨어 입력으로 취급하세요. 미들웨어는 설정하기 전에 요청에서 파생된 값을 인증하고 권한을 부여해야 합니다. 요청별 ClickHouse 역할은 연결 구성이지 테넌트 인증 경계가 아닙니다. ClickHouse 사용자, 역할 및 권한 부여(grants)로 테넌트 격리를 적용하세요.

개발

1. test-services 디렉터리에서 docker compose up -d를 실행하여 ClickHouse 클러스터를 시작합니다.

2. 리포지토리 루트의 .env 파일에 다음 변수를 추가합니다.

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

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

3. uv sync를 실행하여 종속성을 설치합니다. uv를 설치하려면 여기의 지침을 따르세요. 그런 다음 source .venv/bin/activate를 실행합니다.

4. MCP Inspector로 쉽게 테스트하려면 fastmcp dev mcp_clickhouse/mcp_server.py를 실행하여 MCP 서버를 시작합니다.

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

   # For development, disable authentication
   CLICKHOUSE_MCP_SERVER_TRANSPORT=http CLICKHOUSE_MCP_AUTH_DISABLED=true CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000 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

환경 변수

구성은 독립적인 그룹으로 나뉩니다. 이를 혼동하면 디버깅하기 어려운 연결 오류가 자주 발생합니다.

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

예: MCP 서버가 TLS를 종료하는 인그레스 뒤의 Kubernetes에서 실행되는 경우 이는 MCP 전송 문제입니다. CLICKHOUSE_SECURE를 파드가 ClickHouse 자체에 도달하는 방식(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

  • 비표준 포트를 사용하지 않는 한 일반적으로 설정할 필요가 없습니다

  • clickhouse-client가 사용하는 네이티브 TCP 프로토콜 포트가 아닌 HTTP 인터페이스 포트여야 합니다

  • 일반적인 값:

    • 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 역할

  • 기본값: None

  • 사용자가 특정 역할을 요구하는 경우 설정하세요

• CLICKHOUSE_SECURE: ClickHouse 데이터베이스 연결에 대해 HTTPS 활성화(MCP 클라이언트용 아님)

  • 기본값: "true"

  • MCP 서버가 일반 HTTP로 ClickHouse에 도달하는 경우에만 "false"로 설정하세요(포트 8123의 로컬 Docker Compose에서 일반적)

  • ClickHouse Cloud 및 모든 HTTPS 데이터베이스 엔드포인트에 대해서는 "true"로 유지하세요 — MCP 서버 자체가 HTTP, stdio 또는 TLS를 별도로 종료하는 인그레스를 통해 노출되더라도 마찬가지입니다

  • 이 플래그를 데이터베이스 포트와 일치하지 않게 설정하는 것(예: 포트 8443에 대해 CLICKHOUSE_SECURE=false)은 흔한 설정 실수이며, 일반적으로 명확한 "잘못된 스킴" 메시지 대신 혼란스러운 HTTP 클라이언트 오류로 나타납니다

• CLICKHOUSE_VERIFY: ClickHouse HTTPS 연결에 대한 SSL 인증서 검증 활성화/비활성화

  • 기본값: "true"

  • 인증서 검증을 비활성화하려면 "false"로 설정하세요(프로덕션에는 권장되지 않음)

  • TLS 인증서: 이 패키지는 truststore를 통해 TLS 인증서 검증에 운영 체제 신뢰 저장소를 사용합니다. 올바른 인증서 처리를 보장하기 위해 시작 시 truststore.inject_into_ssl()을 호출합니다. 예기치 않은 오류가 발생하는 경우에만 Python의 기본 SSL 동작이 폴백으로 사용됩니다.

• CLICKHOUSE_SERVER_HOST_NAME: ClickHouse 연결에 대한 SNI 재정의 및 인증서 검증용 서버 호스트 이름

  • 기본값: None(연결 호스트 이름 사용)

  • 인증서 호스트 이름이 연결 호스트 이름과 다른 프록시 또는 로드 밸런서를 통해 연결할 때 유용합니다. 설정하면 이 호스트 이름은 TLS 핸드셰이크 중 SNI(Server Name Indication)와 인증서 호스트 이름 검증 모두에 사용됩니다.

• CLICKHOUSE_PROXY_PATH: ClickHouse HTTP 엔드포인트의 URL 경로 접두사

  • 기본값: None

  • ClickHouse HTTP 인터페이스가 경로 접두사(예: /clickhouse) 아래의 리버스 프록시 뒤에 노출된 경우 설정하세요

• CLICKHOUSE_CONNECT_TIMEOUT: ClickHouse 클라이언트의 연결 제한 시간(초)

  • 기본값: "30"

  • 연결 시간 초과가 발생하면 이 값을 늘리세요

• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: ClickHouse 클라이언트의 송신/수신 제한 시간(초)

  • 기본값: "300"

  • 장기 실행 쿼리의 경우 이 값을 늘리세요

• CLICKHOUSE_DATABASE: 사용할 기본 ClickHouse 데이터베이스

  • 기본값: None(서버 기본값 사용)

  • 특정 데이터베이스에 자동으로 연결하려면 설정하세요

• CLICKHOUSE_ENABLED: ClickHouse 데이터베이스 도구 활성화/비활성화

  • 기본값: "true"

  • chDB만 사용할 때 ClickHouse 도구를 비활성화하려면 "false"로 설정하세요

• CLICKHOUSE_ALLOW_WRITE_ACCESS: ClickHouse에 대한 쓰기 작업(DDL 및 DML) 허용

  • 기본값: "false"

  • 비파괴적 DDL 및 DML(CREATE, INSERT, ALTER ADD COLUMN)을 허용하려면 "true"로 설정하세요. 파괴적 문은 추가로 CLICKHOUSE_ALLOW_DROP=true가 필요합니다

  • 비활성화된 경우(기본값) 데이터 수정을 방지하기 위해 쿼리가 readonly=1 설정으로 실행됩니다

• CLICKHOUSE_ALLOW_DROP: 파괴적 작업 허용(모든 DROP 또는 TRUNCATE, ALTER TABLE 변형을 포함한 DELETE 및 UPDATE, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION, 및 DETACH ... PERMANENTLY)

  • 기본값: "false"

  • CLICKHOUSE_ALLOW_WRITE_ACCESS=true도 설정된 경우에만 적용됩니다

  • 이 게이트는 MCP 서버의 최선 노력(best-effort) 사고 방지 장치이지 보안 경계가 아닙니다. 실제 강제 적용을 위해 ClickHouse 사용자의 권한을 제한하세요(파괴적 작업 보호 참조)

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"로 설정합니다.

  • 경고: 로컬 개발에서만 사용하세요. 네트워크에 노출된 경우 비활성화하지 마세요.

• CLICKHOUSE_MCP_ALLOWED_HOSTS: HTTP/SSE 서버가 응답하는 쉼표로 구분된 Host 헤더 값

  • 루프백 바인드의 기본값: 127.0.0.1, localhost, [::1]의 포트 없는 형식 및 모든 포트 형식

  • 설정하는 경우 값에 Host 항목이 하나 이상 포함되어야 합니다.

  • 구체적인 비루프백 바인드 주소는 해당 주소와 구성된 포트를 기본값으로 사용합니다. 0.0.0.0 또는 :: 같은 와일드카드 바인드는 공개 Host를 추론할 수 없으므로 명시적인 비어 있지 않은 값이 필요합니다.

  • Host 검증은 DNS 리바인딩에 대한 심층 방어입니다. 아래의 Origin 검증은 MCP에서 별도로 요구합니다.

  • 항목은 정확히 일치(localhost:8000)하거나 모든 포트를 허용(localhost:*)합니다. 예: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

  • host:* 형식은 포트가 있는 값만 일치합니다. 포트가 없는 Host(클라이언트가 :80/:443을 생략하는 표준 포트 배포)도 포트 없는 정확 일치 항목(example.com)으로 나열해야 합니다.

  • 일치하지 않거나 누락된 Host 헤더가 있는 요청은 421 Misdirected Request를 받습니다. /health에 대한 GET 및 HEAD 요청은 Host 및 Origin 검증에서 제외되므로 오케스트레이터 프로브가 계속 작동합니다.

  • 리버스 프록시 뒤에서는 프록시가 전달하는 Host 값을 나열하세요. fastmcp run 같은 실행기가 원격 액세스를 위해 바인드 주소를 재정의하는 경우 명시적인 목록을 설정하세요.

• CLICKHOUSE_MCP_ALLOWED_ORIGINS: HTTP/SSE에서 허용되는 쉼표로 구분된 Origin 헤더 값

  • 기본값: 없음. Origin 헤더가 있는 모든 요청을 거부합니다.

  • MCP는 HTTP/SSE 전송 연결에 Origin 검증을 요구합니다. Origin이 없는 요청은 허용되는데, 브라우저가 아닌 MCP 클라이언트는 일반적으로 이를 생략하기 때문입니다. 일치하지 않는 Origin은 403 Forbidden을 받습니다. /health 엔드포인트는 위에서 설명한 대로 제외됩니다.

  • 항목은 정확히 일치(http://localhost:3000)하거나 모든 포트를 허용(http://localhost:*)합니다. 호스트와 마찬가지로 모든 포트 형식은 포트가 있는 origin만 일치하며, 표준 포트 origin(https://app.example.com)은 정확히 나열해야 합니다.

미들웨어 변수

• 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

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

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)
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:4200,localhost:4200,mcp.example.com:4200  # Include every Host value clients and proxies send

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

CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse
CLICKHOUSE_MCP_SERVER_TRANSPORT=http
CLICKHOUSE_MCP_AUTH_DISABLED=true  # Only for local development!
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

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

• MCP 엔드포인트: http://localhost:8000/mcp

• 헬스 체크: http://localhost:8000/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

YouTube 개요