> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# ClickHouse MCP 서버 설정
> ClickHouse MCP 서버를 Claude Code, Claude Desktop, Codex, ChatGPT, Cursor 또는 Windsurf에 연결합니다.
[ClickHouse MCP 서버](https://github.com/ClickHouse/mcp-clickhouse)를 사용하면 호환되는 AI 어시스턴트가 데이터베이스를 탐색하고, 테이블을 확인하며, ClickHouse에서 SQL 쿼리를 실행할 수 있습니다.
이 가이드에서는 `uv`를 사용해 로컬 `stdio` 서버를 구성하고 주요 MCP 클라이언트에 연결하는 방법을 설명합니다.
서버는 기본적으로 읽기 전용 쿼리만 허용합니다.
AI 어시스턴트에 필요한 권한만 부여된 전용 ClickHouse 사용자를 사용하고, default 사용자나 관리자 사용자는 사용하지 마십시오.
다음 절차에서는 Claude Desktop을 사용한 설정을 안내합니다.
이 가이드에서 다루는 다른 클라이언트에도 동일한 ClickHouse 연결 정보를 사용합니다.
## 사전 요구 사항
시작하기 전에 다음을 준비하십시오.
1. [`uv`를 설치합니다](https://docs.astral.sh/uv/getting-started/installation/).
2. 사용할 MCP 클라이언트를 설치하십시오.
3. ClickHouse 서비스의 호스트명, 사용자 이름, 비밀번호를 확인하십시오.
아래 예시에서는 다음 자리 표시자 값을 사용합니다.
| 환경 변수 | 값 |
| --------------------- | -------------------------- |
| `CLICKHOUSE_HOST` | `your-clickhouse-host` |
| `CLICKHOUSE_USER` | `your-clickhouse-user` |
| `CLICKHOUSE_PASSWORD` | `your-clickhouse-password` |
실제 연결 정보로 바꾸십시오.
ClickHouse Cloud 서비스의 서버는 기본적으로 포트 `8443`에서 HTTPS를 사용합니다.
일반 HTTP를 사용하는 자가 관리형 서비스에서는 `CLICKHOUSE_SECURE=false`도 설정하고, 필요한 경우 `CLICKHOUSE_PORT=8123`도 설정하십시오.
## MCP 클라이언트 구성
터미널에서 다음 명령을 실행하세요.
```bash theme={null}
claude mcp add \
--transport stdio \
--env CLICKHOUSE_HOST=your-clickhouse-host \
--env CLICKHOUSE_USER=your-clickhouse-user \
--env CLICKHOUSE_PASSWORD=your-clickhouse-password \
--scope user \
mcp-clickhouse -- \
uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse
```
`claude mcp list`를 실행하여 연결을 확인하거나 Claude Code에서 `/mcp`를 입력하여 서버와 해당 도구를 살펴보십시오.
Claude Desktop에서 **설정**을 열고 **개발자**를 선택한 다음 **구성 편집**을 선택합니다.
`claude_desktop_config.json`에 다음 서버를 추가합니다:
```json theme={null}
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "your-clickhouse-host",
"CLICKHOUSE_USER": "your-clickhouse-user",
"CLICKHOUSE_PASSWORD": "your-clickhouse-password"
}
}
}
}
```
파일을 저장한 후 Claude Desktop을 다시 시작하십시오.
채팅 컴포저에서 **Connectors**를 열어 `mcp-clickhouse`를 사용할 수 있는지 확인하십시오.
Codex CLI에서 server를 추가합니다:
```bash theme={null}
codex mcp add mcp-clickhouse \
--env CLICKHOUSE_HOST=your-clickhouse-host \
--env CLICKHOUSE_USER=your-clickhouse-user \
--env CLICKHOUSE_PASSWORD=your-clickhouse-password \
-- uv run --with mcp-clickhouse --python 3.10 mcp-clickhouse
```
`codex mcp list`를 실행하여 연결을 확인하거나 Codex 터미널 UI에 `/mcp`를 입력하십시오.
Codex CLI, Codex IDE 확장 기능, ChatGPT 데스크톱 앱은 `~/.codex/config.toml`의 MCP 구성을 공유합니다.
ChatGPT 데스크톱 앱에서는 Codex 호스트용 로컬 MCP 서버를 구성합니다.
이 구성은 Codex CLI 및 Codex IDE 확장 기능과 공유됩니다.
ChatGPT 데스크톱 앱에서 다음을 수행하세요.
1. **Settings**를 열고 **MCP servers**를 선택하세요.
2. **Add server**를 선택한 후 **STDIO**를 선택하세요.
3. 이름에 `mcp-clickhouse`를 입력하고 명령으로 `uv`를 지정하세요.
4. 인수에 `run`, `--with`, `mcp-clickhouse`, `--python`, `3.10`, `mcp-clickhouse`를 순서대로 추가하세요.
5. 연결 정보로 `CLICKHOUSE_HOST`, `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`를 추가하세요.
6. 서버를 저장하고 앱을 다시 시작하세요.
앱이 다시 시작되면 Codex를 열고 컴포저에 `/mcp`를 입력하여 연결된 서버를 확인하세요.
이 단계에서는 ChatGPT 데스크톱 앱에서 Codex용 로컬 `stdio` 서버를 구성합니다.
ChatGPT 웹에서는 플러그인이 제공하는 원격 MCP 기반 도구를 사용합니다.
ChatGPT 웹에서 ClickHouse 도구를 사용하려면 [ClickHouse Cloud의 원격 MCP 서버](/ko/products/cloud/features/ai-ml/remote-mcp)를 참조하세요.
현재 프로젝트의 `.cursor/mcp.json` 또는 전역 Cursor MCP 구성에 다음 서버를 추가하십시오.
```json theme={null}
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "your-clickhouse-host",
"CLICKHOUSE_USER": "your-clickhouse-user",
"CLICKHOUSE_PASSWORD": "your-clickhouse-password"
}
}
}
}
```
Cursor를 다시 시작한 후 MCP 설정을 열어 서버가 활성화되어 있는지 확인하십시오.
`~/.codeium/windsurf/mcp_config.json`에 다음 서버를 추가하십시오:
```json theme={null}
{
"mcpServers": {
"mcp-clickhouse": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-clickhouse",
"--python",
"3.10",
"mcp-clickhouse"
],
"env": {
"CLICKHOUSE_HOST": "your-clickhouse-host",
"CLICKHOUSE_USER": "your-clickhouse-user",
"CLICKHOUSE_PASSWORD": "your-clickhouse-password"
}
}
}
}
```
Windsurf를 다시 시작한 후 MCP 설정을 열어 서버가 활성화되어 있는지 확인하십시오.
## 연결 확인
클라이언트가 `mcp-clickhouse`에 연결되었다고 보고하면 다음을 요청하십시오.
```text theme={null}
List the databases available in ClickHouse, then show me the tables in one of them.
```
클라이언트에서 최초 도구 호출에 대한 승인을 요청할 수 있습니다.
액세스를 허용하기 전에 모든 요청을 검토하십시오.
## 문제 해결
클라이언트가 `uv`를 찾을 수 없다고 보고하는 경우, 명령어나 구성의 `uv`를 절대 경로로 바꾸십시오.
해당 경로를 찾으려면 macOS 또는 Linux에서 `which uv`를, Windows에서 `where uv`를 실행하십시오.
추가 연결 설정, 선택적 chDB 지원, HTTP 전송 및 인증에 대해서는 [`mcp-clickhouse` README](https://github.com/ClickHouse/mcp-clickhouse)를 참조하십시오.