ClickHouse

resmi

Kueri server basis data ClickHouse Anda.

GitHub
899

Apa yang bisa Anda lakukan dengan ClickHouse MCP?

  • Menjalankan kueri SQL — Minta untuk mengeksekusi kueri SQL apa pun pada klaster ClickHouse Anda melalui run_query, dengan parameter bernama opsional melalui params.
  • Mendaftar database — Temukan semua database yang tersedia pada klaster ClickHouse Anda menggunakan list_databases.
  • Menjelajahi tabel dengan filter — Gunakan list_tables untuk mengeksplorasi tabel dalam database, menerapkan pola like/not_like dan paginasi melalui page_token dan page_size.
  • Memeriksa skema kueri — Minta DESCRIBE (<query>) atau EXPLAIN ESTIMATE <query> melalui run_query untuk memeriksa kolom keluaran atau perkiraan pembacaan sebelum mengeksekusi.
  • Membuat kueri data chDB tertanam — Jalankan SQL langsung terhadap mesin tertanam chDB untuk membuat kueri file, URL, atau database tanpa ETL, menggunakan run_chdb_select_query.

Dokumentasi

Server MCP ClickHouse

PyPI - Version

Server MCP untuk ClickHouse.

mcp-clickhouse MCP server

Server ini mengimplementasikan MCP 2026-07-28 dan mendukung jabat tangan inisialisasi lama dari 2024-11-05 hingga 2025-11-25. Klien modern menggunakan permintaan tanpa sesi dan server/discover. Klien yang sudah ada dapat terus melakukan negosiasi protokol lama.

[!CATATAN] Permintaan HTTP tanpa MCP-Protocol-Version dirutekan melalui penanganan lama sehingga klien dari sebelum 2025-06-18 dapat terus terhubung. MCP 2026-07-28 mengizinkan perilaku ini pada server yang mendukung klien tersebut. Klien modern harus mengirim header pada setiap permintaan POST.

Fitur

Perkakas ClickHouse

Respons perkakas ClickHouse adalah string berenkode JSON. Bilangan bulat di luar [-9007199254740991, 9007199254740991] dikembalikan sebagai string desimal untuk menjaga nilai yang tepat di klien JavaScript. Ini berlaku untuk baris kueri dan metadata tabel bilangan bulat. Bilangan bulat dalam rentang aman dan boolean mempertahankan tipe JSON-nya.

  • run_query

    • Jalankan kueri SQL di klaster ClickHouse Anda.
    • Masukan: query (string): Kueri SQL yang akan dijalankan.
    • Masukan opsional: params (objek): Nilai bernama untuk placeholder {name:Type} ClickHouse. Lihat Parameter kueri.
    • Kueri berjalan dalam mode hanya-baca secara default (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), tetapi penulisan dapat diaktifkan secara eksplisit jika diperlukan.
    • DESCRIBE (<query>) dan EXPLAIN ESTIMATE <query> juga berjalan di sini dan merupakan cara opsional untuk memeriksa skema hasil kueri atau perkiraan pembacaannya. Lihat Memeriksa kueri sebelum menjalankannya.

  • list_databases

    • Daftarkan semua basis data di klaster ClickHouse Anda.

  • list_tables

    • Daftarkan 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 sekali pakai yang dikembalikan oleh panggilan sebelumnya. Token ini disimpan hingga satu jam.
      • page_size (int, default 50): Jumlah tabel yang dikembalikan per halaman; harus lebih besar dari 0.
      • include_detailed_columns (bool, default true): Saat false, menghilangkan metadata kolom untuk respons yang lebih ringan sambil mempertahankan create_table_query lengkap.
    • Bentuk respons:
      • tables: Array objek tabel untuk halaman saat ini.
      • next_page_token: Teruskan nilai sekali pakai ini kembali sebelum kedaluwarsa untuk mengambil halaman berikutnya, atau null saat tidak ada lagi tabel.
      • total_tables: Jumlah total tabel yang cocok dengan filter yang diberikan.

Penemuan Skema Agen

Instruksi server menyarankan membaca Skema Agen's AGENTS.ROOT kanonik melalui run_query saat list_databases mengungkapkan basis data AGENTS, sebelum menulis SQL analitis. Ini adalah panduan untuk agen: tidak ada metadata yang diambil secara otomatis, hasil perkakas tidak berubah, dan izin ClickHouse yang ada tetap berlaku. Jika AGENTS.ROOT hilang atau tidak dapat diakses, penemuan normal dan kueri tetap tersedia.

Parameter kueri

Teruskan nilai secara terpisah dari SQL melalui objek params opsional:

{
  "query": "SELECT {id:UInt32} AS id, {name:String} AS name",
  "params": {"id": 13, "name": "O'Reilly"}
}

Gunakan placeholder {name:Type} ClickHouse tanpa memberi tanda kutip. Jaga kurung buka, nama, dan titik dua tetap berdampingan, seperti pada {id:UInt32}. Spasi setelah titik dua dan di dalam tipe didukung, seperti pada {id: UInt32} dan {amount:Decimal(18, 4)}. Untuk kompatibilitas di seluruh versi driver yang didukung, mulailah nama dengan huruf atau garis bawah dan gunakan hanya huruf, angka, dan garis bawah. Pemformatan gaya Python %s atau %(name)s dan parameter biner mentah $name$ driver tidak didukung. Panggilan dengan hanya query tetap berfungsi. Menghilangkan params, meneruskan null, atau meneruskan objek kosong membuat kueri tidak terikat.

Nilai parameter dapat berupa string JSON, angka, boolean, null, atau array, asalkan cocok dengan tipe ClickHouse yang dideklarasikan:

  • Gunakan null dengan tipe Nullable(...).
  • Teruskan bilangan bulat persis di luar rentang aman JavaScript sebagai string desimal, misalnya "18446744073709551615" dengan {id:UInt64}. Tanggal, stempel waktu, dan desimal persis juga dapat diteruskan sebagai string dengan tipe ClickHouse yang sesuai.
  • Ikat vektor sebagai satu array, misalnya {vector:Array(Float32)} dengan "params": {"vector": [0.25, 0.5, 0.75]}.
  • Null di dalam array bergantung pada driver yang terpasang. Null berfungsi dengan clickhouse-connect 1.8.0 tetapi gagal dengan minimum yang didukung 1.0.0.
  • Daftar dan objek JSON tidak dapat diikat ke tipe Tuple dan Map ClickHouse.

Nilai yang hilang dan tipe yang tidak kompatibel mengembalikan kesalahan kueri. Dengan params yang tidak kosong, kueri yang membawa banyak awal placeholder {name: yang tidak diakhiri ditolak, termasuk teks mirip placeholder dalam komentar atau literal string. Kueri berparameter menggunakan perlindungan penulisan, batas waktu, pembatalan, dan enkode hasil JSON yang sama dengan kueri lainnya.

Nilai parameter tetap di luar pesan log SQL normal server MCP, tetapi tetap ada di argumen perkakas MCP dan dapat muncul di kesalahan backend. ClickHouse 26.3.20.7 mensubstitusi nilai ke dalam teks kueri di system.query_log, system.processes, dan system.text_log. Pengikatan parameter bukanlah fitur privasi dan tidak mengurangi jumlah nilai vektor yang dikirim dalam panggilan perkakas.

Memeriksa kueri sebelum menjalankannya

run_query juga menjalankan DESCRIBE dan EXPLAIN ESTIMATE. Keduanya adalah pemeriksaan opsional: gunakan DESCRIBE saat Anda memerlukan kolom keluaran dan tipe kueri, dan gunakan EXPLAIN ESTIMATE sebelum SELECT yang berpotensi mahal.

DESCRIBE (<query>) memeriksa skema hasil dan mengembalikan metadata kolom keluaran yang sama dengan DESCRIBE TABLE:

DESCRIBE (SELECT user, sum(amt) FROM events WHERE ts > now() - INTERVAL 30 DAY GROUP BY user)

user      String
sum(amt)  Decimal(38, 2)

ClickHouse harus menganalisis kueri untuk menjawab, sehingga kesalahan analisis muncul di sini, dengan pesan ClickHouse sendiri, alih-alih di tengah proses eksekusi:

DESCRIBE (SELECT usr FROM events)  -> Code: 47. Unknown expression identifier `usr` ... Maybe you meant: ['user']
DESCRIBE (SELECT * FROM nosuch)    -> Code: 60. Unknown table expression identifier 'nosuch'

Kueri yang terdeskripsi dengan bersih masih dapat gagal saat dijalankan, karena batas memori atau kesalahan server jarak jauh, dan tidak mengatakan apa pun tentang biaya.

EXPLAIN ESTIMATE <query> mengembalikan bagian, baris, dan tanda yang akan dibaca kueri, satu baris per tabel, yang membedakan pencarian kunci utama dari pemindaian penuh:

EXPLAIN ESTIMATE SELECT count() FROM events WHERE id = 42

database  table   parts  rows   marks
default   events  1      8192   1

Itu adalah perkiraan pembacaan dari tabel keluarga MergeTree, setelah pemangkasan kunci utama dan partisi. Itu bukan waktu proses dan bukan ukuran hasil, dan mesin tabel lain tidak tercakup.

Tidak ada pernyataan yang menjalankan badan kueri, tetapi analisis tidak selalu gratis: DESCRIBE (SELECT (SELECT sleep(1))) mengeksekusi subkueri skalar saat menganalisis. Keduanya hanya-baca dan berfungsi di bawah CLICKHOUSE_ALLOW_WRITE_ACCESS=false default. Lihat dokumentasi ClickHouse untuk EXPLAIN ESTIMATE dan DESCRIBE.

Perkakas chDB

  • run_chdb_select_query
    • Jalankan kueri SQL menggunakan mesin ClickHouse tertanam chDB.
    • Masukan: query (string): Kueri SQL yang akan dijalankan.
    • Bilangan bulat di luar [-9007199254740991, 9007199254740991] dikembalikan sebagai string desimal.
    • Kueri data langsung dari berbagai sumber (file, URL, basis data) tanpa proses ETL.
    • Memerlukan ekstra opsional chdb: pip install 'mcp-clickhouse[chdb]'

Titik Akhir Pemeriksaan Kesehatan

Saat berjalan dengan transport HTTP atau SSE, titik akhir pemeriksaan kesehatan tersedia di /health. Titik akhir ini:

  • Mengembalikan 200 OK (isi: OK) jika server sehat dan dapat terhubung ke ClickHouse
  • Mengembalikan 503 Service Unavailable dengan pesan kesalahan umum jika server tidak dapat terhubung ke ClickHouse
  • Mengembalikan 503 jika pemeriksaan ClickHouse tidak selesai dalam dua detik. Permintaan bersamaan berbagi satu pemeriksaan yang sedang berlangsung
  • Menggunakan kembali hasil pemeriksaan yang selesai selama satu detik, sehingga pemeriksaan yang tiba berurutan tidak masing-masing terhubung ke ClickHouse. Kegagalan atau pemulihan karena itu dapat dilaporkan hingga satu detik terlambat

Permintaan GET dan HEAD ke titik akhir sengaja tidak diautentikasi dan dibebaskan dari validasi Host dan Origin sehingga pemeriksaan orkestrator (mis. liveness/readiness Kubernetes, penyeimbang beban) dapat menggunakan IP pod atau target yang ditetapkan saat runtime tanpa konfigurasi tambahan. /health dicadangkan dan tidak dapat digunakan sebagai jalur transport MCP. Isi 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 wajib secara default. Transport stdio (default) tidak memerlukan autentikasi karena hanya berkomunikasi melalui input/output standar.

Tiga mode autentikasi didukung. Pilih salah satu:

ModeKapan digunakanVariabel env
Token pembawa statisDeployment sederhana, layanan internalCLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (via FastMCP)Azure Entra, Google, GitHub, WorkOS, dll.FASTMCP_SERVER_AUTH=<provider-class-path> (+ variabel FASTMCP_SERVER_AUTH_* khusus penyedia)
DinonaktifkanPengembangan lokal sajaCLICKHOUSE_MCP_AUTH_DISABLED=true

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

Menyiapkan Autentikasi

  1. Buat token aman (dapat berupa string acak apa pun):

    # Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

  2. Konfigurasikan server dengan token:

    export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

  3. 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: titik akhir /health sengaja tidak diautentikasi (lihat Titik Akhir Pemeriksaan Kesehatan di atas). Untuk memverifikasi bahwa autentikasi token pembawa benar-benar menolak permintaan yang tidak diautentikasi, akses titik akhir MCP itu sendiri mis. dengan MCP Inspector, atau dengan mengirim POST permintaan JSON-RPC ke /mcp dengan dan tanpa header Authorization dan konfirmasi 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 auth bawaan FastMCP alih-alih menggunakan token statis. Setel FASTMCP_SERVER_AUTH ke jalur kelas lengkap penyedia auth FastMCP, bersama dengan variabel FASTMCP_SERVER_AUTH_* khusus 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>"
export FASTMCP_SERVER_AUTH_AZURE_BASE_URL="https://mcp.example.com"
export FASTMCP_SERVER_AUTH_AZURE_REQUIRED_SCOPES="read access_as_user"

mcp-clickhouse mempertahankan prefiks lingkungan FastMCP 2.14.7 ini untuk penyedia bawaan FastMCP 4.0.0:

Jalur kelas penyediaPrefiks variabel penyedia
fastmcp.server.auth.providers.auth0.Auth0ProviderFASTMCP_SERVER_AUTH_AUTH0_
fastmcp.server.auth.providers.aws.AWSCognitoProviderFASTMCP_SERVER_AUTH_AWS_COGNITO_
fastmcp.server.auth.providers.azure.AzureProviderFASTMCP_SERVER_AUTH_AZURE_
fastmcp.server.auth.providers.descope.DescopeProviderFASTMCP_SERVER_AUTH_DESCOPEPROVIDER_
fastmcp.server.auth.providers.discord.DiscordProviderFASTMCP_SERVER_AUTH_DISCORD_
fastmcp.server.auth.providers.github.GitHubProviderFASTMCP_SERVER_AUTH_GITHUB_
fastmcp.server.auth.providers.google.GoogleProviderFASTMCP_SERVER_AUTH_GOOGLE_
fastmcp.server.auth.providers.introspection.IntrospectionTokenVerifierFASTMCP_SERVER_AUTH_INTROSPECTION_
fastmcp.server.auth.providers.jwt.JWTVerifierFASTMCP_SERVER_AUTH_JWT_
fastmcp.server.auth.providers.oci.OCIProviderFASTMCP_SERVER_AUTH_OCI_
fastmcp.server.auth.providers.scalekit.ScalekitProviderFASTMCP_SERVER_AUTH_SCALEKITPROVIDER_
fastmcp.server.auth.providers.supabase.SupabaseProviderFASTMCP_SERVER_AUTH_SUPABASE_
fastmcp.server.auth.providers.workos.WorkOSProviderFASTMCP_SERVER_AUTH_WORKOS_
fastmcp.server.auth.providers.workos.AuthKitProviderFASTMCP_SERVER_AUTH_AUTHKITPROVIDER_

Tambahkan nama bidang penyedia huruf besar ke prefiks. Lihat dokumentasi FastMCP untuk persyaratan konfigurasi setiap penyedia.

Nilai auth yang diatur langsung di environment proses memiliki prioritas lebih tinggi tanpa membedakan huruf besar/kecil. Pemuatan default .env dimulai dari direktori paket mcp_clickhouse yang terinstal, menyelesaikan symlink terlebih dahulu, dan berjalan ke atas hingga root filesystem. Ia memuat .env pertama yang ditemukan dan tidak memuat apa pun jika tidak ada. Ia tidak pernah membaca direktori kerja, terlepas dari bagaimana server diluncurkan. Checkout sumber biasanya menemukan root repositori .env. File tersebut juga dapat menyediakan FASTMCP_SERVER_AUTH dan field provider-nya. Nilainya memiliki prioritas lebih tinggi daripada file auth eksplisit atau kompatibilitas. Untuk kompatibilitas FastMCP 2, mcp-clickhouse membaca field provider yang hilang dari .env di direktori kerja, tetapi fallback kompatibilitas tersebut tidak dapat memilih FASTMCP_SERVER_AUTH. FASTMCP_ENV_FILE yang diatur di proses menggantikan fallback kompatibilitas tersebut dan dapat menyediakan field selector dan provider. Atur sebelum startup. Loader kompatibilitas mcp-clickhouse hanya membaca FASTMCP_SERVER_AUTH dan FASTMCP_SERVER_AUTH_* dari file tersebut, sehingga tidak dapat menyuntikkan pengaturan CLICKHOUSE_*. FastMCP 4 dapat menggunakan file yang sama untuk pengaturan yang lebih luas miliknya sendiri. Provider kustom menerima tidak ada argumen konstruktor yang berasal dari environment dan harus mendukung konstruksi tanpa argumen.

Perlakukan file .env yang ditemukan dan di direktori kerja sebagai konfigurasi autentikasi tepercaya. Siapa pun yang dapat membuat atau menulis .env di direktori mana pun dari direktori paket hingga root filesystem dapat mengontrol file mana yang ditemukan, memilih provider, dan mengatur field-nya. Siapa pun yang dapat menulis file direktori kerja mengontrol setiap field provider yang tidak ada di proses dan konfigurasi yang ditemukan, termasuk kunci penandatanganan, penerbit dan endpoint, serta rahasia klien. FASTMCP_ENV_FILE yang diatur di proses yang menunjuk ke file milik operator menonaktifkan fallback direktori kerja.

FastMCP 4 mengubah penyimpanan klien proxy OAuth default. Deployment yang mengandalkan penyimpanan proxy OAuth default FastMCP 2 harus membuat klien mendaftar dan mengotorisasi lagi. Penyimpanan kustom yang kompatibel, token bearer statis, dan verifikasi JWT tidak terpengaruh.

Mode Pengembangan (Menonaktifkan Autentikasi)

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

export CLICKHOUSE_MCP_AUTH_DISABLED=true
export CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

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. Python 3.10 hingga 3.14 didukung. Python 3.12 direkomendasikan untuk peluncuran lokal.

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

  2. Tambahkan berikut ini:

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

Perbarui variabel environment agar menunjuk 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.12",
        "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"
      }
    }
  }
}

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

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse[chdb]",
        "--python",
        "3.12",
        "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.12",
        "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",
        "CHDB_ENABLED": "true",
        "CHDB_DATA_PATH": "/path/to/chdb/data"
      }
    }
  }
}

  1. Temukan entri perintah untuk uv dan ganti dengan path absolut ke executable uv. Ini memastikan bahwa versi uv yang benar digunakan saat memulai server. Di Mac, Anda dapat menemukan path ini menggunakan which uv.

  2. Mulai ulang Claude Desktop untuk menerapkan perubahan.

Akses Tulis Opsional

Secara default, MCP ini menerapkan kueri read-only sehingga mutasi yang tidak disengaja tidak dapat terjadi selama eksplorasi. Untuk mengizinkan pernyataan DDL atau INSERT, atur variabel environment CLICKHOUSE_ALLOW_WRITE_ACCESS ke true. Server tetap menerapkan mode read-only jika instance ClickHouse itu sendiri melarang penulisan.

Mode read-only masih mengizinkan pengguna ClickHouse untuk membatalkan kuerinya sendiri, termasuk kueri dari koneksi lain yang menggunakan pengguna yang sama. Gunakan pengguna ClickHouse khusus bahkan dalam mode read-only. Gunakan pengguna ClickHouse terpisah untuk workload yang tidak boleh saling membatalkan kueri.

Perlindungan Operasi Destruktif

Bahkan saat akses tulis diaktifkan (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), operasi destruktif memerlukan flag opt-in tambahan untuk keamanan. Pemeriksaan mencakup pernyataan DROP apa pun (termasuk klausa ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN), TRUNCATE apa pun, DELETE dan UPDATE (baik pernyataan ringan maupun mutasi ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE), REPLACE TABLE, CREATE OR REPLACE, ALTER TABLE ... REPLACE PARTITION, ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION, dan DETACH ... PERMANENTLY. Kata kunci di dalam literal string, pengidentifikasi yang dikutip, komentar SQL, dan nama parameter {name:Type} diabaikan, sehingga tidak memicu pemeriksaan maupun menyembunyikan pernyataan darinya.

Pemeriksaan ini berjalan di server MCP dan merupakan pengaman terbaik untuk mencegah kecelakaan. Ini bukan batas keamanan. Batas keamanan adalah grant pengguna ClickHouse. Mode read-only (default) diterapkan di sisi server melalui readonly=1. Gerbang operasi destruktif tidak diterapkan di server.

Untuk mode tulis, berikan server MCP pengguna ClickHouse khusus dengan hanya hak istimewa yang dibutuhkan:

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

Operasi pengubah data yang memerlukan hak istimewa di luar grant ini gagal di sisi server dengan ACCESS_DENIED, terlepas dari flag MCP. Pengaturan server max_table_size_to_drop dan max_partition_size_to_drop juga dapat membatasi radius ledakan jika dikunci dengan batasan pengaturan.

Untuk mengaktifkan operasi destruktif, atur kedua flag:

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

Pendekatan dua tingkat ini membuat penghapusan tidak disengaja menjadi sulit:

  • Operasi tulis (INSERT, CREATE, ALTER ADD COLUMN) memerlukan CLICKHOUSE_ALLOW_WRITE_ACCESS=true
  • Operasi destruktif (DROP, TRUNCATE, DELETE, UPDATE, dan sisa daftar di atas) juga memerlukan CLICKHOUSE_ALLOW_DROP=true

Menjalankan Tanpa uv (Menggunakan Python Sistem)

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

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

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

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

Catatan: Pastikan untuk menggunakan path lengkap ke executable Python atau skrip mcp-clickhouse jika keduanya tidak ada di PATH sistem Anda. Anda dapat menemukan path menggunakan:

  • which python3 untuk executable Python
  • which mcp-clickhouse untuk skrip yang terinstal

Middleware Kustom

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

Cara Menggunakan

  1. 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())
  1. Atur variabel environment MCP_MIDDLEWARE_MODULE ke nama modul (tanpa ekstensi .py):
{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": ["run", "--with", "mcp-clickhouse", "--python", "3.12", "mcp-clickhouse"],
      "env": {
        "CLICKHOUSE_HOST": "<clickhouse-host>",
        "CLICKHOUSE_USER": "<clickhouse-user>",
        "CLICKHOUSE_PASSWORD": "<clickhouse-password>",
        "MCP_MIDDLEWARE_MODULE": "my_middleware"
      }
    }
  }
}
  1. Pastikan modul middleware Anda ada di path 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 khusus
  • 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 mencantumkan alat
  • on_list_resources(context, call_next) - Dipanggil saat mencantumkan sumber daya
  • on_list_resource_templates(context, call_next) - Dipanggil saat mencantumkan template sumber daya
  • on_list_prompts(context, call_next) - Dipanggil saat mencantumkan prompt

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

Konfigurasi Klien Dinamis melalui State Konteks

Middleware dapat mengganti konfigurasi klien ClickHouse berdasarkan permintaan menggunakan kunci state konteks CLIENT_CONFIG_OVERRIDES_KEY. Server menggabungkan override ini dengan konfigurasi dasar dari variabel environment.

from fastmcp.server.dependencies import get_context
from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
from mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY


class ClientConfigMiddleware(Middleware):
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        ctx = get_context()
        await ctx.set_state(
            CLIENT_CONFIG_OVERRIDES_KEY,
            {
                "connect_timeout": 60,
                "send_receive_timeout": 120,
            },
            serializable=False,
        )
        return await call_next(context)

Ini memungkinkan kasus penggunaan lanjutan seperti penyesuaian timeout dinamis, routing khusus penyewa, atau pengaturan koneksi per pengguna.

Nilai state harus berupa kamus. Nilai settings dan generic_args bersarang harus berupa pemetaan dan digabungkan dengan konfigurasi dasar. Nilai yang tidak valid membuat panggilan alat gagal sebelum klien ClickHouse dibuat. CLICKHOUSE_ROLE tetap aktif kecuali override secara eksplisit menyediakan settings.role. Kunci role dan ch_role tingkat atas, plus kunci yang sama di bawah generic_args, ditolak.

Atur verify, ca_cert, client_cert, client_cert_key, tls_mode, server_host_name, dan pool_mgr hanya sebagai override tingkat atas. Mereka tidak dapat disarangkan di bawah generic_args. pool_mgr kustom tidak dapat digabungkan dengan pengaturan CA terkelola atau sertifikat klien. Parameter kueri DSN tidak dapat mengatur kunci ini, dan DSN tidak dapat memilih backend chdb. Gunakan override tingkat atas eksplisit host, port, username, password, database, dan secure untuk mengubah koneksi. DSN yang diteruskan tidak menggantikan field koneksi dasar yang terisi atau memilih TLS. Ia dapat mengisi field kosong dan menyediakan parameter kueri yang didukung seperti query_limit. Override secure dan verify menerima boolean atau string true dan false. verify juga menerima proxy, yang berperilaku sebagai tls_mode: proxy saat tls_mode tidak diatur dan karena itu menggunakan autentikasi Basic dengan kata sandi environment. Override secure memilih antarmuka https atau http yang cocok dan tidak mengubah port. Override interface eksplisit harus http atau https dan sesuai dengan secure. Setelah menggabungkan override, mode sertifikat klien default dan mutual menghilangkan kata sandi. Mode proxy dan strict menggunakan autentikasi Basic dengan kata sandi environment kecuali override menyediakan kredensialnya sendiri.

Perlakukan override ini sebagai input middleware tepercaya. Middleware harus mengautentikasi dan mengotorisasi nilai yang berasal dari permintaan sebelum mengaturnya. Gunakan serializable=False sehingga FastMCP menjaga nilai dalam state khusus permintaan. serializable=True default menyimpan state sesi dan ditolak oleh server. Server mengambil snapshot nilai sebelum mengirim pekerjaan database yang memblokir. Jangan simpan data penyewa di state Konteks lingkup sesi. Override lingkup sesi yang ditolak tetap terpasang ke sesi MCP lama dan menyebabkan panggilan alat berikutnya dalam sesi tersebut gagal hingga klien terhubung kembali. Peran ClickHouse per permintaan adalah konfigurasi koneksi, bukan batas otorisasi penyewa. Terapkan isolasi penyewa dengan pengguna, peran, dan grant ClickHouse.

Pengembangan

  1. Di direktori test-services jalankan docker compose up -d untuk memulai cluster ClickHouse.

  2. Tambahkan variabel berikut ke file .env di root repositori.

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

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

  1. Jalankan uv sync untuk menginstal dependensi. Untuk menginstal uv ikuti petunjuk di sini. Kemudian lakukan source .venv/bin/activate.

  2. Untuk pengujian mudah dengan MCP Inspector, jalankan uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp untuk memulai server MCP.

  3. Untuk menguji dengan transport HTTP dan titik akhir pemeriksaan kesehatan:

    # 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

Tata Letak Kode

Paket ini menggunakan tata letak modul datar. Mulailah dengan mcp_server.py untuk perakitan server dan pendaftaran, kemudian ikuti implementasinya ke modul pemiliknya.

ModulTanggung Jawab
mcp_server.py, main.pyPerakitan startup, pendaftaran alat dan prompt, koordinasi shutdown, dan startup CLI
clients.pyKonfigurasi permintaan, koneksi ClickHouse yang di-cache, dan sewa klien
queries.pyEksekusi kueri, pembatalan, dan pengaman operasi destruktif
metadata.pyPenemuan basis data dan tabel, model metadata, dan paginasi
chdb_backend.py, chdb_prompt.pyInisialisasi chDB opsional, eksekusi kueri, dan konten prompt
health.py, executors.pyProbes dan caching kesehatan, serta kumpulan pekerja yang digunakan oleh operasi server
auth.py, transport.py, http_security.pyPemuatan dotenv, autentikasi, konstruksi aplikasi HTTP/SSE, dan validasi Host/Origin
mcp_env.py, serialization.pyKonfigurasi lingkungan dan pengkodean hasil JSON
mcp_middleware_hook.py, skills_advisor.pyPemuatan middleware kustom dan instruksi server

Setiap perakitan server memiliki kumpulan pekerja, cache klien, kueri aktif, cache paginasi, status kesehatan, dan backend chDB sendiri. Pembersihan pekerja dan klien berjalan saat proses keluar. Impor paket menginisialisasi server default, termasuk saat pertama kali mengimpor modul yang diekstrak.

Dalam pengujian, patch modul atau instance pemilik tempat kode membaca dependensi. Misalnya, patch mcp_clickhouse.clients.clickhouse_connect.get_client untuk pembuatan klien. Impor kompatibilitas di mcp_server.py dapat berupa binding terpisah dari yang digunakan implementasi.

Variabel Lingkungan

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

GrupVariabelMengontrol
Koneksi basis data ClickHouseCLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, variabel sertifikatBagaimana server MCP ini terhubung ke klaster ClickHouse Anda melalui antarmuka HTTP
Server MCP / transportCLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*, FASTMCP_ENV_FILETransport MCP, autentikasi, dan batas eksekusi alat kueri
Middleware / chDBMCP_MIDDLEWARE_MODULE, CHDB_*Ekstensi opsional

[!IMPORTANT] CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, CLICKHOUSE_CA_CERT, CLICKHOUSE_CLIENT_CERT, CLICKHOUSE_CLIENT_CERT_KEY, CLICKHOUSE_TLS_MODE, dan CLICKHOUSE_PORT hanya berlaku untuk koneksi basis data ClickHouse keluar. Mereka tidak mengonfigurasi TLS, sertifikat klien, port, atau autentikasi untuk titik akhir MCP HTTP/SSE masuk.

Contoh: jika server MCP berjalan di Kubernetes di belakang ingress yang menghentikan TLS, itu adalah masalah transport MCP. Jaga CLICKHOUSE_SECURE selaras dengan cara 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—sering kali 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. mcp-clickhouse memerlukan clickhouse-connect 1.x, dimulai dari 1.0.0.

Variabel Wajib
  • CLICKHOUSE_HOST: Nama host server ClickHouse Anda (titik akhir basis data, bukan alamat bind server MCP)
  • CLICKHOUSE_USER: Nama pengguna untuk autentikasi ClickHouse
  • CLICKHOUSE_PASSWORD: Kata sandi untuk autentikasi ClickHouse
    • Wajib kecuali CLICKHOUSE_CLIENT_CERT menggunakan default atau mode TLS "mutual"
    • Dalam mode default atau "mutual", autentikasi sertifikat digunakan dan kata sandi tidak dikirim

[!CAUTION] Penting untuk memperlakukan pengguna basis data MCP Anda seperti klien eksternal lain yang terhubung ke basis data Anda, hanya memberikan hak istimewa minimum yang diperlukan untuk operasinya. Penggunaan pengguna default atau administratif harus dihindari secara ketat 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 berupa port antarmuka HTTP, bukan port protokol TCP asli yang digunakan oleh clickhouse-client
    • Nilai umum:
      • HTTP: 8123 (biasa) / 8443 (TLS) — digunakan oleh server ini dan ClickHouse Cloud HTTPS
      • TCP asli (tidak didukung di sini): 9000 (biasa) / 9440 (TLS) — digunakan oleh clickhouse-client
    • Jika server merespons dengan Port 9000 is for clickhouse-client program, Anda diarahkan ke protokol asli; beralihlah ke port HTTP (8123/8443 atau pemetaan HTTP deployment Anda)
  • CLICKHOUSE_ROLE: Peran ClickHouse yang 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 saat server MCP menjangkau ClickHouse melalui HTTP biasa (umum untuk Docker Compose lokal di port 8123)
    • Biarkan "true" untuk ClickHouse Cloud dan titik akhir basis data HTTPS apa pun—bahkan jika server MCP itu sendiri diekspos melalui HTTP, stdio, atau ingress yang menghentikan TLS secara terpisah
    • Ketidakcocokan bendera ini dengan port basis data (mis. CLICKHOUSE_SECURE=false terhadap port 8443) adalah kesalahan pengaturan 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 disarankan untuk produksi)
    • Sertifikat TLS: Paket menggunakan penyimpanan kepercayaan sistem operasi Anda melalui truststore.inject_into_ssl() saat startup. Penanganan SSL default Python digunakan jika injeksi dinonaktifkan dengan MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 atau gagal.
  • MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: Nonaktifkan integrasi penyimpanan kepercayaan sistem operasi proses-lebar untuk TLS
    • Default: tidak diatur (integrasi penyimpanan kepercayaan diaktifkan)
    • Atur tepat ke "1" sebelum startup untuk melewati truststore.inject_into_ssl() dan gunakan penanganan sertifikat SSL default Python. Nilai lain tidak menonaktifkan integrasi.
    • Ini tidak menonaktifkan verifikasi sertifikat. CLICKHOUSE_VERIFY masih mengontrol verifikasi untuk koneksi HTTPS ClickHouse.
  • CLICKHOUSE_CA_CERT: Jalur ke bundel sertifikat CA PEM untuk koneksi HTTPS ClickHouse
    • Default: Tidak ada (menggunakan penyimpanan kepercayaan sistem operasi kecuali injeksi truststore dinonaktifkan atau gagal)
    • Gunakan ini sendiri saat server ClickHouse atau proksi pribadi menyajikan sertifikat yang ditandatangani oleh CA pribadi. Ini mengubah verifikasi sertifikat server dan tidak mengaktifkan autentikasi sertifikat klien.
    • Memerlukan CLICKHOUSE_SECURE=true dan CLICKHOUSE_VERIFY=true
  • CLICKHOUSE_CLIENT_CERT: Jalur ke sertifikat klien PEM untuk koneksi HTTPS ClickHouse
    • Default: Tidak ada
    • File mungkin juga berisi kunci pribadi. Jika tidak, atur CLICKHOUSE_CLIENT_CERT_KEY.
    • Pengguna ClickHouse tetap berasal dari CLICKHOUSE_USER.
  • CLICKHOUSE_CLIENT_CERT_KEY: Jalur ke kunci pribadi PEM untuk CLICKHOUSE_CLIENT_CERT
    • Default: Tidak ada
    • Opsional saat kunci pribadi disertakan dalam file sertifikat klien
    • Tidak dapat digunakan tanpa CLICKHOUSE_CLIENT_CERT
  • CLICKHOUSE_TLS_MODE: Bagaimana clickhouse-connect menggunakan CLICKHOUSE_CLIENT_CERT
    • Default: Tidak ada, yang berperilaku sebagai "mutual" saat sertifikat klien diatur
    • "mutual": Gunakan sertifikat klien untuk autentikasi pengguna X.509 ClickHouse. CLICKHOUSE_PASSWORD opsional dan tidak dikirim.
    • "proxy": Sajikan sertifikat klien ke proksi penghenti TLS, lalu gunakan autentikasi Basic ClickHouse. CLICKHOUSE_PASSWORD wajib.
    • "strict": Sajikan sertifikat klien karena server ClickHouse memerlukannya di lapisan TLS, lalu gunakan autentikasi Basic ClickHouse. CLICKHOUSE_PASSWORD wajib. Mode ini tidak memperkuat verifikasi sertifikat server. CLICKHOUSE_VERIFY mengontrol verifikasi itu.
    • clickhouse-connect memperlakukan "proxy" dan "strict" secara identik. Kedua nama tersebut mendokumentasikan niat.
    • Nilai dipangkas dan tidak peka huruf besar/kecil. Nilai kosong diperlakukan sebagai tidak diatur. Nilai lain ditolak sebelum klien ClickHouse dibuat, pada panggilan alat ClickHouse pertama atau probe /health.
    • Memerlukan CLICKHOUSE_CLIENT_CERT. Semua opsi sertifikat klien memerlukan CLICKHOUSE_SECURE=true.
  • 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 terhubung melalui proksi atau penyeimbang beban di mana nama host sertifikat berbeda dari nama host koneksi. Saat diatur, nama host ini akan digunakan untuk SNI (Server Name Indication) selama jabat tangan TLS dan untuk validasi nama host sertifikat.
  • CLICKHOUSE_PROXY_PATH: Awalan jalur URL untuk titik akhir HTTP ClickHouse
    • Default: Tidak ada
    • Atur ini saat antarmuka HTTP ClickHouse diekspos di belakang proksi terbalik di bawah awalan jalur (misalnya, /clickhouse)
  • CLICKHOUSE_CONNECT_TIMEOUT: Waktu tunggu koneksi dalam detik untuk klien ClickHouse
    • Default: "30"
    • Tingkatkan nilai ini jika Anda mengalami waktu tunggu koneksi
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT: Waktu tunggu kirim/terima dalam detik untuk klien ClickHouse
    • Default: nilai yang lebih rendah dari 300 atau CLICKHOUSE_MCP_QUERY_TIMEOUT + 5, sehingga utas pekerja tidak terblokir segera setelah waktu tunggu kueri
    • Jika diatur secara eksplisit, nilai digunakan apa adanya (mis. "300" untuk kueri berjalan lama)
  • CLICKHOUSE_DATABASE: Basis data ClickHouse default yang digunakan
    • Default: Tidak ada (menggunakan default server)
    • Atur ini untuk terhubung otomatis 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 DDL dan DML non-destruktif (CREATE, INSERT, ALTER ADD COLUMN). Pernyataan destruktif juga memerlukan CLICKHOUSE_ALLOW_DROP=true
    • Saat dinonaktifkan (default), kueri berjalan dengan pengaturan readonly=1 untuk mencegah modifikasi data
  • CLICKHOUSE_ALLOW_DROP: Izinkan operasi destruktif (semua DROP atau TRUNCATE, DELETE dan UPDATE termasuk varian ALTER TABLE, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION, dan DETACH ... PERMANENTLY)
    • Default: "false"
    • Hanya berlaku saat CLICKHOUSE_ALLOW_WRITE_ACCESS=true juga diatur
    • Gerbang ini adalah pengaman kecelakaan upaya terbaik di server MCP, bukan batas keamanan. Batasi hak akses pengguna ClickHouse untuk penegakan nyata (lihat Perlindungan Operasi Destruktif)
File sertifikat TLS ClickHouse

Variabel sertifikat berisi jalur file, bukan konten PEM. mcp-clickhouse meneruskan jalur-jalur ini ke clickhouse-connect. Untuk Docker atau Kubernetes, pasang sertifikat dan kunci privat sebagai file read-only dan gunakan jalurnya di dalam kontainer. Jangan menyematkan kunci privat ke dalam image, mengirimkannya ke kontrol sumber, atau menaruh isinya di variabel lingkungan.

Dalam mode mutual, sertifikat klien yang dikonfigurasi mengidentifikasi proses mcp-clickhouse ini sebagai CLICKHOUSE_USER. Ini tidak mengautentikasi klien MCP yang masuk atau meneruskan identitas mereka ke ClickHouse. Konfigurasikan autentikasi transport MCP secara terpisah.

Mulai ulang mcp-clickhouse setelah mengganti sertifikat atau kunci di jalur yang sama ketika rotasi atau pencabutan segera diperlukan. Klien yang di-cache dapat mempertahankan koneksi TLS yang ada, dan cache tidak melacak konten file atau waktu modifikasi.

ClickHouse Cloud tidak mendukung autentikasi sertifikat klien X.509 untuk pengguna basis data. Gunakan CLICKHOUSE_USER dan CLICKHOUSE_PASSWORD untuk ClickHouse Cloud. Sertifikat CA masih dapat berguna ketika proxy privat di depan endpoint menyajikan sertifikat yang ditandatangani oleh CA privat.

Server MCP dan transport

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 khas untuk Claude Desktop; http/sse mengekspos pendengar jaringan (ikat host/port di bawah)
    • "sse" memilih transport HTTP+SSE standalone yang tidak digunakan lagi dan mencatat peringatan. Gunakan "http" untuk Streamable HTTP dalam penerapan baru.
  • CLICKHOUSE_MCP_BIND_HOST: Host untuk mengikat server MCP saat menggunakan transport HTTP atau SSE
    • Default: "127.0.0.1"
    • Setel 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: Waktu tunggu dalam detik untuk panggilan alat kueri
    • Default: "30"
    • Tingkatkan ini jika Anda melihat kesalahan Query timed out after ... untuk kueri berat
    • Saat kueri melebihi waktu tunggu, server mencoba membatalkannya dengan KILL QUERY
    • Kecuali CLICKHOUSE_SEND_RECEIVE_TIMEOUT diatur secara eksplisit, waktu tunggu baca HTTP dibatasi pada nilai ini ditambah lima detik
  • CLICKHOUSE_MCP_MAX_WORKERS: Jumlah maksimum utas pekerja kueri bersamaan
    • Default: "10"
    • Tingkatkan jika beban kerja Anda memerlukan banyak panggilan alat bersamaan
    • Alat metadata menggunakan kumpulan terpisah dengan min(4, CLICKHOUSE_MCP_MAX_WORKERS) utas sehingga penemuan skema tidak dapat menunda kueri
  • CLICKHOUSE_MCP_AUTH_TOKEN: Token pembawa statis untuk transport HTTP/SSE
    • Default: Tidak ada
    • Salah satu dari CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH, atau CLICKHOUSE_MCP_AUTH_DISABLED=true wajib untuk transport HTTP/SSE
    • Buat 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, mcp-clickhouse memuat penyedia dari variabel lingkungan FASTMCP_SERVER_AUTH_* yang ada; biarkan CLICKHOUSE_MCP_AUTH_TOKEN tidak diatur dalam mode ini
    • Penyedia kustom tidak menerima argumen konstruktor yang berasal dari lingkungan dan harus mendukung konstruksi tanpa argumen
    • FastMCP 4 tidak lagi mendukung verifikasi Supabase HS256. Penerapan Supabase harus menggunakan RS256 atau ES256.
  • FASTMCP_ENV_FILE: File opsional yang berisi FASTMCP_SERVER_AUTH dan variabel lingkungan khusus penyedia
    • Default: Tidak ada. Saat tidak diatur, pemuat kompatibilitas membaca bidang penyedia yang hilang dari .env di direktori kerja. Ini tidak membaca FASTMCP_SERVER_AUTH dari fallback tersebut
    • Setel di lingkungan proses sebelum memulai. Nilai yang dimuat dari .env default tidak dapat mengarahkan ulang pemuat kompatibilitas
    • Jika diatur oleh proses, file ini dapat menyediakan FASTMCP_SERVER_AUTH dan bidang penyedia dan menggantikan fallback direktori kerja
    • Nilai lingkungan proses diutamakan tanpa membedakan huruf besar/kecil
    • Pemuat kompatibilitas mcp-clickhouse membaca file ini hanya saat membangun autentikasi HTTP/SSE dan membaca hanya entri FASTMCP_SERVER_AUTH dan FASTMCP_SERVER_AUTH_*. FastMCP 4 dapat membaca file yang sama untuk pengaturan yang lebih luas
    • Pemuatan .env default terpisah. Ini dimulai di direktori paket mcp_clickhouse yang terinstal, menyelesaikan symlink, berjalan ke atas ke akar sistem file, dan memuat .env pertama yang ditemukan atau tidak sama sekali. Ini tidak pernah membaca direktori kerja, apa pun metode peluncurannya. File itu dapat menyediakan FASTMCP_SERVER_AUTH dan bidang penyedia bersama dengan pengaturan server lainnya. Checkout sumber biasanya menemukan .env akar repositori
  • CLICKHOUSE_MCP_AUTH_DISABLED: Nonaktifkan autentikasi untuk transport HTTP/SSE
    • Default: "false" (autentikasi diaktifkan)
    • Setel ke "true" untuk menonaktifkan autentikasi hanya untuk pengembangan/pengujian lokal
    • PERINGATAN: Hanya gunakan untuk pengembangan lokal. Jangan nonaktifkan saat terpapar ke jaringan
  • CLICKHOUSE_MCP_ALLOWED_HOSTS: Nilai header Host yang dipisahkan koma yang dijawab oleh server HTTP/SSE
    • Default untuk bind loopback: bentuk telanjang dan port-apa pun dari 127.0.0.1, localhost, dan [::1]
    • Jika diatur, nilai harus berisi setidaknya satu entri Host.
    • Alamat bind non-loopback konkret default ke alamat itu dan port yang dikonfigurasi. Bind wildcard seperti 0.0.0.0 atau :: memerlukan nilai non-kosong eksplisit karena Host publik tidak dapat disimpulkan.
    • Validasi Host adalah pertahanan berlapis terhadap DNS rebinding. Validasi Origin di bawah diperlukan secara terpisah oleh MCP.
    • Entri tepat (localhost:8000) atau menerima port apa pun (localhost:*). Contoh: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000
    • Bentuk host:* hanya cocok dengan nilai yang membawa port. Host tanpa port (penerapan port standar di mana klien menghilangkan :80/:443) harus dicantumkan sebagai entri tepat telanjang (example.com) juga.
    • Permintaan dengan header Host yang tidak cocok atau hilang mendapatkan 421 Misdirected Request. Permintaan GET dan HEAD ke /health dikecualikan dari validasi Host dan Origin sehingga probe orkestrator tetap berfungsi.
    • Di belakang proxy terbalik, lebih suka mempertahankan header Host asli. Anda dapat mencantumkan nilai Host upstream yang dikirim proxy. Setel daftar eksplisit ketika peluncur seperti fastmcp run menimpa alamat bind untuk akses jarak jauh.
    • mcp-clickhouse memaksa penjaga Host dan Origin terpisah FastMCP mati. FASTMCP_HTTP_HOST_ORIGIN_PROTECTION, FASTMCP_HTTP_ALLOWED_HOSTS, dan FASTMCP_HTTP_ALLOWED_ORIGINS tidak berlaku. CLICKHOUSE_MCP_ALLOWED_HOSTS dan CLICKHOUSE_MCP_ALLOWED_ORIGINS bersifat otoritatif.
  • CLICKHOUSE_MCP_TRUSTED_PROXIES: Alamat IP proxy atau jaringan CIDR yang header X-Forwarded-*-nya dipercaya
    • Default: Tidak ada. X-Forwarded-Host diabaikan. Penanganan Uvicorn yang ada untuk X-Forwarded-For dan X-Forwarded-Proto tidak berubah.
    • Entri harus berupa alamat IP atau jaringan CIDR, seperti 127.0.0.1,10.20.0.0/24,2001:db8::1. CIDR harus menggunakan alamat jaringannya, sehingga 10.20.0.1/24 ditolak. Nama host, alamat IPv6 dengan cakupan, *, 0.0.0.0/0, dan ::/0 juga ditolak.
    • Kepercayaan didasarkan pada peer soket mentah langsung. Permintaan dari peer lain mana pun, atau permintaan tanpa alamat klien, mengabaikan X-Forwarded-Host dan memvalidasi Host.
    • Peer tepercaya dapat mengirim tepat satu header X-Forwarded-Host yang berisi satu nilai non-kosong. Bidang duplikat, nilai kosong, dan daftar yang dipisahkan koma mendapatkan 421 Misdirected Request. Jika header tidak ada, Host divalidasi.
    • Gunakan alamat atau jaringan sesempit mungkin. Server MCP hanya harus dapat dijangkau melalui proxy dalam rentang yang dikonfigurasi. Setiap proxy tepercaya harus menghapus dan menimpa nilai X-Forwarded-Host dan X-Forwarded-Proto yang disuplai klien, dan membangun X-Forwarded-For dari peer koneksi yang diverifikasi.
    • Server bawaan dan fastmcp run menonaktifkan penanganan header proxy luar Uvicorn, memvalidasi Host dari peer mentah, lalu menerapkan X-Forwarded-For dan X-Forwarded-Proto. Mengaktifkan uvicorn_config["proxy_headers"] secara eksplisit gagal memulai dalam mode ini.
    • Penyematan ASGI langsung harus menonaktifkan penanganan header proxy di server ASGI luar dan memanggil mcp.http_app(raw_client_address_preserved=True). Tanpa penegasan eksplisit itu, konstruksi aplikasi gagal ketika proxy tepercaya dikonfigurasi.
  • CLICKHOUSE_MCP_ALLOWED_ORIGINS: Nilai header Origin yang dipisahkan koma diterima di HTTP/SSE
    • Default: Tidak ada, yang menolak setiap permintaan yang membawa header Origin
    • MCP memerlukan validasi Origin untuk koneksi transport HTTP/SSE. Permintaan tanpa Origin diterima karena klien MCP non-browser biasanya menghilangkannya. Origin yang tidak cocok mendapatkan 403 Forbidden. Endpoint /health dikecualikan seperti dijelaskan di atas.
    • Entri tepat (http://localhost:3000) atau menerima port apa pun (http://localhost:*). Seperti dengan host, bentuk port-apa pun hanya cocok dengan origin yang membawa port; origin port standar (https://app.example.com) harus dicantumkan dengan tepat.
Penanganan Host proxy terbalik

Pertahankan Host bila memungkinkan. Ini menjaga kepercayaan Host yang diteruskan tetap nonaktif:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host "";
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Bersihkan X-Forwarded-For dan X-Forwarded-Proto secara independen dari kepercayaan X-Forwarded-Host. Uvicorn dapat mempercayai header tersebut berdasarkan peer proxy bahkan ketika CLICKHOUSE_MCP_TRUSTED_PROXIES tidak diatur.

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

nginx stok mengubah Host menjadi nama upstream untuk permintaan yang diproksi. Ini tidak membuat atau menimpa X-Forwarded-Host. Jika mempertahankan Host tidak memungkinkan, timpa header yang diteruskan di tepi tepercaya:

location / {
    proxy_pass http://mcp-clickhouse:8000;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com
CLICKHOUSE_MCP_TRUSTED_PROXIES=10.20.0.8

Konfigurasi kedua aman hanya ketika 10.20.0.8 adalah alamat sumber langsung proxy, port server diisolasi dari klien lain, dan nginx menimpa header penerusan masuk seperti yang ditunjukkan. Untuk rantai proxy, setiap hop tepercaya harus membuang nilai masuk yang tidak diverifikasi sebelum membangun header penerusan baru.

Pada bind IPv6 atau dual-stack, proxy IPv4 dapat muncul sebagai alamat yang dipetakan IPv4 seperti ::ffff:10.20.0.8; ini dicocokkan dengan entri IPv4 secara otomatis. append_x_forwarded_host Envoy menambahkan ke X-Forwarded-Host yang ada daripada menimpanya, menghasilkan daftar yang dipisahkan koma yang ditolak, jadi konfigurasikan hop tepercaya untuk menimpa header sebagai gantinya. Di Kubernetes dengan NAT sumber (misalnya externalTrafficPolicy: Cluster) peer yang diamati mungkin merupakan IP node daripada pod proxy, jadi percayai pod atau CIDR node sesuai; ingress-nginx menimpa Host dan X-Forwarded-Host sendiri.

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)
    • Setel 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: Mengaktifkan/menonaktifkan fungsionalitas chDB
    • Default: "false"
    • Setel ke "true" untuk mengaktifkan alat chDB
    • Memerlukan pemasangan 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 (misalnya, /path/to/chdb/data)

Kesalahan konfigurasi umum

  • CLICKHOUSE_SECURE vs TLS MCP / ingress — Mematikan CLICKHOUSE_SECURE karena server MCP berada di belakang ingress Kubernetes, proxy terbalik, atau diakses melalui HTTP biasa tidak menonaktifkan TLS basis data; itu hanya mengubah cara 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 tempat server MCP HTTP/SSE mendengarkan.

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 SQL Playground ClickHouse:

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

Untuk CA server pribadi tanpa autentikasi sertifikat klien:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_VERIFY=true
CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem

Untuk autentikasi sertifikat klien X.509 ClickHouse:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-certificate-user
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
# CLICKHOUSE_CA_CERT=/run/secrets/clickhouse-ca.pem  # Only for a private server CA
# CLICKHOUSE_TLS_MODE=mutual  # Optional. This is the default with a client certificate.

Untuk sertifikat klien yang diperlukan oleh server TLS ketat sementara ClickHouse menggunakan autentikasi Basic:

CLICKHOUSE_HOST=your-secure-clickhouse.example.com
CLICKHOUSE_USER=your-user
CLICKHOUSE_PASSWORD=your-password
CLICKHOUSE_SECURE=true
CLICKHOUSE_CLIENT_CERT=/run/secrets/clickhouse-client.pem
CLICKHOUSE_CLIENT_CERT_KEY=/run/secrets/clickhouse-client-key.pem
CLICKHOUSE_TLS_MODE=strict

Gunakan CLICKHOUSE_TLS_MODE=proxy sebagai gantinya ketika proxy penghenti TLS memerlukan sertifikat klien dan ClickHouse masih menggunakan autentikasi Basic.

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

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!
CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000

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

  • Titik akhir MCP: http://localhost:8000/mcp
  • Pemeriksaan kesehatan: http://localhost:8000/health

Anda dapat mengatur variabel-variabel ini di lingkungan Anda, dalam file .env, atau dalam konfigurasi Claude Desktop:

{
  "mcpServers": {
    "mcp-clickhouse": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-clickhouse",
        "--python",
        "3.12",
        "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 host dan port bind hanya digunakan saat transport diatur ke "http" atau "sse".

Menjalankan tes

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

Ringkasan YouTube

YouTube