ClickHouse

ClickHouse MCP Sunucusu

ClickHouse için bir MCP sunucusu.

Sunucu, MCP 2026-07-28 protokolünü uygular ve 2024-11-05 ile 2025-11-25 sürümlerinden itibaren eski initialize el sıkışmalarını destekler. Modern istemciler oturumsuz istekleri ve server/discover kullanır. Mevcut istemciler eski protokolü kullanmaya devam edebilir.

[!NOTE] MCP-Protocol-Version içermeyen HTTP istekleri, 2025-06-18 öncesindeki istemcilerin bağlanmaya devam edebilmesi için eski işleme yönlendirilir. MCP 2026-07-28, bu istemcileri destekleyen sunucularda bu davranışa izin verir. Modern istemciler başlığı her POST isteğinde göndermelidir.

Özellikler

ClickHouse Araçları

ClickHouse araç yanıtları JSON kodlu dizelerdir. [-9007199254740991, 9007199254740991] dışındaki tam sayılar, JavaScript istemcilerinde tam değerleri korumak için ondalık dizeler olarak döndürülür. Bu, sorgu satırları ve tam sayı tablo meta verileri için geçerlidir. Güvenli aralıktaki tam sayılar ve boole değerleri JSON türlerini korur.

• run_query

  • ClickHouse kümenizde SQL sorguları çalıştırın.
  • Girdi: query (dize): Çalıştırılacak SQL sorgusu.
  • İsteğe bağlı girdi: params (nesne): ClickHouse {name:Type} yer tutucuları için adlandırılmış değerler. Sorgu parametreleri bölümüne bakın.
  • Sorgular varsayılan olarak salt okunur modda çalışır (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), ancak gerekirse yazma işlemleri açıkça etkinleştirilebilir.
  • DESCRIBE (<query>) ve EXPLAIN ESTIMATE <query> da burada çalışır ve bir sorgunun sonuç şemasını veya tahmini okuma miktarını incelemenin isteğe bağlı yollarıdır. Çalıştırmadan önce sorguyu kontrol etme bölümüne bakın.

• list_databases

  • ClickHouse kümenizdeki tüm veritabanlarını listeler.

• list_tables

  • Bir veritabanındaki tabloları sayfalama ile listeler.
  • Zorunlu girdi: database (dize).
  • İsteğe bağlı girdiler:
    • like / not_like (dize): Tablo adlarına LIKE veya NOT LIKE filtreleri uygulayın.
    • page_token (dize): Önceki bir çağrı tarafından döndürülen tek kullanımlık belirteç. En fazla bir saat saklanır.
    • page_size (int, varsayılan 50): Sayfa başına döndürülen tablo sayısı; 0 değerinden büyük olmalıdır.
    • include_detailed_columns (bool, varsayılan true): false olduğunda, tam create_table_query korunurken daha hafif yanıtlar için sütun meta verilerini atlar.
  • Yanıt yapısı:
    • tables: Geçerli sayfa için tablo nesneleri dizisi.
    • next_page_token: Sonraki sayfayı getirmek için bu tek kullanımlık değeri süresi dolmadan geri iletin veya daha fazla tablo yoksa null değerini kullanın.
    • total_tables: Sağlanan filtrelerle eşleşen toplam tablo sayısı.

Sorgu Parametreleri

Değerleri SQL'den ayrı olarak isteğe bağlı params nesnesi aracılığıyla iletin:

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

ClickHouse'un {name:Type} yer tutucularını tırnak işareti olmadan kullanın. Açılış ayracını, adı ve iki nokta üst üsteyi bitişik tutun, örneğin {id:UInt32} gibi. İki nokta üst üstten sonraki ve tür içindeki boşluklar desteklenir, örneğin {id: UInt32} ve {amount:Decimal(18, 4)} gibi. Desteklenen sürücü sürümleri arasında uyumluluk için adlara bir harf veya alt çizgi ile başlayın ve yalnızca harf, rakam ve alt çizgi kullanın. Python tarzı %s veya %(name)s biçimlendirme ve sürücünün $name$ ham ikili parametreleri desteklenmez. Yalnızca query içeren çağrılar yine de çalışır. params atlanırsa, null iletilirse veya boş bir nesne iletilirse sorgu bağlanmamış kalır.

Parametre değerleri, bildirilen ClickHouse türüyle eşleşmeleri koşuluyla JSON dizeleri, sayılar, boole değerleri, null veya diziler olabilir:

• null türüyle Nullable(...) kullanın.
• JavaScript'in güvenli aralığının dışındaki tam sayıları ondalık dizeler olarak iletin, örneğin {id:UInt64} ile "18446744073709551615" gibi. Tarihler, zaman damgaları ve tam ondalık sayılar da karşılık gelen ClickHouse türüyle dizeler olarak iletilebilir.
• Vektörleri tek bir dizi olarak bağlayın, örneğin "params": {"vector": [0.25, 0.5, 0.75]} ile {vector:Array(Float32)} gibi.
• Dizilerin içindeki null değerler yüklü sürücüye bağlıdır. clickhouse-connect 1.8.0 ile çalışırlar ancak desteklenen minimum 1.0.0 ile başarısız olurlar.
• JSON listeleri ve nesneleri ClickHouse Tuple ve Map türlerine bağlanamaz.

Eksik değerler ve uyumsuz türler sorgu hataları döndürür. Boş olmayan params ile, çok sayıda sonlandırılmamış {name: yer tutucu başlangıcı taşıyan bir sorgu reddedilir; yorumlardaki veya dize değişmezlerindeki yer tutucu benzeri metinler dahil. Parametreli sorgular, diğer sorgularla aynı yazma korumasını, zaman aşımlarını, iptali ve JSON sonuç kodlamasını kullanır.

Parametre değerleri MCP sunucusunun normal SQL günlük mesajlarının dışında kalır, ancak MCP araç bağımsız değişkenlerinde kalır ve arka uç hatalarında görünebilir. ClickHouse 26.3.20.7, değerleri system.query_log, system.processes ve system.text_log içindeki sorgu metnine ekler. Parametre bağlama bir gizlilik özelliği değildir ve bir araç çağrısında gönderilen vektör değerlerinin sayısını azaltmaz.

Çalıştırmadan Önce Sorguyu Kontrol Etme

run_query ayrıca DESCRIBE ve EXPLAIN ESTIMATE çalıştırır. Her ikisi de isteğe bağlı kontrollerdir: bir sorgunun çıktı sütunlarına ve türlerine ihtiyacınız olduğunda DESCRIBE kullanın ve pahalı olabilecek bir SELECT öncesinde EXPLAIN ESTIMATE kullanın.

DESCRIBE (<query>), sonuç şemasını inceler ve DESCRIBE TABLE ile aynı çıktı sütunu meta verilerini döndürür:

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

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

ClickHouse yanıt vermek için sorguyu analiz etmek zorundadır, bu nedenle analiz hataları, yürütmenin ortasında değil, ClickHouse'un kendi mesajıyla burada ortaya çıkar:

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'

Temiz bir şekilde tanımlanan bir sorgu, çalıştırıldığında bellek sınırı veya uzak sunucu hatası nedeniyle yine de başarısız olabilir ve maliyet hakkında hiçbir şey söylemez.

EXPLAIN ESTIMATE <query>, sorgunun okuyacağı parçaları, satırları ve işaretleri, tablo başına bir satır olacak şekilde döndürür; bu, bir birincil anahtar aramasını tam taramadan ayıran şeydir:

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

database  table   parts  rows   marks
default   events  1      8192   1

Bunlar, MergeTree ailesi tablolarından, birincil anahtar ve bölüm budamasından sonra tahmini okumalardır. Çalışma süresi veya sonuç boyutu değildirler ve diğer tablo motorları kapsanmaz.

Her iki ifade de sorgu gövdesini çalıştırmaz, ancak analiz her zaman ücretsiz değildir: DESCRIBE (SELECT (SELECT sleep(1))), analiz sırasında skaler alt sorguyu yürütür. Her ikisi de salt okunurdur ve varsayılan CLICKHOUSE_ALLOW_WRITE_ACCESS=false altında çalışır. EXPLAIN ESTIMATE ve DESCRIBE için ClickHouse belgelerine bakın.

chDB Araçları

• run_chdb_select_query
  • chDB'nin gömülü ClickHouse motorunu kullanarak SQL sorguları çalıştırın.
  • Girdi: query (dize): Çalıştırılacak SQL sorgusu.
  • [-9007199254740991, 9007199254740991] dışındaki tam sayılar ondalık dizeler olarak döndürülür.
  • ETL süreçleri olmadan çeşitli kaynaklardan (dosyalar, URL'ler, veritabanları) doğrudan veri sorgulayın.
  • İsteğe bağlı chdb ek paketini gerektirir: pip install 'mcp-clickhouse[chdb]'

Sağlık Kontrolü Uç Noktası

HTTP veya SSE taşımacılığıyla çalışırken, /health adresinde bir sağlık kontrolü uç noktası bulunur. Bu uç nokta:

• Sunucu sağlıklıysa ve ClickHouse'a bağlanabiliyorsa 200 OK döndürür (gövde: OK)
• Sunucu ClickHouse'a bağlanamıyorsa genel bir hata mesajıyla 503 Service Unavailable döndürür
• Bir ClickHouse yoklaması iki saniye içinde tamamlanmazsa 503 döndürür. Eşzamanlı istekler tek bir devam eden yoklamayı paylaşır
• Tamamlanmış bir yoklama sonucunu bir saniye boyunca yeniden kullanır, böylece hızlı ardışık gelen yoklamaların her biri ClickHouse'a bağlanmaz. Bu nedenle bir hata veya kurtarma en fazla bir saniye gecikmeli raporlanabilir

Uç noktaya yapılan GET ve HEAD istekleri kasıtlı olarak kimlik doğrulamasız ve Host ile Origin doğrulamasından muaftır; böylece orkestratör yoklamaları (örn. Kubernetes canlılık/hazır olma, yük dengeleyiciler) ek yapılandırma olmadan çalışma zamanında atanan pod veya hedef IP'leri kullanabilir. /health ayrılmıştır ve MCP taşıma yolu olarak kullanılamaz. Yanıt gövdesi, arka uç sürüm dizelerini veya hata ayrıntılarını sızdırmamak için kasıtlı olarak minimum düzeydedir; hata ayıklama için sunucu günlüklerine bakın.

Örnek:

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

Güvenlik

HTTP/SSE Taşımacılığı için Kimlik Doğrulama

HTTP veya SSE taşımacılığı kullanılırken kimlik doğrulama varsayılan olarak zorunludur. stdio taşımacılığı (varsayılan) yalnızca standart girdi/çıktı üzerinden iletişim kurduğu için kimlik doğrulama gerektirmez.

Üç kimlik doğrulama modu desteklenir. Birini seçin:

Mod	Ne zaman kullanılır	Ortam değişkeni
Statik taşıyıcı belirteci	Basit dağıtımlar, dahili hizmetler	CLICKHOUSE_MCP_AUTH_TOKEN
OAuth / OIDC (FastMCP aracılığıyla)	Azure Entra, Google, GitHub, WorkOS vb.	FASTMCP_SERVER_AUTH=<provider-class-path> (+ sağlayıcıya özgü FASTMCP_SERVER_AUTH_* değişkenleri)
Devre dışı	Yalnızca yerel geliştirme	CLICKHOUSE_MCP_AUTH_DISABLED=true

HTTP/SSE taşımacılıkları için bunlardan hiçbiri yapılandırılmamışsa başlangıç başarısız olur.

Kimlik Doğrulama Kurulumu

1. Güvenli bir belirteç oluşturun (herhangi bir rastgele dize olabilir):

   # Using uuidgen (macOS/Linux)
   uuidgen
   
   # Using openssl
   openssl rand -hex 32
   

2. Sunucuyu belirteçle yapılandırın:

   export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"
   

3. MCP istemcinizi isteklere belirteci ekleyecek şekilde yapılandırın:

   HTTP/SSE taşımacılığı ile Claude Desktop için:

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

   Not: /health uç noktası kasıtlı olarak kimlik doğrulamasızdır (yukarıdaki Sağlık Kontrolü Uç Noktası bölümüne bakın). Taşıyıcı belirteç kimlik doğrulamasının kimlik doğrulamasız istekleri gerçekten reddettiğini doğrulamak için, MCP uç noktasının kendisine örn. MCP Inspector ile veya /mcp adresine Authorization başlığıyla ve başlıksız bir JSON-RPC isteği POST ederek ve kimlik doğrulamasız çağrının 401 döndürdüğünü doğrulayarak erişin.

FastMCP aracılığıyla OAuth / OIDC

Kimlik sağlayıcıları (Azure Entra, Google, GitHub, WorkOS vb.) içeren üretim dağıtımları için, statik bir belirteç kullanmak yerine kimlik doğrulamayı FastMCP'nin yerleşik kimlik doğrulama sağlayıcılarına devredin. FASTMCP_SERVER_AUTH değişkenini bir FastMCP kimlik doğrulama sağlayıcısının tam sınıf yoluna ayarlayın, sağlayıcıya özgü FASTMCP_SERVER_AUTH_* değişkenleriyle birlikte ve CLICKHOUSE_MCP_AUTH_TOKEN değişkenini boş bırakın.

Örnek (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, FastMCP 4.0.0 yerleşik sağlayıcıları için bu FastMCP 2.14.7 ortam öneklerini korur:

Sağlayıcı sınıf yolu	Sağlayıcı değişken öneki
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_

Sağlayıcı alan adının büyük harfli halini öneke ekleyin. Her sağlayıcının yapılandırma gereksinimleri için FastMCP belgelerine bakın. Auth değerleri doğrudan süreç ortamında ayarlandığında, büyük/küçük harf duyarsız olarak öncelik kazanır. Varsayılan .env yüklemesi, kurulu mcp_clickhouse paket dizininden başlar, önce sembolik bağlantıları çözer ve dosya sistemi köküne doğru yukarı doğru ilerler. Bulduğu ilk .env dosyasını yükler ve hiçbiri yoksa hiçbir şey yüklemez. Sunucunun nasıl başlatıldığından bağımsız olarak çalışma dizinini asla okumaz. Bir kaynak kopyası normalde depo kökü .env dosyasını bulur. Bu dosya ayrıca FASTMCP_SERVER_AUTH ve sağlayıcı alanlarını da sağlayabilir. Değerleri, açık veya uyumluluk kimlik doğrulama dosyasına göre önceliklidir. FastMCP 2 uyumluluğu için mcp-clickhouse, eksik sağlayıcı alanlarını çalışma dizinindeki .env dosyasından okur, ancak bu uyumluluk geri dönüşü FASTMCP_SERVER_AUTH seçemez. Süreç tarafından ayarlanan bir FASTMCP_ENV_FILE, bu uyumluluk geri dönüşünün yerini alır ve hem seçici hem de sağlayıcı alanlarını sağlayabilir. Başlatmadan önce ayarlayın. mcp-clickhouse uyumluluk yükleyicisi, bu dosyadan yalnızca FASTMCP_SERVER_AUTH ve FASTMCP_SERVER_AUTH_* okur, bu nedenle CLICKHOUSE_* ayarlarını ekleyemez. FastMCP 4, kendi daha geniş ayarları için aynı dosyayı kullanabilir. Özel bir sağlayıcı, ortamdan türetilmiş yapıcı argümanları almaz ve bağımsız değişkensiz yapılandırmayı desteklemelidir.

Hem bulunan hem de çalışma dizinindeki .env dosyalarını güvenilir kimlik doğrulama yapılandırması olarak değerlendirin. Paket dizininden dosya sistemi köküne kadar herhangi bir dizinde .env oluşturabilen veya yazabilen herkes, hangi dosyanın bulunacağını kontrol edebilir, sağlayıcıyı seçebilir ve alanlarını ayarlayabilir. Çalışma dizini dosyasını yazabilen herkes, süreç ve bulunan yapılandırmada bulunmayan tüm sağlayıcı alanlarını kontrol eder; imzalama anahtarları, verenler ve uç noktalar ile istemci sırları dahil. Operatöre ait bir dosyayı işaret eden süreç tarafından ayarlanan bir FASTMCP_ENV_FILE, çalışma dizini geri dönüşünü devre dışı bırakır.

FastMCP 4, varsayılan OAuth proxy istemci deposunu değiştirdi. FastMCP 2'nin varsayılan OAuth proxy depolamasına dayanan dağıtımlar, istemcilerin yeniden kaydolmasını ve yetkilendirmesini gerektirir. Uyumlu özel depolama, statik taşıyıcı belirteçleri ve JWT doğrulaması etkilenmez.

Geliştirme Modu (Kimlik Doğrulamayı Devre Dışı Bırakma)

Yalnızca yerel geliştirme ve test için kimlik doğrulamayı şu şekilde ayarlayarak devre dışı bırakabilirsiniz:

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

UYARI: Bunu yalnızca yerel geliştirme için kullanın. Sunucu herhangi bir ağa maruz kaldığında kimlik doğrulamayı devre dışı bırakmayın.

Yapılandırma

Bu MCP sunucusu hem ClickHouse hem de chDB'yi destekler. İhtiyaçlarınıza göre birini veya her ikisini de etkinleştirebilirsiniz. Python 3.10 ile 3.14 desteklenmektedir. Yerel başlatmalar için Python 3.12 önerilir.

1. Claude Desktop yapılandırma dosyasını şu konumda açın:

   • macOS'ta: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows'ta: %APPDATA%/Claude/claude_desktop_config.json

2. Aşağıdakileri ekleyin:

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

Kendi ClickHouse hizmetinizi işaret etmek için ortam değişkenlerini güncelleyin.

Veya ClickHouse SQL Playground ile denemek isterseniz aşağıdaki yapılandırmayı kullanabilirsiniz:

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

chDB (gömülü ClickHouse motoru) için aşağıdaki yapılandırmayı ekleyin:

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

Ayrıca hem ClickHouse hem de chDB'yi aynı anda etkinleştirebilirsiniz:

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

3. uv komut girişini bulun ve uv yürütülebilir dosyasının mutlak yolu ile değiştirin. Bu, sunucu başlatılırken doğru uv sürümünün kullanılmasını sağlar. Mac'te bu yolu which uv kullanarak bulabilirsiniz.

4. Değişiklikleri uygulamak için Claude Desktop'ı yeniden başlatın.

İsteğe Bağlı Yazma Erişimi

Varsayılan olarak bu MCP, keşif sırasında yanlışlıkla değişiklik yapılmaması için salt okunur sorgular uygular. DDL veya INSERT ifadelerine izin vermek için CLICKHOUSE_ALLOW_WRITE_ACCESS ortam değişkenini true olarak ayarlayın. ClickHouse örneğinin kendisi yazmalara izin vermiyorsa sunucu salt okunur modu uygulamaya devam eder.

Yıkıcı İşlem Koruması

Yazma erişimi etkinleştirilmiş olsa bile (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), yıkıcı işlemler güvenlik için ek bir onay bayrağı gerektirir. Kontrol, herhangi bir DROP ifadesini (ALTER TABLE ... DROP PARTITION / DROP PART / DROP COLUMN yan tümceleri dahil), herhangi bir TRUNCATE, DELETE ve UPDATE (hem hafif ifadeler hem de ALTER TABLE ... DELETE / ALTER TABLE ... UPDATE mutasyonları), REPLACE TABLE, CREATE OR REPLACE, ALTER TABLE ... REPLACE PARTITION, ALTER TABLE ... CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION ve DETACH ... PERMANENTLY kapsar. Dize değişmezlerindeki, tırnaklı tanımlayıcılardaki, SQL yorumlarındaki ve {name:Type} parametre adlarındaki anahtar kelimeler yok sayılır; bu nedenle kontrolü tetiklemezler ve bir ifadeyi kontrolden gizlemezler.

Bu kontrol MCP sunucusunda çalışır ve kazalara karşı en iyi çaba gösteren bir korumadır. Bir güvenlik sınırı değildir. Güvenlik sınırı, ClickHouse kullanıcısının yetkileridir. Salt okunur mod (varsayılan) sunucu tarafında readonly=1 ile uygulanır. Yıkıcı işlem kapısı sunucu tarafında uygulanmaz.

Yazma modu için MCP sunucusuna yalnızca ihtiyaç duyduğu ayrıcalıklara sahip özel bir ClickHouse kullanıcısı verin:

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

Bu yetkilerin dışındaki her ifade, MCP bayraklarından bağımsız olarak sunucu tarafında ACCESS_DENIED ile başarısız olur. Sunucu ayarları max_table_size_to_drop ve max_partition_size_to_drop, ayar kısıtlamalarıyla sabitlenirse patlama yarıçapını da sınırlayabilir.

Yıkıcı işlemleri etkinleştirmek için her iki bayrağı da ayarlayın:

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

Bu iki katmanlı yaklaşım, yanlışlıkla silmeyi zorlaştırır:

• Yazma işlemleri (INSERT, CREATE, ALTER ADD COLUMN) CLICKHOUSE_ALLOW_WRITE_ACCESS=true gerektirir
• Yıkıcı işlemler (DROP, TRUNCATE, DELETE, UPDATE ve yukarıdaki listenin geri kalanı) ayrıca CLICKHOUSE_ALLOW_DROP=true gerektirir

uv Olmadan Çalıştırma (Sistem Python'u Kullanma)

uv yerine sistem Python kurulumunu kullanmayı tercih ederseniz, paketi PyPI'den kurup doğrudan çalıştırabilirsiniz:

1. Paketi pip kullanarak kurun:

   python3 -m pip install mcp-clickhouse
   

   chDB desteğini de kurmak için:

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

   En son sürüme yükseltmek için:

   python3 -m pip install --upgrade mcp-clickhouse
   

2. Claude Desktop yapılandırmanızı doğrudan Python kullanacak şekilde güncelleyin:

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

Alternatif olarak, kurulu betiği doğrudan kullanabilirsiniz:

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

Not: Python yürütülebilir dosyası veya mcp-clickhouse betiği sistem PATH'inizde değilse tam yolunu kullandığınızdan emin olun. Yolları şu şekilde bulabilirsiniz:

• Python yürütülebilir dosyası için which python3
• Kurulu betik için which mcp-clickhouse

Özel Ara Katman

Kaynak kodunu değiştirmeden MCP sunucusuna özel ara katman ekleyebilirsiniz. FastMCP, MCP protokol mesajlarını (araç çağrıları, kaynak okumaları, istemler vb.) yakalamanıza ve işlemenize olanak tanıyan bir ara katman sistemi sağlar.

Nasıl Kullanılır

1. Middleware genişleten ara katman sınıfları ve bir setup_middleware(mcp) işlevi içeren bir Python modülü oluşturun:

# my_middleware.py
import logging
from fastmcp.server.middleware import Middleware, MiddlewareContext, CallNext

logger = logging.getLogger("my-middleware")

class LoggingMiddleware(Middleware):
    """Log all tool calls."""
    
    async def on_call_tool(self, context: MiddlewareContext, call_next: CallNext):
        tool_name = context.message.name if hasattr(context.message, 'name') else 'unknown'
        logger.info(f"Calling tool: {tool_name}")
        result = await call_next(context)
        logger.info(f"Tool {tool_name} completed")
        return result

def setup_middleware(mcp):
    """Register middleware with the MCP server."""
    mcp.add_middleware(LoggingMiddleware())

2. MCP_MIDDLEWARE_MODULE ortam değişkenini modül adına ayarlayın (.py uzantısı olmadan):

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

3. Ara katman modülünüzün Python içe aktarma yolunda olduğundan emin olun (ör. MCP sunucusunun çalıştığı dizinde veya bir paket olarak kurulu).

Örnek Ara Katman

example_middleware.py içinde yaygın desenleri gösteren bir örnek ara katman modülü sağlanmıştır:

• Tüm MCP isteklerini günlüğe kaydetme
• Özellikle araç çağrılarını günlüğe kaydetme
• İstek işleme süresini ölçme

Örneği kullanmak için:

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

Ara Katman Yetenekleri

Middleware temel sınıfı, farklı MCP işlemleri için kancalar sağlar:

• on_message(context, call_next) - Tüm mesajlar için çağrılır
• on_request(context, call_next) - Tüm istekler için çağrılır
• on_notification(context, call_next) - Tüm bildirimler için çağrılır
• on_call_tool(context, call_next) - Bir araç yürütüldüğünde çağrılır
• on_read_resource(context, call_next) - Bir kaynak okunduğunda çağrılır
• on_get_prompt(context, call_next) - Bir istem alındığında çağrılır
• on_list_tools(context, call_next) - Araçlar listelenirken çağrılır
• on_list_resources(context, call_next) - Kaynaklar listelenirken çağrılır
• on_list_resource_templates(context, call_next) - Kaynak şablonları listelenirken çağrılır
• on_list_prompts(context, call_next) - İstemler listelenirken çağrılır

Her kanca, mesajı ve meta verileri içeren bir MiddlewareContext nesnesi ve ardışık düzeni sürdürmek için bir call_next işlevi alır.

Bağlam Durumu ile Dinamik İstemci Yapılandırması

Ara katman, CLIENT_CONFIG_OVERRIDES_KEY bağlam durumu anahtarını kullanarak ClickHouse istemci yapılandırmasını istek başına geçersiz kılabilir. Sunucu bu geçersiz kılmaları ortam değişkenlerinden gelen temel yapılandırmayla birleştirir.

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)

Bu, dinamik zaman aşımı ayarlamaları, kiracıya özel yönlendirme veya kullanıcı başına bağlantı ayarları gibi gelişmiş kullanım durumlarını etkinleştirir.

Durum değeri bir sözlük olmalıdır. İç içe settings ve generic_args değerleri eşlemeler olmalı ve temel yapılandırmayla birleştirilir. Geçersiz değerler, bir ClickHouse istemcisi oluşturulmadan önce araç çağrısını başarısız kılar. CLICKHOUSE_ROLE, geçersiz kılma açıkça settings.role sağlamadığı sürece etkin kalır. Üst düzey role ve ch_role anahtarları ile generic_args altındaki aynı anahtarlar reddedilir.

verify, ca_cert, client_cert, client_cert_key, tls_mode, server_host_name ve pool_mgr yalnızca üst düzey geçersiz kılmalar olarak ayarlayın. generic_args altına yerleştirilemezler. Özel bir pool_mgr, yönetilen CA veya istemci sertifikası ayarlarıyla birleştirilemez. DSN sorgu parametreleri bu anahtarları ayarlayamaz ve bir DSN chdb arka ucunu seçemez. Bağlantıyı değiştirmek için açık üst düzey host, port, username, password, database ve secure geçersiz kılmalarını kullanın. İletilen bir DSN, doldurulmuş temel bağlantı alanlarının yerini almaz veya TLS seçmez. Boş alanları doldurabilir ve query_limit gibi desteklenen sorgu parametrelerini sağlayabilir. secure ve verify geçersiz kılmaları boole değerlerini veya true ve false dizelerini kabul eder. verify ayrıca proxy kabul eder; bu, tls_mode ayarlanmadığında tls_mode: proxy gibi davranır ve bu nedenle ortam parolasıyla Temel kimlik doğrulaması kullanır. Bir secure geçersiz kılması, eşleşen https veya http arabirimini seçer ve bağlantı noktasını değiştirmez. Açık bir interface geçersiz kılması http veya https olmalı ve secure ile uyumlu olmalıdır. Geçersiz kılmaları birleştirdikten sonra, varsayılan ve mutual istemci sertifikası modları parolayı atlar. proxy ve strict modları, geçersiz kılma kendi kimlik bilgilerini sağlamadığı sürece ortam parolasıyla Temel kimlik doğrulaması kullanır.

Bu geçersiz kılmaları güvenilir ara katman girdisi olarak değerlendirin. Ara katman, istekten türetilen değerleri ayarlamadan önce kimlik doğrulamalı ve yetkilendirmelidir. FastMCP'nin değeri istek yerel durumunda tutması için serializable=False kullanın. Varsayılan serializable=True oturum durumunu saklar ve sunucu tarafından reddedilir. Sunucu, engelleyici veritabanı işini dağıtmadan önce değerin anlık görüntüsünü alır. Kiracı verilerini oturum kapsamlı Bağlam durumunda saklamayın. Reddedilen oturum kapsamlı bir geçersiz kılma, eski bir MCP oturumuna bağlı kalır ve istemci yeniden bağlanana kadar o oturumdaki sonraki araç çağrılarının başarısız olmasına neden olur. İstek başına ClickHouse rolü, bağlantı yapılandırmasıdır; kiracı yetkilendirme sınırı değildir. Kiracı yalıtımını ClickHouse kullanıcıları, rolleri ve yetkileriyle uygulayın.

Geliştirme

1. test-services dizininde ClickHouse kümesini başlatmak için docker compose up -d çalıştırın.

2. Depo kökünde bir .env dosyasına aşağıdaki değişkenleri ekleyin.

Not: Bu bağlamda default kullanıcısının kullanımı yalnızca yerel geliştirme amaçlıdır.

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

3. Bağımlılıkları kurmak için uv sync çalıştırın. uv kurmak için buradaki talimatları izleyin. Ardından source .venv/bin/activate yapın.

4. MCP Inspector ile kolay test için MCP sunucusunu başlatmak üzere uv run fastmcp dev inspector mcp_clickhouse/mcp_server.py:mcp çalıştırın.

5. HTTP taşıması ve sağlık kontrolü uç noktasıyla test etmek için:

   # 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
   

Ortam Değişkenleri

Yapılandırma bağımsız gruplara ayrılmıştır. Bunları karıştırmak, hata ayıklaması zor bağlantı hatalarının yaygın bir nedenidir:

Grup	Değişkenler	Kontroller
ClickHouse veritabanı bağlantısı	CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, sertifika değişkenleri	Bu MCP sunucusunun ClickHouse kümenize HTTP arayüzü üzerinden nasıl bağlandığı
MCP sunucusu / taşıma	CLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*, FASTMCP_ENV_FILE	MCP taşıması, kimlik doğrulama ve sorgu aracı yürütme sınırları
Ara katman / chDB	MCP_MIDDLEWARE_MODULE, CHDB_*	İsteğe bağlı uzantılar

[!IMPORTANT] CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, CLICKHOUSE_CA_CERT, CLICKHOUSE_CLIENT_CERT, CLICKHOUSE_CLIENT_CERT_KEY, CLICKHOUSE_TLS_MODE ve CLICKHOUSE_PORT yalnızca giden ClickHouse veritabanı bağlantısı için geçerlidir. Gelen MCP HTTP/SSE uç noktası için TLS, istemci sertifikaları, bağlantı noktaları veya kimlik doğrulamayı yapılandırmazlar.

Örnek: MCP sunucusu Kubernetes'te TLS'yi sonlandıran bir ingress arkasında çalışıyorsa, bu bir MCP taşıma konusudur. CLICKHOUSE_SECURE'yi pod'un ClickHouse'un kendisine nasıl ulaştığıyla uyumlu tutun (HTTPS → true, düz HTTP → false). MCP sunucusu bir ingress arkasında olduğu için CLICKHOUSE_SECURE=false'i ayarlamak, sunucunun ClickHouse'a HTTP üzerinden bağlanmasına neden olur—genellikle yalnızca HTTPS kullanan bir bağlantı noktasına—ve sunucu günlüklerinde anlaşılmaz HTTP/TLS hataları üretir.

ClickHouse veritabanı bağlantısı

Bu değişkenler clickhouse-connect HTTP istemcisini ve run_query, list_databases ve list_tables gibi ClickHouse destekli araçların davranışını yapılandırır. mcp-clickhouse, 1.0.0'dan başlayarak clickhouse-connect 1.x gerektirir.

Zorunlu Değişkenler

• CLICKHOUSE_HOST: ClickHouse sunucunuzun ana bilgisayar adı (veritabanı uç noktası, MCP sunucusu bağlama adresi değil)
• CLICKHOUSE_USER: ClickHouse kimlik doğrulaması için kullanıcı adı
• CLICKHOUSE_PASSWORD: ClickHouse kimlik doğrulaması için parola
  • CLICKHOUSE_CLIENT_CERT varsayılanı kullanmadığı veya "mutual" TLS modu olmadığı sürece gereklidir
  • Varsayılan veya "mutual" modunda sertifika kimlik doğrulaması kullanılır ve parola gönderilmez

[!CAUTION] MCP veritabanı kullanıcınıza, veritabanınıza bağlanan herhangi bir harici istemci gibi davranmanız ve çalışması için gereken yalnızca minimum ayrıcalıkları vermeniz önemlidir. Varsayılan veya yönetici kullanıcıların kullanımı her zaman kesinlikle kaçınılmalıdır.

İsteğe Bağlı Değişkenler

• CLICKHOUSE_PORT: ClickHouse sunucunuzun HTTP arayüz bağlantı noktası
  • Varsayılan: 8443 eğer CLICKHOUSE_SECURE=true, 8123 eğer CLICKHOUSE_SECURE=false
  • Standart olmayan bir bağlantı noktası kullanılmadığı sürece genellikle ayarlanması gerekmez
  • Bir HTTP arayüz bağlantı noktası olmalıdır, clickhouse-client tarafından kullanılan yerel TCP protokol bağlantı noktası değil
  • Yaygın değerler:
    • HTTP: 8123 (düz) / 8443 (TLS) — bu sunucu ve ClickHouse Cloud HTTPS tarafından kullanılır
    • Yerel TCP (burada desteklenmez): 9000 (düz) / 9440 (TLS) — clickhouse-client tarafından kullanılır
  • Sunucu Port 9000 is for clickhouse-client program ile yanıt verirse, yerel protokole yönlendiriliyorsunuz; HTTP bağlantı noktasına geçin (8123/8443 veya dağıtımınızın HTTP eşlemesi)
• CLICKHOUSE_ROLE: Kimlik doğrulama için kullanılacak ClickHouse rolü
  • Varsayılan: Yok
  • Kullanıcınız belirli bir rol gerektiriyorsa bunu ayarlayın
• CLICKHOUSE_SECURE: ClickHouse veritabanı bağlantısı için HTTPS'yi etkinleştirin (MCP istemcileri için değil)
  • Varsayılan: "true"
  • Yalnızca MCP sunucusu ClickHouse'a düz HTTP üzerinden ulaştığında "false" olarak ayarlayın (bağlantı noktası 8123 üzerindeki yerel Docker Compose için tipik)
  • ClickHouse Cloud ve herhangi bir HTTPS veritabanı uç noktası için "true" bırakın—MCP sunucusunun kendisi HTTP, stdio veya TLS'yi ayrıca sonlandıran bir ingress üzerinden sunulsa bile
  • Bu bayrağı veritabanı bağlantı noktasıyla eşleştirmemek (ör. CLICKHOUSE_SECURE=false bağlantı noktası 8443'ye karşı) sık yapılan bir kurulum hatasıdır ve genellikle net bir "yanlış şema" mesajı yerine kafa karıştırıcı HTTP istemci hataları olarak ortaya çıkar
• CLICKHOUSE_VERIFY: ClickHouse HTTPS bağlantısı için SSL sertifika doğrulamasını etkinleştirin/devre dışı bırakın
  • Varsayılan: "true"
  • Sertifika doğrulamasını devre dışı bırakmak için "false" olarak ayarlayın (üretim için önerilmez)
  • TLS sertifikaları: Paket, başlangıçta truststore.inject_into_ssl() aracılığıyla işletim sistemi güven deposunu kullanır. Enjeksiyon MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 ile devre dışı bırakılırsa veya başarısız olursa Python'un varsayılan SSL işlemesi kullanılır.
• MCP_CLICKHOUSE_TRUSTSTORE_DISABLE: TLS için işlem genelindeki işletim sistemi güven deposu entegrasyonunu devre dışı bırakın
  • Varsayılan: ayarlanmamış (güven deposu entegrasyonu etkin)
  • Başlangıçtan önce tam olarak "1" olarak ayarlayın truststore.inject_into_ssl()'ü atlamak ve Python'un varsayılan SSL sertifika işlemesini kullanmak için. Diğer değerler entegrasyonu devre dışı bırakmaz.
  • Bu, sertifika doğrulamasını devre dışı bırakmaz. CLICKHOUSE_VERIFY yine de ClickHouse HTTPS bağlantısı için doğrulamayı kontrol eder.
• CLICKHOUSE_CA_CERT: ClickHouse HTTPS bağlantısı için PEM CA sertifika paketinin yolu
  • Varsayılan: Yok (güven deposu enjeksiyonu devre dışı bırakılmadıkça veya başarısız olmadıkça işletim sistemi güven deposunu kullanır)
  • Bir ClickHouse sunucusu veya özel proxy, özel bir CA tarafından imzalanmış bir sertifika sunduğunda bunu tek başına kullanın. Bu, sunucu sertifika doğrulamasını değiştirir ve istemci sertifikası kimlik doğrulamasını etkinleştirmez.
  • CLICKHOUSE_SECURE=true ve CLICKHOUSE_VERIFY=true gerektirir
• CLICKHOUSE_CLIENT_CERT: ClickHouse HTTPS bağlantısı için PEM istemci sertifikasının yolu
  • Varsayılan: Yok
  • Dosya ayrıca özel anahtarı da içerebilir. Aksi takdirde CLICKHOUSE_CLIENT_CERT_KEY'i ayarlayın.
  • ClickHouse kullanıcısı yine de CLICKHOUSE_USER'den gelir.
• CLICKHOUSE_CLIENT_CERT_KEY: CLICKHOUSE_CLIENT_CERT için PEM özel anahtarının yolu
  • Varsayılan: Yok
  • Özel anahtar istemci sertifika dosyasına dahil edildiğinde isteğe bağlıdır
  • CLICKHOUSE_CLIENT_CERT olmadan kullanılamaz
• CLICKHOUSE_TLS_MODE: clickhouse-connect'in CLICKHOUSE_CLIENT_CERT'yi nasıl kullandığı
  • Varsayılan: Yok, bir istemci sertifikası ayarlandığında "mutual" gibi davranır
  • "mutual": ClickHouse X.509 kullanıcı kimlik doğrulaması için istemci sertifikasını kullanın. CLICKHOUSE_PASSWORD isteğe bağlıdır ve gönderilmez.
  • "proxy": İstemci sertifikasını TLS'yi sonlandıran bir proxy'ye sunun, ardından ClickHouse Temel kimlik doğrulamasını kullanın. CLICKHOUSE_PASSWORD gereklidir.
  • "strict": ClickHouse sunucusu TLS katmanında bir tane gerektirdiği için istemci sertifikasını sunun, ardından ClickHouse Temel kimlik doğrulamasını kullanın. CLICKHOUSE_PASSWORD gereklidir. Bu mod, sunucu sertifika doğrulamasını güçlendirmez. CLICKHOUSE_VERIFY bu doğrulamayı kontrol eder.
  • clickhouse-connect, "proxy" ve "strict"'yi aynı şekilde ele alır. İki ad, amacı belgeler.
  • Değerler kırpılır ve büyük/küçük harfe duyarsızdır. Boş bir değer, ayarlanmamış olarak kabul edilir. Diğer değerler, ilk ClickHouse aracı çağrısında veya /health yoklamasında bir ClickHouse istemcisi oluşturulmadan önce reddedilir.
  • CLICKHOUSE_CLIENT_CERT gerektirir. Tüm istemci sertifikası seçenekleri CLICKHOUSE_SECURE=true gerektirir.
• CLICKHOUSE_SERVER_HOST_NAME: ClickHouse bağlantısında SNI geçersiz kılma ve sertifika doğrulaması için sunucu ana bilgisayar adı
  • Varsayılan: Yok (bağlantı ana bilgisayar adını kullanır)
  • Bu, sertifika ana bilgisayar adının bağlantı ana bilgisayar adından farklı olduğu proxy'ler veya yük dengeleyiciler üzerinden bağlanırken kullanışlıdır. Ayarlandığında, bu ana bilgisayar adı hem TLS el sıkışması sırasında SNI (Sunucu Adı Göstergesi) hem de sertifika ana bilgisayar adı doğrulaması için kullanılır.
• CLICKHOUSE_PROXY_PATH: ClickHouse HTTP uç noktası için URL yol öneki
  • Varsayılan: Yok
  • ClickHouse HTTP arayüzü bir ters proxy arkasında bir yol öneki altında sunulduğunda bunu ayarlayın (örneğin, /clickhouse)
• CLICKHOUSE_CONNECT_TIMEOUT: ClickHouse istemcisi için saniye cinsinden bağlantı zaman aşımı
  • Varsayılan: "30"
  • Bağlantı zaman aşımları yaşıyorsanız bu değeri artırın
• CLICKHOUSE_SEND_RECEIVE_TIMEOUT: ClickHouse istemcisi için saniye cinsinden gönderme/alma zaman aşımı
  • Varsayılan: 300 veya CLICKHOUSE_MCP_QUERY_TIMEOUT + 5'den düşük olanı, böylece çalışan iş parçacıkları bir sorgu zaman aşımından kısa süre sonra engellenmeden kurtulur
  • Açıkça ayarlanırsa, değer olduğu gibi kullanılır (ör. uzun süreli sorgular için "300")
• CLICKHOUSE_DATABASE: Kullanılacak varsayılan ClickHouse veritabanı
  • Varsayılan: Yok (sunucu varsayılanını kullanır)
  • Belirli bir veritabanına otomatik bağlanmak için bunu ayarlayın
• CLICKHOUSE_ENABLED: ClickHouse veritabanı araçlarını etkinleştirin/devre dışı bırakın
  • Varsayılan: "true"
  • Yalnızca chDB kullanırken ClickHouse araçlarını devre dışı bırakmak için "false" olarak ayarlayın
• CLICKHOUSE_ALLOW_WRITE_ACCESS: ClickHouse'a yazma işlemlerine (DDL ve DML) izin ver
  • Varsayılan: "false"
  • Yıkıcı olmayan DDL ve DML'ye (CREATE, INSERT, ALTER ADD COLUMN) izin vermek için "true" olarak ayarlayın. Yıkıcı ifadeler ayrıca CLICKHOUSE_ALLOW_DROP=true gerektirir
  • Devre dışı bırakıldığında (varsayılan), sorgular veri değişikliklerini önlemek için readonly=1 ayarıyla çalışır
• CLICKHOUSE_ALLOW_DROP: Yıkıcı işlemlere izin ver (herhangi bir DROP veya TRUNCATE, DELETE ve UPDATE dahil ALTER TABLE varyantları, REPLACE TABLE / REPLACE PARTITION / CREATE OR REPLACE, CLEAR COLUMN / CLEAR INDEX / CLEAR PROJECTION ve DETACH ... PERMANENTLY)
  • Varsayılan: "false"
  • Yalnızca CLICKHOUSE_ALLOW_WRITE_ACCESS=true de ayarlandığında etkili olur
  • Bu kapı, MCP sunucusunda en iyi çaba gösteren bir kaza korumasıdır, bir güvenlik sınırı değildir. Gerçek uygulama için ClickHouse kullanıcısının yetkilerini kısıtlayın (bkz. Yıkıcı İşlem Koruması)

ClickHouse TLS sertifika dosyaları

Sertifika değişkenleri PEM içeriklerini değil, dosya yollarını içerir. mcp-clickhouse bu yolları clickhouse-connect'e iletir. Docker veya Kubernetes için sertifikayı ve özel anahtarı salt okunur dosyalar olarak bağlayın ve kapsayıcı içindeki yollarını kullanın. Özel bir anahtarı bir görüntüye gömmeyin, kaynak kontrolüne işlemeyin veya içeriğini bir ortam değişkenine koymayın.

mutual modunda, yapılandırılan istemci sertifikası bu mcp-clickhouse işlemini CLICKHOUSE_USER olarak tanımlar. Gelen MCP istemcilerinin kimliğini doğrulamaz veya kimliklerini ClickHouse'a iletmez. MCP taşıma kimlik doğrulamasını ayrıca yapılandırın.

Aynı yolda bir sertifikayı veya anahtarı değiştirdikten sonra, acil döndürme veya iptal gerektiğinde mcp-clickhouse'u yeniden başlatın. Önbelleğe alınmış istemciler mevcut TLS bağlantılarını koruyabilir ve önbellek dosya içeriklerini veya değişiklik zamanlarını izlemez.

ClickHouse Cloud, veritabanı kullanıcıları için X.509 istemci sertifikası kimlik doğrulamasını desteklemez. ClickHouse Cloud için CLICKHOUSE_USER ve CLICKHOUSE_PASSWORD kullanın. Bir uç noktanın önündeki özel bir proxy, özel bir CA tarafından imzalanmış bir sertifika sunduğunda bir CA sertifikası yine de yararlı olabilir.

MCP sunucusu ve taşıma

Bu değişkenler, taşıma, kimlik doğrulama ve sorgu aracı yürütme sınırları dahil olmak üzere MCP sürecinin kendisini kontrol eder. Yukarıdaki ClickHouse veritabanı ayarlarından bağımsızdırlar. Ayrıca bkz. HTTP/SSE Taşımaları için Kimlik Doğrulama.

• CLICKHOUSE_MCP_SERVER_TRANSPORT: MCP sunucusu için taşıma yöntemini ayarlar
  • Varsayılan: "stdio"
  • Geçerli seçenekler: "stdio", "http", "sse". Bu, MCP Inspector gibi araçlarla yerel geliştirme için kullanışlıdır.
  • stdio Claude Desktop için tipiktir; http/sse bir ağ dinleyicisi sunar (aşağıdaki bağlama ana bilgisayarını/portunu kullanır)
  • "sse" kullanımdan kaldırılmış bağımsız HTTP+SSE taşımasını seçer ve bir uyarı günlüğü kaydeder. Yeni dağıtımlarda Streamable HTTP için "http" kullanın.
• CLICKHOUSE_MCP_BIND_HOST: HTTP veya SSE taşıması kullanılırken MCP sunucusunun bağlanacağı ana bilgisayar
  • Varsayılan: "127.0.0.1"
  • Tüm ağ arayüzlerine bağlanmak için "0.0.0.0" olarak ayarlayın (Docker veya uzaktan erişim için kullanışlıdır)
  • Yalnızca taşıma "http" veya "sse" olduğunda kullanılır — CLICKHOUSE_HOST ile ilgisi yoktur
• CLICKHOUSE_MCP_BIND_PORT: HTTP veya SSE taşıması kullanılırken MCP sunucusunun bağlanacağı port
  • Varsayılan: "8000"
  • Yalnızca taşıma "http" veya "sse" olduğunda kullanılır — CLICKHOUSE_PORT ile ilgisi yoktur
• CLICKHOUSE_MCP_QUERY_TIMEOUT: Sorgu aracı çağrıları için saniye cinsinden zaman aşımı
  • Varsayılan: "30"
  • Ağır sorgular için Query timed out after ... hataları görüyorsanız bunu artırın
  • Bir sorgu zaman aşımına uğradığında, sunucu onu KILL QUERY ile iptal etmeye çalışır
  • CLICKHOUSE_SEND_RECEIVE_TIMEOUT açıkça ayarlanmadıkça, HTTP okuma zaman aşımı bu değer artı beş saniye ile sınırlıdır
• CLICKHOUSE_MCP_MAX_WORKERS: Eşzamanlı sorgu çalışan iş parçacıklarının maksimum sayısı
  • Varsayılan: "10"
  • İş yükünüz çok sayıda eşzamanlı araç çağrısı gerektiriyorsa artırın
  • Meta veri araçları, min(4, CLICKHOUSE_MCP_MAX_WORKERS) iş parçacıklı ayrı bir havuz kullanır; böylece şema keşfi sorguları geciktiremez
• CLICKHOUSE_MCP_AUTH_TOKEN: HTTP/SSE taşımaları için statik taşıyıcı belirteci
  • Varsayılan: Yok
  • CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH veya CLICKHOUSE_MCP_AUTH_DISABLED=true değerlerinden biri HTTP/SSE taşımaları için zorunludur
  • uuidgen veya openssl rand -hex 32 kullanarak oluşturun
  • İstemciler bu belirteci Authorization: Bearer <token> başlığında göndermelidir
• FASTMCP_SERVER_AUTH: Kimlik doğrulamayı bir FastMCP auth sağlayıcısına devredin
  • Varsayılan: Yok
  • Değer, bir AuthProvider alt sınıfının tam sınıf yoludur, örn. fastmcp.server.auth.providers.azure.AzureProvider veya fastmcp.server.auth.providers.google.GoogleProvider
  • Ayarlandığında, mcp-clickhouse sağlayıcıyı mevcut FASTMCP_SERVER_AUTH_* ortam değişkenlerinden yükler; bu modda CLICKHOUSE_MCP_AUTH_TOKEN değerini ayarlanmamış bırakın
  • Özel sağlayıcılar ortamdan türetilmiş yapıcı bağımsız değişkenleri almaz ve bağımsız değişkensiz yapılandırmayı desteklemelidir
  • FastMCP 4 artık Supabase HS256 doğrulamasını desteklemiyor. Supabase dağıtımları RS256 veya ES256 kullanmalıdır.
• FASTMCP_ENV_FILE: FASTMCP_SERVER_AUTH ve sağlayıcıya özel ortam değişkenlerini içeren isteğe bağlı dosya
  • Varsayılan: Yok. Ayarlanmadığında, uyumluluk yükleyicisi eksik sağlayıcı alanlarını çalışma dizinindeki .env dosyasından okur. Bu geri dönüşten FASTMCP_SERVER_AUTH okumaz
  • Başlangıçtan önce onu işlem ortamına ayarlayın. Varsayılan .env dosyasından yüklenen bir değer, uyumluluk yükleyicisini yönlendiremez
  • İşlem tarafından ayarlanırsa, bu dosya hem FASTMCP_SERVER_AUTH hem de sağlayıcı alanlarını sağlayabilir ve çalışma dizini geri dönüşünün yerini alır
  • İşlem ortamı değerleri büyük/küçük harfe duyarsız olarak önceliklidir
  • mcp-clickhouse uyumluluk yükleyicisi bu dosyayı yalnızca HTTP/SSE kimlik doğrulaması oluştururken okur ve yalnızca FASTMCP_SERVER_AUTH ve FASTMCP_SERVER_AUTH_* girdilerini okur. FastMCP 4, daha geniş ayarları için aynı dosyayı okuyabilir
  • Varsayılan .env yüklemesi ayrıdır. Kurulu mcp_clickhouse paket dizininden başlar, sembolik bağlantıları çözer, dosya sistemi köküne doğru yukarı yürür ve bulunan ilk .env dosyasını veya hiçbirini yükler. Başlatma yönteminden bağımsız olarak çalışma dizinini asla okumaz. Bu dosya, diğer sunucu ayarlarıyla birlikte FASTMCP_SERVER_AUTH ve sağlayıcı alanlarını sağlayabilir. Bir kaynak kopyası normalde depo kökü .env dosyasını bulur
• CLICKHOUSE_MCP_AUTH_DISABLED: HTTP/SSE taşımaları için kimlik doğrulamayı devre dışı bırakır
  • Varsayılan: "false" (kimlik doğrulama etkindir)
  • Yalnızca yerel geliştirme/test için kimlik doğrulamayı devre dışı bırakmak üzere "true" olarak ayarlayın
  • UYARI: Yalnızca yerel geliştirme için kullanın. Ağlara maruz kaldığında devre dışı bırakmayın
• CLICKHOUSE_MCP_ALLOWED_HOSTS: HTTP/SSE sunucusunun yanıt verdiği virgülle ayrılmış Host başlık değerleri
  • Geri döngü bağlaması için varsayılan: 127.0.0.1, localhost ve [::1] değerlerinin çıplak ve herhangi bir port biçimi
  • Ayarlanırsa, değer en az bir Ana Bilgisayar girdisi içermelidir.
  • Somut bir geri döngü olmayan bağlama adresi, varsayılan olarak bu adrese ve yapılandırılmış porta ayarlanır. 0.0.0.0 veya :: gibi bir joker karakter bağlaması, genel Ana Bilgisayar çıkarılamadığı için açık, boş olmayan bir değer gerektirir.
  • Ana bilgisayar doğrulaması, DNS yeniden bağlamaya karşı derinlemesine bir savunmadır. Aşağıdaki kaynak doğrulaması MCP tarafından ayrıca gereklidir.
  • Girdiler tamdır (localhost:8000) veya herhangi bir portu kabul eder (localhost:*). Örnek: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000
  • host:* biçimi yalnızca bir port taşıyan değerlerle eşleşir. Portsuz bir Ana Bilgisayar (istemcinin :80/:443 değerini atladığı standart bir port dağıtımı) ayrıca çıplak bir tam girdi (example.com) olarak listelenmelidir.
  • Eşleşmeyen veya eksik bir Host başlığına sahip istekler 421 Misdirected Request alır. /health adresine yapılan GET ve HEAD istekleri, düzenleyici yoklama problarının çalışmaya devam etmesi için Ana Bilgisayar ve Kaynak doğrulamasından muaftır.
  • Bir ters proxy arkasında, orijinal Host başlığını korumayı tercih edin. Bunun yerine proxy'nin gönderdiği yukarı akış Host değerini listeleyebilirsiniz. fastmcp run gibi bir başlatıcı uzaktan erişim için bağlama adresini geçersiz kıldığında açık bir liste ayarlayın.
  • mcp-clickhouse, FastMCP'nin ayrı Ana Bilgisayar ve Kaynak korumasını kapatmaya zorlar. FASTMCP_HTTP_HOST_ORIGIN_PROTECTION, FASTMCP_HTTP_ALLOWED_HOSTS ve FASTMCP_HTTP_ALLOWED_ORIGINS uygulanmaz. CLICKHOUSE_MCP_ALLOWED_HOSTS ve CLICKHOUSE_MCP_ALLOWED_ORIGINS yetkilidir.
• CLICKHOUSE_MCP_TRUSTED_PROXIES: X-Forwarded-* başlıklarına güvenilen proxy IP adresleri veya CIDR ağları
  • Varsayılan: Yok. X-Forwarded-Host yok sayılır. X-Forwarded-For ve X-Forwarded-Proto için mevcut Uvicorn işlemesi değişmez.
  • Girdiler IP adresleri veya CIDR ağları olmalıdır, örn. 127.0.0.1,10.20.0.0/24,2001:db8::1. CIDR'ler ağ adreslerini kullanmalıdır, bu nedenle 10.20.0.1/24 reddedilir. Ana bilgisayar adları, kapsamlı IPv6 adresleri, *, 0.0.0.0/0 ve ::/0 de reddedilir.
  • Güven, anında ham soket eşine dayanır. Başka bir eşten gelen bir istek veya istemci adresi olmayan bir istek, X-Forwarded-Host değerini yok sayar ve Host değerini doğrular.
  • Güvenilir bir eş, boş olmayan bir değer içeren tam olarak bir X-Forwarded-Host başlığı gönderebilir. Yinelenen alanlar, boş değerler ve virgülle ayrılmış listeler 421 Misdirected Request alır. Başlık yoksa, Host doğrulanır.
  • Mümkün olan en dar adresi veya ağı kullanın. MCP sunucusuna yalnızca yapılandırılmış aralıklardaki proxy'ler aracılığıyla erişilebilmelidir. Her güvenilir proxy, istemci tarafından sağlanan X-Forwarded-Host ve X-Forwarded-Proto değerlerini kaldırmalı ve üzerine yazmalı ve doğrulanmış bağlantı eşinden X-Forwarded-For değerini oluşturmalıdır.
  • Yerleşik sunucu ve fastmcp run, Uvicorn'un dış proxy başlığı işlemesini devre dışı bırakır, Ana Bilgisayarı ham eşten doğrular ve ardından X-Forwarded-For ve X-Forwarded-Proto değerlerini uygular. Bu modda uvicorn_config["proxy_headers"] değerini açıkça etkinleştirmek başlatmayı başarısız kılar.
  • Doğrudan ASGI gömme, dış ASGI sunucusunda proxy başlığı işlemesini devre dışı bırakmalı ve mcp.http_app(raw_client_address_preserved=True) çağırmalıdır. Bu açık onay olmadan, güvenilir proxy'ler yapılandırıldığında uygulama oluşturma başarısız olur.
• CLICKHOUSE_MCP_ALLOWED_ORIGINS: HTTP/SSE üzerinde kabul edilen virgülle ayrılmış Origin başlık değerleri
  • Varsayılan: Yok; bu, Origin başlığı taşıyan her isteği reddeder
  • MCP, HTTP/SSE taşıma bağlantıları için Kaynak doğrulaması gerektirir. Kaynak başlığı olmayan istekler kabul edilir çünkü tarayıcı olmayan MCP istemcileri normalde onu atlar. Eşleşmeyen bir Kaynak 403 Forbidden alır. /health uç noktası yukarıda açıklandığı gibi muaftır.
  • Girdiler tamdır (http://localhost:3000) veya herhangi bir portu kabul eder (http://localhost:*). Ana bilgisayarlarda olduğu gibi, herhangi bir port biçimi yalnızca bir port taşıyan kaynaklarla eşleşir; standart bir port kaynağı (https://app.example.com) tam olarak listelenmelidir.

Ters proxy Ana Bilgisayar işleme

Mümkün olduğunda Host değerini koruyun. Bu, iletilen Ana Bilgisayar güvenini devre dışı bırakır:

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

X-Forwarded-For ve X-Forwarded-Proto değerlerini X-Forwarded-Host güveninden bağımsız olarak temizleyin. Uvicorn, CLICKHOUSE_MCP_TRUSTED_PROXIES ayarlanmamış olsa bile bu başlıklara proxy eşine dayanarak güvenebilir.

CLICKHOUSE_MCP_ALLOWED_HOSTS=mcp.example.com

Stok nginx, proxy'lenen istekler için Host değerini yukarı akış adına değiştirir. X-Forwarded-Host oluşturmaz veya üzerine yazmaz. Host korumak mümkün değilse, iletilen başlığı güvenilir uçta üzerine yazın:

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

İkinci yapılandırma yalnızca 10.20.0.8 proxy'nin anında kaynak adresi olduğunda, sunucu portu diğer istemcilerden izole edildiğinde ve nginx gelen iletme başlıklarını gösterildiği gibi üzerine yazdığında güvenlidir. Bir proxy zinciri için, her güvenilir atlama, yeni iletme başlıklarını oluşturmadan önce doğrulanmamış gelen değerleri atmalıdır.

IPv6 veya çift yığın bağlamasında, IPv4 proxy'leri ::ffff:10.20.0.8 gibi IPv4 eşlemeli adresler olarak görünebilir; bunlar otomatik olarak IPv4 girdileriyle eşleştirilir. Envoy'un append_x_forwarded_host değeri, mevcut bir X-Forwarded-Host değerine ekler, üzerine yazmak yerine, reddedilen virgülle ayrılmış bir liste üretir; bu nedenle güvenilir atlamayı başlığı üzerine yazacak şekilde yapılandırın. Kaynak NAT'lı Kubernetes'te (örneğin externalTrafficPolicy: Cluster) gözlemlenen eş, proxy pod'u yerine bir düğüm IP'si olabilir; bu nedenle uygun şekilde pod veya düğüm CIDR'ine güvenin; ingress-nginx hem Host hem de X-Forwarded-Host değerlerini kendisi üzerine yazar.

Ara Yazılım Değişkenleri

• MCP_MIDDLEWARE_MODULE: MCP sunucusuna eklenecek özel ara yazılımı içeren Python modül adı
  • Varsayılan: Yok (ara yazılım yüklenmez)
  • Ara yazılım modülünüzün modül adına ayarlayın (.py uzantısı olmadan)
  • Modül bir setup_middleware(mcp) işlevi sağlamalıdır
  • Ayrıntılar ve örnekler için Özel Ara Yazılım bölümüne bakın

chDB Değişkenleri

• CHDB_ENABLED: chDB işlevselliğini etkinleştirir/devre dışı bırakır
  • Varsayılan: "false"
  • chDB araçlarını etkinleştirmek için "true" olarak ayarlayın
  • İsteğe bağlı ekstra paketin kurulmasını gerektirir: mcp-clickhouse[chdb]
• CHDB_DATA_PATH: chDB veri dizininin yolu
  • Varsayılan: ":memory:" (bellek içi veritabanı)
  • Bellek içi veritabanı için :memory: kullanın
  • Kalıcı depolama için bir dosya yolu kullanın (örn. /path/to/chdb/data)

Yaygın yapılandırma tuzakları

• CLICKHOUSE_SECURE ile MCP / ingress TLS — MCP sunucusu Kubernetes ingress, ters proxy arkasında olduğu veya düz HTTP üzerinden erişildiği için CLICKHOUSE_SECURE kapatmak veritabanı TLS'ini devre dışı bırakmaz; yalnızca bu işlemin ClickHouse'a nasıl bağlandığını değiştirir. Ingress TLS'i veritabanı istemci ayarlarından ayrı olarak yapılandırın.
• Yerel protokol portları — CLICKHOUSE_PORT, ClickHouse'un HTTP arayüzünü hedeflemelidir (varsayılan olarak 8123/8443). 9000/9440 portları yerel TCP protokolü içindir (clickhouse-client) ve bu sunucuyla çalışmaz.
• Ana bilgisayar karışıklığı — CLICKHOUSE_HOST veritabanı ana bilgisayar adıdır. CLICKHOUSE_MCP_BIND_HOST yalnızca MCP HTTP/SSE sunucusunun dinlediği adrestir.

Örnek Yapılandırmalar

Docker ile yerel geliştirme için:

# Required variables
CLICKHOUSE_HOST=localhost
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=clickhouse

# Optional: Override defaults for local development
CLICKHOUSE_SECURE=false  # Uses port 8123 automatically
CLICKHOUSE_VERIFY=false

ClickHouse Cloud için:

# Required variables
CLICKHOUSE_HOST=your-instance.clickhouse.cloud
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-password

# Optional: These use secure defaults
# CLICKHOUSE_SECURE=true  # Uses port 8443 automatically
# CLICKHOUSE_DATABASE=your_database

ClickHouse SQL Playground için:

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

İstemci sertifikası kimlik doğrulaması olmayan özel bir sunucu CA'sı için:

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

ClickHouse X.509 istemci sertifikası kimlik doğrulaması için:

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.

ClickHouse Temel kimlik doğrulaması kullanırken katı bir TLS sunucusu tarafından gereken bir istemci sertifikası için:

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

Use CLICKHOUSE_TLS_MODE=proxy instead when a TLS-terminating proxy requires the client certificate and ClickHouse still uses Basic authentication.

For chDB only (in-memory):

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

For chDB with persistent storage:

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

For MCP Inspector or remote access with HTTP transport:

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

For local development with HTTP transport (authentication disabled):

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

When using HTTP transport, the server will run on the configured port (default 8000). For example, with the above configuration:

• MCP endpoint: http://localhost:8000/mcp
• Health check: http://localhost:8000/health

You can set these variables in your environment, in a .env file, or in the Claude Desktop configuration:

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

Note: The bind host and port settings are only used when transport is set to "http" or "sse".

Running tests

uv sync --all-extras --dev # install dev dependencies
uv run ruff check . # run linting

docker compose up -d test_services # start ClickHouse
uv run pytest -v tests
uv run pytest -v tests/test_tool.py # ClickHouse only
CHDB_ENABLED=true uv run --extra chdb pytest -v tests/test_chdb_tool.py # chDB only

YouTube Overview