ClickHouse

resmi

Kueri server basis data ClickHouse Anda.

GitHub

872

Coba MCP iniDisponsori

Apa yang bisa Anda lakukan dengan ClickHouse MCP?

Menjalankan kueri SQL — Minta asisten Anda untuk mengeksekusi SQL pada klaster ClickHouse Anda melalui run_query, termasuk DESCRIBE dan EXPLAIN ESTIMATE untuk pemeriksaan awal.
Menjelajahi struktur database — Gunakan list_databases dan list_tables untuk menemukan database, memfilter tabel dengan pola LIKE, dan melakukan paginasi melalui hasil dengan page_token.
Mengkueri data dengan chDB — Manfaatkan run_chdb_select_query untuk menjalankan SQL pada mesin chDB yang tertanam, mengkueri file, URL, atau database tanpa ETL.
Memantau kesehatan server — Periksa endpoint /health untuk probe liveness/readiness, yang mengembalikan 200 OK saat terhubung atau 503 saat gagal.
Mengaktifkan operasi tulis — Konfigurasikan flag CLICKHOUSE_ALLOW_WRITE_ACCESS dan CLICKHOUSE_ALLOW_DROP untuk mengizinkan DDL/INSERT atau operasi destruktif dengan pengaman.

Dokumentasi

Server MCP ClickHouse

Server MCP untuk ClickHouse.

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.

[!NOTE] 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 secara presisi 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 pada 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.
- 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.

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 bisa 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 bisa 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 berjalan 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))) menjalankan 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 probe ClickHouse tidak selesai dalam dua detik. Permintaan bersamaan berbagi satu probe yang sedang berjalan
Menggunakan kembali hasil probe yang selesai selama satu detik, sehingga probe 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 probe orkestrator (misalnya 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:

Mode	Kapan digunakan	Variabel env
Token pembawa statis	Penerapan 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_*` khusus 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 string acak apa pun):

# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

Konfigurasi server dengan token:

export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

Konfigurasi 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 tanpa autentikasi, pukul titik akhir MCP itu sendiri misalnya dengan MCP Inspector, atau dengan POSTing permintaan JSON-RPC ke /mcp dengan dan tanpa header Authorization dan konfirmasi bahwa panggilan tanpa autentikasi mengembalikan 401.

OAuth / OIDC via FastMCP

Untuk penerapan produksi dengan penyedia identitas (Azure Entra, Google, GitHub, WorkOS, dll.), serahkan 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 penyedia	Prefiks variabel penyedia
`fastmcp.server.auth.providers.auth0.Auth0Provider`	`FASTMCP_SERVER_AUTH_AUTH0_`
`fastmcp.server.auth.providers.aws.AWSCognitoProvider`	`FASTMCP_SERVER_AUTH_AWS_COGNITO_`
`fastmcp.server.auth.providers.azure.AzureProvider`	`FASTMCP_SERVER_AUTH_AZURE_`
`fastmcp.server.auth.providers.descope.DescopeProvider`	`FASTMCP_SERVER_AUTH_DESCOPEPROVIDER_`
`fastmcp.server.auth.providers.discord.DiscordProvider`	`FASTMCP_SERVER_AUTH_DISCORD_`
`fastmcp.server.auth.providers.github.GitHubProvider`	`FASTMCP_SERVER_AUTH_GITHUB_`
`fastmcp.server.auth.providers.google.GoogleProvider`	`FASTMCP_SERVER_AUTH_GOOGLE_`
`fastmcp.server.auth.providers.introspection.IntrospectionTokenVerifier`	`FASTMCP_SERVER_AUTH_INTROSPECTION_`
`fastmcp.server.auth.providers.jwt.JWTVerifier`	`FASTMCP_SERVER_AUTH_JWT_`
`fastmcp.server.auth.providers.oci.OCIProvider`	`FASTMCP_SERVER_AUTH_OCI_`
`fastmcp.server.auth.providers.scalekit.ScalekitProvider`	`FASTMCP_SERVER_AUTH_SCALEKITPROVIDER_`
`fastmcp.server.auth.providers.supabase.SupabaseProvider`	`FASTMCP_SERVER_AUTH_SUPABASE_`
`fastmcp.server.auth.providers.workos.WorkOSProvider`	`FASTMCP_SERVER_AUTH_WORKOS_`
`fastmcp.server.auth.providers.workos.AuthKitProvider`	`FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_`

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

Nilai auth yang disetel langsung di lingkungan proses memiliki prioritas tidak peka huruf besar/kecil. Pemuatan .env default dimulai di direktori paket mcp_clickhouse yang terinstal, menyelesaikan symlink terlebih dahulu, dan berjalan ke atas ke akar sistem file. Ini memuat .env pertama yang ditemukan dan tidak memuat apa pun jika tidak ada. Ini tidak pernah membaca direktori kerja, terlepas dari bagaimana server diluncurkan. Checkout sumber biasanya menemukan .env akar repositori. File itu juga dapat menyediakan FASTMCP_SERVER_AUTH dan bidang penyedianya. Nilainya memiliki prioritas atas file auth eksplisit atau kompatibilitas. Untuk kompatibilitas FastMCP 2, mcp-clickhouse membaca bidang penyedia yang hilang dari .env di direktori kerja, tetapi fallback kompatibilitas itu tidak dapat memilih FASTMCP_SERVER_AUTH. FASTMCP_ENV_FILE yang disetel proses menggantikan fallback kompatibilitas itu dan dapat menyediakan pemilih dan bidang penyedia. Setel sebelum startup. Pemuat kompatibilitas mcp-clickhouse hanya membaca FASTMCP_SERVER_AUTH dan FASTMCP_SERVER_AUTH_* dari file itu, sehingga tidak dapat menyuntikkan pengaturan CLICKHOUSE_*. FastMCP 4 dapat menggunakan file yang sama untuk pengaturan yang lebih luas sendiri. Penyedia kustom menerima tidak ada argumen konstruktor yang berasal dari lingkungan dan harus mendukung konstruksi tanpa argumen.

Perlakukan file .env yang ditemukan dan direktori kerja sebagai konfigurasi autentikasi tepercaya. Siapa pun yang dapat membuat atau menulis .env di direktori mana pun dari direktori paket hingga akar sistem file dapat mengontrol file mana yang ditemukan, memilih penyedia, dan menyetel bidangnya. Siapa pun yang dapat menulis file direktori kerja mengontrol setiap bidang penyedia yang tidak ada di proses dan konfigurasi yang ditemukan, termasuk kunci penandatanganan, penerbit dan titik akhir, serta rahasia klien. FASTMCP_ENV_FILE yang disetel proses yang menunjuk ke file milik operator menonaktifkan fallback direktori kerja.

FastMCP 4 mengubah penyimpanan klien proxy OAuth default. Penerapan yang mengandalkan penyimpanan proxy OAuth default FastMCP 2 harus mendaftarkan dan mengotorisasi klien lagi. Penyimpanan kustom yang kompatibel, token pembawa statis, dan verifikasi JWT tidak terpengaruh.

Mode Pengembangan (Menonaktifkan Autentikasi)

Untuk pengembangan dan pengujian lokal saja, Anda dapat menonaktifkan autentikasi dengan menyetel:

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 apa pun.

Konfigurasi

Server MCP ini mendukung ClickHouse dan chDB. Anda dapat mengaktifkan salah satu atau keduanya tergantung kebutuhan Anda. Python 3.10 hingga 3.14 didukung. Python 3.12 direkomendasikan untuk peluncuran lokal.

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

Temukan entri perintah untuk uv dan ganti dengan jalur absolut ke executable 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, atur variabel lingkungan CLICKHOUSE_ALLOW_WRITE_ACCESS ke true. Server tetap memberlakukan mode hanya-baca jika instance ClickHouse itu sendiri menolak operasi tulis.

Perlindungan Operasi Destruktif

Bahkan ketika akses tulis diaktifkan (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), operasi destruktif memerlukan flag opt-in tambahan demi keamanan. Pemeriksaan ini 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, dan komentar SQL diabaikan, sehingga tidak memicu pemeriksaan maupun menyembunyikan pernyataan darinya.

Pemeriksaan ini berjalan di server MCP dan merupakan upaya terbaik untuk melindungi dari kecelakaan. Ini bukan batas keamanan. Batas keamanan adalah hak akses (grants) pengguna ClickHouse. Mode hanya-baca (default) diberlakukan di sisi server melalui readonly=1. Gerbang operasi destruktif tidak diberlakukan di sisi server.

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

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

Setiap pernyataan di luar grants ini kemudian 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 dampak 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 yang 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 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"
      }
    }
  }
}

Atau, Anda dapat menggunakan skrip yang diinstal 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 jalur lengkap ke executable Python atau skrip mcp-clickhouse jika keduanya tidak ada di PATH sistem Anda. Anda dapat menemukan jalurnya menggunakan:

which python3 untuk executable Python
which mcp-clickhouse untuk skrip yang diinstal

Middleware Kustom

Anda dapat menambahkan middleware kustom ke server MCP tanpa memodifikasi kode sumber. FastMCP menyediakan sistem middleware yang memungkinkan Anda untuk 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.12", "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

Contoh modul middleware 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 templat 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 lingkungan.

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, perutean khusus penyewa, atau pengaturan koneksi per pengguna.

Nilai state harus berupa kamus (dictionary). Nilai bersarang settings dan generic_args harus berupa pemetaan dan digabungkan dengan konfigurasi dasar. Nilai yang tidak valid menyebabkan panggilan alat gagal sebelum klien ClickHouse dibuat. CLICKHOUSE_ROLE tetap aktif kecuali override secara eksplisit menyediakan settings.role. Kunci tingkat atas role dan ch_role, serta 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 bidang koneksi dasar yang sudah terisi atau memilih TLS. DSN dapat mengisi bidang 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 ketika tls_mode tidak diatur dan karena itu menggunakan autentikasi Basic dengan kata sandi lingkungan. Override secure memilih antarmuka https atau http yang sesuai 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 lingkungan 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 lokal permintaan. serializable=True default menyimpan state sesi dan ditolak oleh server. Server mengambil snapshot nilai sebelum mengirimkan pekerjaan basis data yang memblokir. Jangan simpan data penyewa dalam state Konteks yang dicakup sesi. Override yang dicakup sesi yang ditolak tetap terpasang ke sesi MCP lama dan menyebabkan panggilan alat berikutnya dalam sesi tersebut gagal sampai klien terhubung kembali. Peran ClickHouse per permintaan adalah konfigurasi koneksi, bukan batas otorisasi penyewa. Terapkan isolasi penyewa dengan pengguna ClickHouse, peran, dan grants.

Pengembangan

Di direktori test-services jalankan docker compose up -d untuk memulai cluster ClickHouse.
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

Jalankan uv sync untuk menginstal dependensi. Untuk menginstal uv ikuti instruksi di sini. Kemudian lakukan source .venv/bin/activate.
Untuk pengujian mudah dengan MCP Inspector, jalankan uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp 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 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

Variabel Lingkungan

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

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

[!PENTING] 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 endpoint MCP HTTP/SSE masuk.

Contoh: jika server MCP berjalan di Kubernetes di belakang ingress yang mengakhiri TLS, itu adalah masalah transport MCP. Jaga CLICKHOUSE_SECURE selaras dengan cara pod mencapai ClickHouse itu sendiri (HTTPS → true, HTTP biasa → false). Mengatur CLICKHOUSE_SECURE=false karena server MCP berada di belakang ingress akan membuat server melakukan dial ke 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 ini mengonfigurasi klien HTTP clickhouse-connect dan perilaku alat yang didukung ClickHouse seperti run_query, list_databases, dan list_tables. mcp-clickhouse memerlukan clickhouse-connect 1.0.0 atau lebih baru.

Variabel yang Diperlukan

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
- Diperlukan kecuali CLICKHOUSE_CLIENT_CERT menggunakan mode TLS default atau "mutual"
- Dalam mode default atau "mutual", autentikasi sertifikat digunakan dan kata sandi tidak dikirim

[!PERINGATAN] Penting untuk memperlakukan pengguna basis data MCP Anda seperti klien eksternal apa pun 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 dari 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 pada 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 database ClickHouse (bukan untuk klien MCP)
- Default: "true"
- Atur ke "false" hanya ketika server MCP terhubung ke ClickHouse melalui HTTP biasa (umum untuk Docker Compose lokal pada port 8123)
- Biarkan "true" untuk ClickHouse Cloud dan endpoint database HTTPS apa pun—bahkan jika server MCP itu sendiri diekspos melalui HTTP, stdio, atau ingress yang menghentikan TLS secara terpisah
- Ketidakcocokan flag ini dengan port database (misalnya CLICKHOUSE_SECURE=false terhadap port 8443) adalah kesalahan pengaturan yang sering terjadi dan biasanya muncul sebagai kesalahan klien HTTP yang membingungkan, bukan 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 ini 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 tingkat proses 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 tetap 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 ketika server ClickHouse atau proxy privat menyajikan sertifikat yang ditandatangani oleh CA privat. 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 tersebut juga dapat berisi kunci privat. Jika tidak, atur CLICKHOUSE_CLIENT_CERT_KEY.
- Pengguna ClickHouse tetap berasal dari CLICKHOUSE_USER.
CLICKHOUSE_CLIENT_CERT_KEY: Jalur ke kunci privat PEM untuk CLICKHOUSE_CLIENT_CERT
- Default: Tidak ada
- Opsional ketika kunci privat 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 seperti "mutual" ketika sertifikat klien diatur
- "mutual": Gunakan sertifikat klien untuk autentikasi pengguna X.509 ClickHouse. CLICKHOUSE_PASSWORD opsional dan tidak dikirim.
- "proxy": Sajikan sertifikat klien ke proxy yang menghentikan TLS, lalu gunakan autentikasi Basic ClickHouse. CLICKHOUSE_PASSWORD diperlukan.
- "strict": Sajikan sertifikat klien karena server ClickHouse memerlukannya di lapisan TLS, lalu gunakan autentikasi Basic ClickHouse. CLICKHOUSE_PASSWORD diperlukan. Mode ini tidak memperkuat verifikasi sertifikat server. CLICKHOUSE_VERIFY mengontrol verifikasi tersebut.
- clickhouse-connect memperlakukan "proxy" dan "strict" secara identik. Kedua nama tersebut mendokumentasikan maksud.
- 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 proxy atau penyeimbang beban di mana nama host sertifikat berbeda dari nama host koneksi. Saat diatur, nama host ini akan digunakan untuk SNI (Indikasi Nama Server) selama jabat tangan 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 proxy 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 tersebut digunakan apa adanya (misalnya "300" untuk kueri yang berjalan lama)
CLICKHOUSE_DATABASE: Database ClickHouse default yang digunakan
- Default: Tidak ada (menggunakan default server)
- Atur ini untuk terhubung otomatis ke database tertentu
CLICKHOUSE_ENABLED: Aktifkan/nonaktifkan alat database 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 dijalankan 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 ketika CLICKHOUSE_ALLOW_WRITE_ACCESS=true juga diatur
- Gerbang ini adalah pelindung kecelakaan upaya terbaik di server MCP, bukan batas keamanan. Batasi izin pengguna ClickHouse untuk penegakan yang nyata (lihat Perlindungan Operasi Destruktif)

File sertifikat TLS ClickHouse

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

Dalam mode mutual, sertifikat klien yang dikonfigurasi mengidentifikasi proses mcp-clickhouse ini sebagai CLICKHOUSE_USER. Ini tidak mengautentikasi klien MCP 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 database. 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. Variabel-variabel ini independen dari pengaturan database ClickHouse di atas. Lihat juga Autentikasi untuk Transport HTTP/SSE.

CLICKHOUSE_MCP_SERVER_TRANSPORT: Menetapkan metode transportasi untuk server MCP
- Default: "stdio"
- Opsi yang valid: "stdio", "http", "sse". Ini berguna untuk pengembangan lokal dengan alat seperti MCP Inspector.
- stdio umum digunakan untuk Claude Desktop; http/sse mengekspos pendengar jaringan (ikat host/port di bawah)
- "sse" memilih transportasi HTTP+SSE standalone yang tidak digunakan lagi dan mencatat peringatan. Gunakan "http" untuk Streamable HTTP pada penerapan baru.
CLICKHOUSE_MCP_BIND_HOST: Host untuk mengikat server MCP saat menggunakan transportasi 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 transportasi adalah "http" atau "sse" — tidak terkait dengan CLICKHOUSE_HOST
CLICKHOUSE_MCP_BIND_PORT: Port untuk mengikat server MCP saat menggunakan transportasi HTTP atau SSE
- Default: "8000"
- Hanya digunakan saat transportasi 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 transportasi HTTP/SSE
- Default: Tidak ada
- Salah satu dari CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH, atau CLICKHOUSE_MCP_AUTH_DISABLED=true wajib untuk transportasi HTTP/SSE
- Buat menggunakan uuidgen atau openssl rand -hex 32
- Klien harus mengirim token ini di header Authorization: Bearer <token>
FASTMCP_SERVER_AUTH: Mendelegasikan autentikasi ke penyedia auth FastMCP
- Default: Tidak ada
- Nilainya adalah jalur kelas lengkap dari subkelas AuthProvider, misalnya 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. Ia tidak membaca FASTMCP_SERVER_AUTH dari fallback tersebut
- Atur 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 serta menggantikan fallback direktori kerja
- Nilai lingkungan proses memiliki prioritas tanpa membedakan huruf besar/kecil
- Pemuat kompatibilitas mcp-clickhouse membaca file ini hanya saat membangun autentikasi HTTP/SSE dan hanya membaca entri FASTMCP_SERVER_AUTH dan FASTMCP_SERVER_AUTH_*. FastMCP 4 dapat membaca file yang sama untuk pengaturan yang lebih luas
- Pemuatan .env default terpisah. Dimulai dari direktori paket mcp_clickhouse yang terinstal, menyelesaikan symlink, berjalan ke atas hingga akar sistem file, dan memuat .env pertama yang ditemukan atau tidak sama sekali. Ia tidak pernah membaca direktori kerja, apa pun metode peluncurannya. File tersebut dapat menyediakan FASTMCP_SERVER_AUTH dan bidang penyedia beserta pengaturan server lainnya. Checkout sumber biasanya menemukan .env akar repositori
CLICKHOUSE_MCP_AUTH_DISABLED: Menonaktifkan autentikasi untuk transportasi 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
CLICKHOUSE_MCP_ALLOWED_HOSTS: Nilai header Host yang dipisahkan koma yang dilayani 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 tersebut 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 bersifat 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 baik mempertahankan header Host asli. Anda dapat mencantumkan nilai Host hulu yang dikirim proxy. Atur daftar eksplisit saat 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 yang paling sempit. Server MCP hanya boleh dijangkau melalui proxy dalam rentang yang dikonfigurasi. Setiap proxy tepercaya harus menghapus dan menimpa nilai X-Forwarded-Host dan X-Forwarded-Proto yang diberikan klien, dan membangun X-Forwarded-For dari peer koneksi yang terverifikasi.
- 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 saat startup 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 saat proxy tepercaya dikonfigurasi.
CLICKHOUSE_MCP_ALLOWED_ORIGINS: Nilai header Origin yang dipisahkan koma yang diterima di HTTP/SSE
- Default: Tidak ada, yang menolak setiap permintaan yang membawa header Origin
- MCP mewajibkan validasi Origin untuk koneksi transportasi HTTP/SSE. Permintaan tanpa Origin diterima karena klien MCP non-browser biasanya menghilangkannya. Origin yang tidak cocok mendapatkan 403 Forbidden. Titik akhir /health dikecualikan seperti dijelaskan di atas.
- Entri bersifat tepat (http://localhost:3000) atau menerima port apa pun (http://localhost:*). Seperti halnya host, bentuk port-apa pun hanya cocok dengan origin yang membawa port; origin port standar (https://app.example.com) harus dicantumkan secara tepat.

Penanganan Host proxy terbalik

Pertahankan Host jika 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 saat CLICKHOUSE_MCP_TRUSTED_PROXIES tidak diatur.

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

nginx standar mengubah Host menjadi nama hulu untuk permintaan yang diproksi. Ia 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 jika 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 terverifikasi 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 berupa IP node daripada pod proxy, jadi percayai pod atau CIDR node sesuai kebutuhan; 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)
- 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: Mengaktifkan/menonaktifkan fungsionalitas chDB
- Default: "false"
- Atur 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 dijangkau 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 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 hanya 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 ClickHouse SQL Playground:

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 yang menghentikan TLS memerlukan sertifikat klien dan ClickHouse masih menggunakan autentikasi Basic.

Khusus 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:

Endpoint 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