ClickHouse

resmi

Kueri server basis data ClickHouse Anda.

GitHub

839

Apa yang bisa Anda lakukan dengan Click House MCP?

Jalankan kueri SQL hanya-baca — Minta asisten untuk mengeksekusi kueri SELECT apa pun terhadap klaster ClickHouse Anda menggunakan run_query.
Daftar basis data dan tabel — Jelajahi skema Anda dengan mendaftar semua basis data menggunakan list_databases atau melakukan paginasi melalui tabel dalam basis data tertentu dengan list_tables.
Kueri file dan URL secara langsung melalui chDB — Gunakan run_chdb_select_query untuk menjalankan SQL terhadap file lokal atau sumber data jarak jauh tanpa memuatnya ke ClickHouse terlebih dahulu.
Kontrol operasi tulis dan destruktif — Aktifkan CLICKHOUSE_ALLOW_WRITE_ACCESS untuk DDL/DML, dan secara opsional CLICKHOUSE_ALLOW_DROP untuk mengizinkan pernyataan DROP atau TRUNCATE selama sesi berbantuan AI.

Dokumentasi

Server MCP ClickHouse

Server MCP untuk ClickHouse.

Fitur

Alat ClickHouse

run_query
- Jalankan kueri SQL di klaster ClickHouse Anda.
- Masukan: query (string): Kueri SQL yang akan dijalankan.
- Kueri berjalan dalam mode hanya-baca secara default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), tetapi penulisan dapat diaktifkan secara eksplisit jika diperlukan.
list_databases
- Tampilkan semua basis data di klaster ClickHouse Anda.
list_tables
- Tampilkan tabel dalam basis data dengan paginasi.
- Masukan wajib: database (string).
- Masukan opsional:
  - like / not_like (string): Terapkan filter LIKE atau NOT LIKE pada nama tabel.
  - page_token (string): Token yang dikembalikan oleh panggilan sebelumnya untuk mengambil halaman berikutnya.
  - page_size (int, default 50): Jumlah tabel yang dikembalikan per halaman.
  - include_detailed_columns (bool, default true): Saat false, menghilangkan metadata kolom untuk respons yang lebih ringan namun tetap menyertakan create_table_query lengkap.
- Bentuk respons:
  - tables: Array objek tabel untuk halaman saat ini.
  - next_page_token: Berikan nilai ini kembali untuk mengambil halaman berikutnya, atau null jika tidak ada tabel lagi.
  - total_tables: Jumlah total tabel yang cocok dengan filter yang diberikan.

Alat chDB

run_chdb_select_query
- Jalankan kueri SQL menggunakan mesin ClickHouse tertanam chDB.
- Masukan: query (string): Kueri SQL yang akan dijalankan.
- Kueri data langsung dari berbagai sumber (file, URL, basis data) tanpa proses ETL.
- Memerlukan tambahan opsional chdb: pip install 'mcp-clickhouse[chdb]'

Endpoint Pemeriksaan Kesehatan

Saat berjalan dengan transport HTTP atau SSE, endpoint pemeriksaan kesehatan tersedia di /health. Endpoint ini:

Mengembalikan 200 OK (body: OK) jika server sehat dan dapat terhubung ke ClickHouse
Mengembalikan 503 Service Unavailable dengan pesan kesalahan generik jika server tidak dapat terhubung ke ClickHouse

Endpoint sengaja tidak diautentikasi agar probe orkestrator (misalnya liveness/readiness Kubernetes, load balancer) dapat menjangkaunya tanpa kredensial. Body respons sengaja dibuat minimal untuk menghindari kebocoran string versi backend atau detail kesalahan; debug kegagalan melalui log server.

Contoh:

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

Keamanan

Autentikasi untuk Transport HTTP/SSE

Saat menggunakan transport HTTP atau SSE, autentikasi diwajibkan secara default. Transport stdio (default) tidak memerlukan autentikasi karena hanya berkomunikasi melalui input/output standar.

Tiga mode autentikasi didukung. Pilih salah satu:

Mode	Kapan digunakan	Env var
Token bearer statis	Deployment sederhana, layanan internal	`CLICKHOUSE_MCP_AUTH_TOKEN`
OAuth / OIDC (via FastMCP)	Azure Entra, Google, GitHub, WorkOS, dll.	`FASTMCP_SERVER_AUTH=<provider-class-path>` (+ variabel `FASTMCP_SERVER_AUTH_*` spesifik penyedia)
Dinonaktifkan	Hanya pengembangan lokal	`CLICKHOUSE_MCP_AUTH_DISABLED=true`

Startup gagal jika tidak ada yang dikonfigurasi untuk transport HTTP/SSE.

Menyiapkan Autentikasi

Buat token aman (bisa berupa string acak apa pun):

# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

Konfigurasikan server dengan token:

export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

Konfigurasikan klien MCP Anda untuk menyertakan token dalam permintaan:

Untuk Claude Desktop dengan transport HTTP/SSE:
```
{
  "mcpServers": {
    "mcp-clickhouse": {
      "url": "http://127.0.0.1:8000",
      "headers": {
        "Authorization": "Bearer your-generated-token"
      }
    }
  }
}
```
Catatan: endpoint /health sengaja tidak diautentikasi (lihat Endpoint Pemeriksaan Kesehatan di atas). Untuk memverifikasi bahwa autentikasi token bearer benar-benar menolak permintaan yang tidak diautentikasi, akses endpoint MCP itu sendiri misalnya dengan MCP Inspector, atau dengan mengirimkan permintaan JSON-RPC POST ke /mcp dengan dan tanpa header Authorization dan konfirmasikan bahwa panggilan yang tidak diautentikasi mengembalikan 401.

OAuth / OIDC via FastMCP

Untuk deployment produksi dengan penyedia identitas (Azure Entra, Google, GitHub, WorkOS, dll.), delegasikan autentikasi ke penyedia autentikasi bawaan FastMCP alih-alih menggunakan token statis. Atur FASTMCP_SERVER_AUTH ke jalur kelas lengkap penyedia autentikasi FastMCP, bersama dengan variabel FASTMCP_SERVER_AUTH_* spesifik penyedia, dan biarkan CLICKHOUSE_MCP_AUTH_TOKEN tidak disetel.

Contoh (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>"

Lihat dokumentasi FastMCP untuk daftar lengkap penyedia dan variabel lingkungan yang diperlukan.

Mode Pengembangan (Menonaktifkan Autentikasi)

Hanya untuk pengembangan dan pengujian lokal, Anda dapat menonaktifkan autentikasi dengan mengatur:

export CLICKHOUSE_MCP_AUTH_DISABLED=true

PERINGATAN: Hanya gunakan ini untuk pengembangan lokal. Jangan nonaktifkan autentikasi saat server terpapar ke jaringan mana pun.

Konfigurasi

Server MCP ini mendukung ClickHouse dan chDB. Anda dapat mengaktifkan salah satu atau keduanya sesuai kebutuhan.

Buka file konfigurasi Claude Desktop yang terletak di:
- Di macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Di Windows: %APPDATA%/Claude/claude_desktop_config.json
Tambahkan yang berikut:

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

Perbarui variabel lingkungan untuk mengarah ke layanan ClickHouse Anda sendiri.

Atau, jika Anda ingin mencobanya dengan ClickHouse SQL Playground, Anda dapat menggunakan konfigurasi berikut:

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

Untuk chDB (mesin ClickHouse tertanam), tambahkan konfigurasi berikut:

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

Anda juga dapat mengaktifkan ClickHouse dan chDB secara bersamaan:

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

Temukan entri perintah untuk uv dan ganti dengan jalur absolut ke file yang dapat dieksekusi uv. Ini memastikan bahwa versi uv yang benar digunakan saat memulai server. Di mac, Anda dapat menemukan jalur ini menggunakan which uv.
Mulai ulang Claude Desktop untuk menerapkan perubahan.

Akses Tulis Opsional

Secara default, MCP ini memberlakukan kueri hanya-baca sehingga mutasi yang tidak disengaja tidak dapat terjadi selama eksplorasi. Untuk mengizinkan pernyataan DDL atau INSERT/UPDATE, atur variabel lingkungan CLICKHOUSE_ALLOW_WRITE_ACCESS ke true. Server tetap memberlakukan mode hanya-baca jika instans ClickHouse itu sendiri melarang penulisan.

Perlindungan Operasi Destruktif

Bahkan ketika akses tulis diaktifkan (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), operasi destruktif (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) memerlukan flag opt-in tambahan demi keamanan. Ini mencegah penghapusan data yang tidak disengaja selama eksplorasi AI.

Untuk mengaktifkan operasi destruktif, atur kedua flag:

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

Pendekatan dua tingkat ini memastikan bahwa penghapusan yang tidak disengaja sangat sulit terjadi:

Operasi tulis (INSERT, UPDATE, CREATE) memerlukan CLICKHOUSE_ALLOW_WRITE_ACCESS=true
Operasi destruktif (DROP, TRUNCATE) juga memerlukan CLICKHOUSE_ALLOW_DROP=true

Menjalankan Tanpa uv (Menggunakan Python Sistem)

Jika Anda lebih suka menggunakan instalasi Python sistem alih-alih uv, Anda dapat menginstal paket dari PyPI dan menjalankannya secara langsung:

Instal paket menggunakan pip:

python3 -m pip install mcp-clickhouse

Untuk menginstal dukungan chDB juga:

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

Untuk meningkatkan ke versi terbaru:

python3 -m pip install --upgrade mcp-clickhouse

Perbarui konfigurasi Claude Desktop Anda untuk menggunakan Python secara langsung:

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

Atau, Anda dapat menggunakan skrip yang terinstal secara langsung:

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

Catatan: Pastikan untuk menggunakan jalur lengkap ke file yang dapat dieksekusi Python atau skrip mcp-clickhouse jika tidak ada di PATH sistem Anda. Anda dapat menemukan jalurnya menggunakan:

which python3 untuk file yang dapat dieksekusi Python
which mcp-clickhouse untuk skrip yang terinstal

Middleware Kustom

Anda dapat menambahkan middleware kustom ke server MCP tanpa mengubah kode sumber. FastMCP menyediakan sistem middleware yang memungkinkan Anda mencegat dan memproses pesan protokol MCP (panggilan alat, pembacaan sumber daya, prompt, dll.).

Cara Menggunakan

Buat modul Python dengan kelas middleware yang memperluas Middleware dan fungsi setup_middleware(mcp):

# 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())

Atur variabel lingkungan MCP_MIDDLEWARE_MODULE ke nama modul (tanpa ekstensi .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"
      }
    }
  }
}

Pastikan modul middleware Anda berada di jalur impor Python (misalnya, di direktori yang sama tempat server MCP berjalan, atau diinstal sebagai paket).

Contoh Middleware

Modul middleware contoh disediakan di example_middleware.py yang menunjukkan pola umum:

Mencatat semua permintaan MCP
Mencatat panggilan alat secara spesifik
Mengukur waktu pemrosesan permintaan

Untuk menggunakan contoh:

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

Kemampuan Middleware

Kelas dasar Middleware menyediakan hook untuk berbagai operasi MCP:

on_message(context, call_next) - Dipanggil untuk semua pesan
on_request(context, call_next) - Dipanggil untuk semua permintaan
on_notification(context, call_next) - Dipanggil untuk semua notifikasi
on_call_tool(context, call_next) - Dipanggil saat alat dieksekusi
on_read_resource(context, call_next) - Dipanggil saat sumber daya dibaca
on_get_prompt(context, call_next) - Dipanggil saat prompt diambil
on_list_tools(context, call_next) - Dipanggil saat mendaftar alat
on_list_resources(context, call_next) - Dipanggil saat mendaftar sumber daya
on_list_resource_templates(context, call_next) - Dipanggil saat mendaftar templat sumber daya
on_list_prompts(context, call_next) - Dipanggil saat mendaftar prompt

Setiap hook menerima objek MiddlewareContext yang berisi pesan dan metadata, dan fungsi call_next untuk melanjutkan pipeline.

Konfigurasi Klien Dinamis via Context State

Middleware dapat mengganti konfigurasi klien ClickHouse berdasarkan per-permintaan menggunakan kunci context state CLIENT_CONFIG_OVERRIDES_KEY. Server menggabungkan penggantian ini dengan konfigurasi dasar dari variabel lingkungan.

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
})

Ini memungkinkan kasus penggunaan lanjutan seperti penyesuaian batas waktu dinamis, perutean spesifik penyewa, atau pengaturan koneksi per pengguna.

Pengembangan

Di direktori test-services jalankan docker compose up -d untuk memulai klaster ClickHouse.
Tambahkan variabel berikut ke file .env di root repositori.

Catatan: Penggunaan pengguna default dalam konteks ini hanya ditujukan untuk tujuan pengembangan lokal.

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

Jalankan uv sync untuk menginstal dependensi. Untuk menginstal uv ikuti petunjuk di sini. Kemudian lakukan source .venv/bin/activate.
Untuk pengujian mudah dengan MCP Inspector, jalankan fastmcp dev mcp_clickhouse/mcp_server.py untuk memulai server MCP.

Untuk menguji dengan transport HTTP dan endpoint pemeriksaan kesehatan:

# 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

Variabel Lingkungan

Konfigurasi dibagi menjadi beberapa grup independen. Mencampuradukkannya adalah penyebab umum kegagalan koneksi yang sulit di-debug:

Grup	Variabel	Mengontrol
Koneksi basis data ClickHouse	`CLICKHOUSE_HOST`, `CLICKHOUSE_PORT`, `CLICKHOUSE_SECURE`, `CLICKHOUSE_VERIFY`, …	Bagaimana server MCP ini terhubung ke klaster ClickHouse Anda melalui antarmuka HTTP
Server MCP / transport	`CLICKHOUSE_MCP_`, `FASTMCP_SERVER_AUTH`, `FASTMCP_SERVER_AUTH_`	Transport MCP, autentikasi, dan batas eksekusi alat kueri
Middleware / chDB	`MCP_MIDDLEWARE_MODULE`, `CHDB_*`	Ekstensi opsional

[!PENTING] Variabel seperti CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, dan CLICKHOUSE_PORT hanya berlaku untuk koneksi basis data ClickHouse. Variabel tersebut tidak mengonfigurasi TLS, port, atau autentikasi untuk endpoint protokol MCP.

Contoh: jika server MCP berjalan di Kubernetes di belakang ingress yang mengakhiri TLS, itu adalah masalah transport MCP. Jaga agar CLICKHOUSE_SECURE selaras dengan bagaimana pod menjangkau ClickHouse itu sendiri (HTTPS → true, HTTP biasa → false). Mengatur CLICKHOUSE_SECURE=false karena server MCP berada di belakang ingress akan membuat server menghubungi ClickHouse melalui HTTP—seringkali terhadap port khusus HTTPS—dan menghasilkan kesalahan HTTP/TLS yang tidak jelas di log server.

Koneksi basis data ClickHouse

Variabel-variabel ini mengonfigurasi klien HTTP clickhouse-connect dan perilaku alat berbasis ClickHouse seperti run_query, list_databases, dan list_tables.

Variabel Wajib

CLICKHOUSE_HOST: Nama host server ClickHouse Anda (endpoint basis data, bukan alamat bind server MCP)
CLICKHOUSE_USER: Nama pengguna untuk autentikasi ClickHouse
CLICKHOUSE_PASSWORD: Kata sandi untuk autentikasi ClickHouse

[!CAUTION] Penting untuk memperlakukan pengguna basis data MCP Anda sebagaimana Anda memperlakukan klien eksternal mana pun yang terhubung ke basis data Anda, hanya memberikan hak akses minimum yang diperlukan untuk operasinya. Penggunaan pengguna default atau administratif harus dihindari setiap saat.

Variabel Opsional

CLICKHOUSE_PORT: Port antarmuka HTTP server ClickHouse Anda
- Default: 8443 jika CLICKHOUSE_SECURE=true, 8123 jika CLICKHOUSE_SECURE=false
- Biasanya tidak perlu diatur kecuali menggunakan port non-standar
- Harus merupakan port antarmuka HTTP, bukan port protokol TCP native yang digunakan oleh clickhouse-client
- Nilai umum:
  - HTTP: 8123 (plain) / 8443 (TLS) — digunakan oleh server ini dan HTTPS ClickHouse Cloud
  - Native TCP (tidak didukung di sini): 9000 (plain) / 9440 (TLS) — digunakan oleh clickhouse-client
- Jika server merespons dengan Port 9000 is for clickhouse-client program, Anda diarahkan ke protokol native; beralihlah ke port HTTP (8123/8443 atau pemetaan HTTP deployment Anda)
CLICKHOUSE_ROLE: Peran ClickHouse yang akan digunakan untuk autentikasi
- Default: Tidak ada
- Atur ini jika pengguna Anda memerlukan peran tertentu
CLICKHOUSE_SECURE: Aktifkan HTTPS untuk koneksi basis data ClickHouse (bukan untuk klien MCP)
- Default: "true"
- Atur ke "false" hanya ketika server MCP menjangkau ClickHouse melalui HTTP biasa (umum untuk Docker Compose lokal pada port 8123)
- Biarkan "true" untuk ClickHouse Cloud dan endpoint basis data HTTPS apa pun—meskipun server MCP itu sendiri diekspos melalui HTTP, stdio, atau ingress yang mengakhiri TLS secara terpisah
- Ketidakcocokan flag ini dengan port basis data (mis. CLICKHOUSE_SECURE=false terhadap port 8443) adalah kesalahan penyiapan yang sering terjadi dan biasanya muncul sebagai kesalahan klien HTTP yang membingungkan daripada pesan "skema salah" yang jelas
CLICKHOUSE_VERIFY: Aktifkan/nonaktifkan verifikasi sertifikat SSL untuk koneksi HTTPS ClickHouse
- Default: "true"
- Atur ke "false" untuk menonaktifkan verifikasi sertifikat (tidak direkomendasikan untuk produksi)
- Sertifikat TLS: Paket ini menggunakan penyimpanan kepercayaan sistem operasi Anda untuk verifikasi sertifikat TLS melalui truststore. Kami memanggil truststore.inject_into_ssl() saat startup untuk memastikan penanganan sertifikat yang tepat. Perilaku SSL default Python digunakan sebagai fallback hanya jika terjadi kesalahan yang tidak terduga.
CLICKHOUSE_SERVER_HOST_NAME: Nama host server untuk override SNI dan validasi sertifikat pada koneksi ClickHouse
- Default: Tidak ada (menggunakan nama host koneksi)
- Ini berguna saat menghubungkan melalui proxy atau load balancer di mana nama host sertifikat berbeda dari nama host koneksi. Saat diatur, nama host ini akan digunakan untuk SNI (Server Name Indication) selama handshake TLS dan untuk validasi nama host sertifikat.
CLICKHOUSE_PROXY_PATH: Awalan jalur URL untuk endpoint HTTP ClickHouse
- Default: Tidak ada
- Atur ini ketika antarmuka HTTP ClickHouse diekspos di belakang reverse proxy di bawah awalan jalur (misalnya, /clickhouse)
CLICKHOUSE_CONNECT_TIMEOUT: Batas waktu koneksi dalam detik untuk klien ClickHouse
- Default: "30"
- Tingkatkan nilai ini jika Anda mengalami batas waktu koneksi
CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Batas waktu kirim/terima dalam detik untuk klien ClickHouse
- Default: "300"
- Tingkatkan nilai ini untuk kueri yang berjalan lama
CLICKHOUSE_DATABASE: Basis data ClickHouse default yang akan digunakan
- Default: Tidak ada (menggunakan default server)
- Atur ini untuk secara otomatis terhubung ke basis data tertentu
CLICKHOUSE_ENABLED: Aktifkan/nonaktifkan alat basis data ClickHouse
- Default: "true"
- Atur ke "false" untuk menonaktifkan alat ClickHouse saat hanya menggunakan chDB
CLICKHOUSE_ALLOW_WRITE_ACCESS: Izinkan operasi tulis (DDL dan DML) terhadap ClickHouse
- Default: "false"
- Atur ke "true" untuk mengizinkan operasi DDL (CREATE, ALTER, DROP) dan DML (INSERT, UPDATE, DELETE)
- Saat dinonaktifkan (default), kueri dijalankan dengan pengaturan readonly=1 untuk mencegah modifikasi data
CLICKHOUSE_ALLOW_DROP: Izinkan operasi destruktif (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
- Default: "false"
- Hanya berlaku saat CLICKHOUSE_ALLOW_WRITE_ACCESS=true juga diatur
- Atur ke "true" untuk secara eksplisit mengizinkan operasi DROP dan TRUNCATE yang destruktif
- Ini adalah fitur keamanan untuk mencegah penghapusan data yang tidak disengaja selama eksplorasi AI

Server dan transport MCP

Variabel-variabel ini mengontrol proses MCP itu sendiri, termasuk transport, autentikasi, dan batas eksekusi alat kueri. Mereka independen dari pengaturan basis data ClickHouse di atas. Lihat juga Autentikasi untuk Transport HTTP/SSE.

CLICKHOUSE_MCP_SERVER_TRANSPORT: Mengatur metode transport untuk server MCP
- Default: "stdio"
- Opsi valid: "stdio", "http", "sse". Ini berguna untuk pengembangan lokal dengan alat seperti MCP Inspector.
- stdio umum untuk Claude Desktop; http/sse mengekspos listener jaringan (bind host/port di bawah)
CLICKHOUSE_MCP_BIND_HOST: Host untuk mengikat server MCP saat menggunakan transport HTTP atau SSE
- Default: "127.0.0.1"
- Atur ke "0.0.0.0" untuk mengikat ke semua antarmuka jaringan (berguna untuk Docker atau akses jarak jauh)
- Hanya digunakan saat transport adalah "http" atau "sse" — tidak terkait dengan CLICKHOUSE_HOST
CLICKHOUSE_MCP_BIND_PORT: Port untuk mengikat server MCP saat menggunakan transport HTTP atau SSE
- Default: "8000"
- Hanya digunakan saat transport adalah "http" atau "sse" — tidak terkait dengan CLICKHOUSE_PORT
CLICKHOUSE_MCP_QUERY_TIMEOUT: Batas waktu dalam detik untuk alat kueri
- Default: "30"
- Tingkatkan ini jika Anda melihat kesalahan Query timed out after ... untuk kueri berat
CLICKHOUSE_MCP_AUTH_TOKEN: Token bearer statis untuk transport HTTP/SSE
- Default: Tidak ada
- Salah satu dari CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH, atau CLICKHOUSE_MCP_AUTH_DISABLED=true diperlukan untuk transport HTTP/SSE
- Hasilkan menggunakan uuidgen atau openssl rand -hex 32
- Klien harus mengirim token ini di header Authorization: Bearer <token>
FASTMCP_SERVER_AUTH: Delegasikan autentikasi ke penyedia auth FastMCP
- Default: Tidak ada
- Nilai adalah jalur kelas lengkap dari subkelas AuthProvider, mis. fastmcp.server.auth.providers.azure.AzureProvider atau fastmcp.server.auth.providers.google.GoogleProvider
- Saat diatur, FastMCP memuat penyedia secara otomatis dari variabel lingkungan FASTMCP_SERVER_AUTH_*-nya sendiri; biarkan CLICKHOUSE_MCP_AUTH_TOKEN tidak diatur dalam mode ini
CLICKHOUSE_MCP_AUTH_DISABLED: Nonaktifkan autentikasi untuk transport HTTP/SSE
- Default: "false" (autentikasi diaktifkan)
- Atur ke "true" untuk menonaktifkan autentikasi hanya untuk pengembangan/pengujian lokal
- PERINGATAN: Hanya gunakan untuk pengembangan lokal. Jangan nonaktifkan saat terpapar ke jaringan

Variabel Middleware

MCP_MIDDLEWARE_MODULE: Nama modul Python yang berisi middleware kustom untuk disuntikkan ke server MCP
- Default: Tidak ada (tidak ada middleware yang dimuat)
- Atur ke nama modul (tanpa ekstensi .py) dari modul middleware Anda
- Modul harus menyediakan fungsi setup_middleware(mcp)
- Lihat Middleware Kustom untuk detail dan contoh

Variabel chDB

CHDB_ENABLED: Aktifkan/nonaktifkan fungsionalitas chDB
- Default: "false"
- Atur ke "true" untuk mengaktifkan alat chDB
- Memerlukan penginstalan ekstra opsional: mcp-clickhouse[chdb]
CHDB_DATA_PATH: Jalur ke direktori data chDB
- Default: ":memory:" (basis data dalam memori)
- Gunakan :memory: untuk basis data dalam memori
- Gunakan jalur file untuk penyimpanan persisten (mis., /path/to/chdb/data)

Jebakan konfigurasi umum

CLICKHOUSE_SECURE vs MCP / ingress TLS — Mematikan CLICKHOUSE_SECURE karena server MCP berada di belakang ingress Kubernetes, reverse proxy, atau dijangkau melalui HTTP biasa tidak menonaktifkan TLS basis data; itu hanya mengubah bagaimana proses ini terhubung ke ClickHouse. Konfigurasikan TLS ingress secara terpisah dari pengaturan klien basis data.
Port protokol native — CLICKHOUSE_PORT harus menargetkan antarmuka HTTP ClickHouse (8123/8443 secara default). Port 9000/9440 adalah untuk protokol TCP native (clickhouse-client) dan tidak akan berfungsi dengan server ini.
Kebingungan host — CLICKHOUSE_HOST adalah nama host basis data. CLICKHOUSE_MCP_BIND_HOST hanyalah alamat yang didengarkan oleh server HTTP/SSE MCP.

Contoh Konfigurasi

Untuk pengembangan lokal dengan 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

Untuk 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

Untuk ClickHouse SQL Playground:

CLICKHOUSE_HOST=sql-clickhouse.clickhouse.com
CLICKHOUSE_USER=demo
CLICKHOUSE_PASSWORD=
# Uses secure defaults (HTTPS on port 8443)

Untuk chDB saja (dalam memori):

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

Untuk chDB dengan penyimpanan persisten:

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

Untuk MCP Inspector atau akses jarak jauh dengan transport 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)

Untuk pengembangan lokal dengan transport HTTP (autentikasi dinonaktifkan):

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

Saat menggunakan transport HTTP, server akan berjalan pada port yang dikonfigurasi (default 8000). Misalnya, dengan konfigurasi di atas:

Endpoint MCP: http://localhost:4200/mcp
Pemeriksaan kesehatan: http://localhost:4200/health

Anda dapat mengatur variabel-variabel ini di lingkungan Anda, di file .env, atau di konfigurasi 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"
      }
    }
  }
}

Catatan: Pengaturan bind host dan port hanya digunakan saat transport diatur ke "http" atau "sse".

Menjalankan pengujian

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