ClickHouse

resmi

ClickHouse veritabanı sunucunuzu sorgulayın.

GitHub
902

ClickHouse MCP ile neler yapabilirsiniz?

  • Run SQL sorguları — ClickHouse kümenizde run_query ile herhangi bir SQL sorgusunu çalıştırmasını isteyin; params ile isteğe bağlı adlandırılmış parametreler ekleyebilirsiniz.
  • Veritabanlarını listele — list_databases kullanarak ClickHouse kümenizdeki tüm veritabanlarını keşfedin.
  • Filtrelerle tablolara göz at — Bir veritabanındaki tabloları keşfetmek için list_tables kullanın; like/not_like desenleri ve page_token ile page_size üzerinden sayfalama uygulayın.
  • Sorgu şemalarını incele — Çalıştırmadan önce çıktı sütunlarını veya tahmini okumaları kontrol etmek için run_query ile DESCRIBE (<query>) veya EXPLAIN ESTIMATE <query> isteyin.
  • Gömülü chDB verilerini sorgula — ETL olmadan dosyaları, URL'leri veya veritabanlarını sorgulamak için run_chdb_select_query kullanarak doğrudan chDB'nin gömülü motoruna SQL çalıştırın.

Dokümantasyon

ClickHouse MCP Sunucusu

PyPI - Version

ClickHouse için bir MCP sunucusu.

mcp-clickhouse MCP server

Sunucu, MCP 2026-07-28 protokolünü uygular ve 2024-11-05 ile 2025-11-25 arasındaki sürümlerden 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, her POST isteğinde başlığı 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. Sorguyu çalıştırmadan önce kontrol etme bölümüne bakın.

  • list_databases

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

  • list_tables

    • Sayfalama ile bir veritabanındaki tabloları 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 iletin.
      • total_tables: Sağlanan filtrelerle eşleşen toplam tablo sayısı.

Aracılar Şema Keşfi

Sunucu talimatları, analitik SQL yazmadan önce list_databases bir AGENTS veritabanı ortaya çıkardığında Agents Schema belgesinin kanonik AGENTS.ROOT ile run_query bölümlerini okumayı önerir. Bu, aracı için bir rehberdir: otomatik olarak hiçbir meta veri getirilmez, araç sonuçları değişmez ve mevcut ClickHouse izinleri geçerliliğini korur. AGENTS.ROOT eksikse veya erişilemezse, normal keşif ve sorgular kullanılabilir durumda kalır.

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 boşluklar 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 "18446744073709551615" ile {id:UInt64}. 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 {vector:Array(Float32)} ile "params": {"vector": [0.25, 0.5, 0.75]}.
  • Diziler 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; bu, yorumlardaki veya dize değişmezlerindeki yer tutucu benzeri metinleri de içerir. 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 yerleştirir. 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.

Sorguyu Çalıştırmadan Önce 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ütme sırası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, birincil anahtar ve bölüm budamasından sonra MergeTree ailesi tablolarından tahmini okumalardır. Çalışma süresi veya sonuç boyutu değildir ve diğer tablo motorları kapsanmaz.

Hiçbir ifade 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 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 ekstra gerektirir: pip install 'mcp-clickhouse[chdb]'

Sağlık Kontrolü Uç Noktası

HTTP veya SSE taşıması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ı art arda 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) ekstra 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; hataları sunucu günlükleri aracılığıyla ayıklayın.

Örnek:

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

Güvenlik

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

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

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

ModNe zaman kullanılırOrtam değişkeni
Statik taşıyıcı belirteciBasit dağıtımlar, dahili hizmetlerCLICKHOUSE_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 özel FASTMCP_SERVER_AUTH_* değişkenleri)
Devre dışıYalnızca yerel geliştirmeCLICKHOUSE_MCP_AUTH_DISABLED=true

HTTP/SSE taşımaları 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 dahil edecek şekilde yapılandırın:

    HTTP/SSE taşımalı 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 özel 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 yoluSağlayıcı değişken öneki
fastmcp.server.auth.providers.auth0.Auth0ProviderFASTMCP_SERVER_AUTH_AUTH0_
fastmcp.server.auth.providers.aws.AWSCognitoProviderFASTMCP_SERVER_AUTH_AWS_COGNITO_
fastmcp.server.auth.providers.azure.AzureProviderFASTMCP_SERVER_AUTH_AZURE_
fastmcp.server.auth.providers.descope.DescopeProviderFASTMCP_SERVER_AUTH_DESCOPEPROVIDER_
fastmcp.server.auth.providers.discord.DiscordProviderFASTMCP_SERVER_AUTH_DISCORD_
fastmcp.server.auth.providers.github.GitHubProviderFASTMCP_SERVER_AUTH_GITHUB_
fastmcp.server.auth.providers.google.GoogleProviderFASTMCP_SERVER_AUTH_GOOGLE_
fastmcp.server.auth.providers.introspection.IntrospectionTokenVerifierFASTMCP_SERVER_AUTH_INTROSPECTION_
fastmcp.server.auth.providers.jwt.JWTVerifierFASTMCP_SERVER_AUTH_JWT_
fastmcp.server.auth.providers.oci.OCIProviderFASTMCP_SERVER_AUTH_OCI_
fastmcp.server.auth.providers.scalekit.ScalekitProviderFASTMCP_SERVER_AUTH_SCALEKITPROVIDER_
fastmcp.server.auth.providers.supabase.SupabaseProviderFASTMCP_SERVER_AUTH_SUPABASE_
fastmcp.server.auth.providers.workos.WorkOSProviderFASTMCP_SERVER_AUTH_WORKOS_
fastmcp.server.auth.providers.workos.AuthKitProviderFASTMCP_SERVER_AUTH_AUTHKITPROVIDER_

Öneke, sağlayıcı alan adının büyük harfli halini 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 auth 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şlangıçtan ö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 keşfedilen hem de çalışma dizinindeki .env dosyalarını güvenilir kimlik doğrulama yapılandırması olarak ele alın. Paket dizininden dosya sistemi köküne kadar herhangi bir dizinde .env oluşturabilen veya yazabilen herkes, hangi dosyanın keşfedileceğini kontrol edebilir, sağlayıcıyı seçebilir ve alanlarını ayarlayabilir. Çalışma dizini dosyasını yazabilen herkes, süreç ve keşfedilen 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 dosyaya 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 gerektirmelidir. 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. Şu konumda bulunan Claude Desktop yapılandırma dosyasını 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 hizmetinize 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 ClickHouse ve 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"
      }
    }
  }
}

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

  2. Değişiklikleri uygulamak için Claude Desktop'u 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 yazmaları devre dışı bırakırsa sunucu salt okunur modu uygulamaya devam eder.

Salt okunur mod, ClickHouse kullanıcısının kendi sorgularını, aynı kullanıcıyı kullanan diğer bağlantılardan gelen sorgular dahil, iptal etmesine hâlâ izin verir. Salt okunur modda bile özel bir ClickHouse kullanıcısı kullanın. Birbirlerinin sorgularını iptal etmemesi gereken iş yükleri için ayrı ClickHouse kullanıcıları kullanın.

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 veya bir ifadeyi ondan 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 aracılığıyla 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ışında ayrıcalıklar gerektiren veri değiştiren işlemler, 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'unu 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 Yazılım

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

Nasıl Kullanılır

  1. Middleware genişleten ara yazılım 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())
  1. 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"
      }
    }
  }
}
  1. Ara yazılım 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 Yazılım

example_middleware.py içinde yaygın desenleri gösteren bir örnek ara yazılım 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 Yazılım 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 yazılım, 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ıkça 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ıkça ortam parolasıyla Temel kimlik doğrulaması kullanır.

Bu geçersiz kılmaları güvenilir ara yazılım girdisi olarak ele alın. Ara yazılım, 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 bir oturum kapsamlı geçersiz kılma, eski bir MCP oturumuna ekli 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 zorunlu kılın.

Geliştirme

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

  2. Deponun 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

  1. Bağımlılıkları yüklemek için uv sync komutunu çalıştırın. uv yüklemek için buradaki talimatları izleyin. Ardından source .venv/bin/activate işlemini yapın.

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

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

Kod Düzeni

Paket, düz bir modül düzeni kullanır. Sunucu derlemesi ve kaydı için mcp_server.py ile başlayın, ardından uygulamayı sahip olduğu modüle kadar takip edin.

ModülSorumluluk
mcp_server.py, main.pyBaşlangıç derlemesi, araç ve komut kaydı, kapanış koordinasyonu ve CLI başlangıcı
clients.pyİstek yapılandırması, önbelleğe alınmış ClickHouse bağlantıları ve istemci kiralamaları
queries.pySorgu yürütme, iptal ve yıkıcı işlem korumaları
metadata.pyVeritabanı ve tablo keşfi, meta veri modelleri ve sayfalama
chdb_backend.py, chdb_prompt.pyİsteğe bağlı chDB başlatma, sorgu yürütme ve komut içeriği
health.py, executors.pySağlık kontrolleri ve önbellekleme ile sunucu işlemlerinde kullanılan çalışan havuzları
auth.py, transport.py, http_security.pyDotenv yükleme, kimlik doğrulama, HTTP/SSE uygulama kurulumu ve Host/Origin doğrulaması
mcp_env.py, serialization.pyOrtam yapılandırması ve JSON sonuç kodlaması
mcp_middleware_hook.py, skills_advisor.pyÖzel ara katman yükleme ve sunucu talimatları

Her sunucu derlemesi kendi çalışan havuzlarına, istemci önbelleğine, aktif sorgularına, sayfalama önbelleğine, sağlık durumuna ve chDB arka ucuna sahiptir. Çalışan ve istemci temizliği işlem çıkışında çalışır. Paket içe aktarımları, çıkarılmış bir modül ilk içe aktarıldığında bile varsayılan sunucuyu başlatır.

Testlerde, kodun bir bağımlılığı okuduğu modülü veya sahip örneğini yamalayın. Örneğin, istemci oluşturma için mcp_clickhouse.clients.clickhouse_connect.get_client öğesini yamalayın. mcp_server.py içindeki uyumluluk içe aktarımları, bir uygulamanın kullandığı bağlamalardan ayrı bağlamalar olabilir.

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:

GrupDeğişkenlerKontroller
ClickHouse veritabanı bağlantısıCLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY, sertifika değişkenleriBu MCP sunucusunun ClickHouse kümenize HTTP arayüzü üzerinden nasıl bağlandığı
MCP sunucusu / taşımaCLICKHOUSE_MCP_*, FASTMCP_SERVER_AUTH, FASTMCP_SERVER_AUTH_*, FASTMCP_ENV_FILEMCP taşıması, kimlik doğrulama ve sorgu aracı yürütme sınırları
Ara katman / chDBMCP_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 girişin arkasında çalışıyorsa, bu bir MCP taşıma konusudur. CLICKHOUSE_SECURE değerini, podun ClickHouse'un kendisine nasıl ulaştığıyla uyumlu tutun (HTTPS → true, düz HTTP → false). MCP sunucusu bir girişin arkasında olduğu için CLICKHOUSE_SECURE=false ayarlamak, sunucunun ClickHouse'a HTTP üzerinden bağlanmasına neden olur—genellikle yalnızca HTTPS olan 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 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: CLICKHOUSE_SECURE=true ise 8443, CLICKHOUSE_SECURE=false ise 8123
    • Standart olmayan bir bağlantı noktası kullanılmadığı sürece genellikle ayarlanması gerekmez
    • 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 işaret ediyorsunuz; 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 olan 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 giriş üzerinden sunulsa bile
    • Bu bayrağı veritabanı bağlantı noktasıyla eşleştirmemek (örn. bağlantı noktası 8443 karşısında CLICKHOUSE_SECURE=false) 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. MCP_CLICKHOUSE_TRUSTSTORE_DISABLE=1 ile enjeksiyon 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 sertifikası 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 ayarlayın.
    • ClickHouse kullanıcısı yine de CLICKHOUSE_USER'dan 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 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 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 sertifikası doğrulamasını güçlendirmez. CLICKHOUSE_VERIFY bu doğrulamayı kontrol eder.
    • clickhouse-connect, "proxy" ve "strict" 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 yolu öneki
    • Varsayılan: Yok
    • ClickHouse HTTP arayüzü bir ters proxy'nin 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'nin düşük olanı, böylece çalışan iş parçacıkları bir sorgu zaman aşımından kısa süre sonra engeli kaldırır
    • Açıkça ayarlanırsa, değer olduğu gibi kullanılır (örn. 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 ALTER TABLE varyantları dahil UPDATE, 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 dosya yollarını içerir, PEM içeriklerini değil. 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 imaja 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 sürecini 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 rotasyon 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 MCP sürecinin kendisini kontrol eder; taşıma, kimlik doğrulama ve sorgu aracı yürütme sınırlarını içerir. Bunlar yukarıdaki ClickHouse veritabanı ayarlarından bağımsızdır. 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 açığa çıkarır (aşağıdaki bağlama ana bilgisayarını/bağlantı noktasını kullanır)
    • "sse" kullanımdan kaldırılmış bağımsız HTTP+SSE taşımasını seçer ve bir uyarı günlüğe 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 ilgili değildir
  • CLICKHOUSE_MCP_BIND_PORT: HTTP veya SSE taşıması kullanılırken MCP sunucusunun bağlanacağı bağlantı noktası
    • Varsayılan: "8000"
    • Yalnızca taşıma "http" veya "sse" olduğunda kullanılır — CLICKHOUSE_PORT ile ilgili değildir
  • 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ürseniz 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ırlandırılır
  • CLICKHOUSE_MCP_MAX_WORKERS: Maksimum eşzamanlı sorgu çalışan iş parçacığı 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ığına sahip 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, ör. 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 ayarını boş 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 özgü 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 işlem ortamında 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 dizininde 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çbir şeyi 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 kontrolü 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 için "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 bağlantı noktası biçimleri
    • Ayarlanırsa, değer en az bir Host girdisi içermelidir.
    • Somut bir geri döngü olmayan bağlama adresi, varsayılan olarak bu adrese ve yapılandırılan bağlantı noktasına ayarlanır. 0.0.0.0 veya :: gibi bir joker karakter bağlaması, genel Host çıkarılamadığı için açık ve boş olmayan bir değer gerektirir.
    • Host 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 bağlantı noktasını kabul eder (localhost:*). Örnek: CLICKHOUSE_MCP_ALLOWED_HOSTS=127.0.0.1:8000,localhost:8000
    • host:* biçimi yalnızca bir bağlantı noktası taşıyan değerlerle eşleşir. Bağlantı noktası olmayan bir Host (istemcinin :80/:443 değerini atladığı standart bağlantı noktalı bir dağıtım) ayrıca çıplak bir tam girdi (example.com) olarak listelenmelidir.
    • Eşleşmeyen veya eksik Host başlığına sahip istekler 421 Misdirected Request alır. /health adresine yapılan GET ve HEAD istekleri, orkestratör yoklama problarının çalışmaya devam etmesi için Host ve Origin 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ı Host ve Origin korumasını zorla kapatır. 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, ör. 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. Güvenilen her 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 oluşturmalıdır.
    • Yerleşik sunucu ve fastmcp run, Uvicorn'un dış proxy başlığı işlemesini devre dışı bırakır, Host'u ham eşden doğrular ve ardından X-Forwarded-For ve X-Forwarded-Proto uygular. Bu modda uvicorn_config["proxy_headers"] öğesini 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 onaylama 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 Origin doğrulaması gerektirir. Origin olmayan istekler kabul edilir çünkü tarayıcı olmayan MCP istemcileri normalde onu atlar. Eşleşmeyen bir Origin 403 Forbidden alır. /health uç noktası yukarıda açıklandığı gibi muaftır.
    • Girdiler tamdır (http://localhost:3000) veya herhangi bir bağlantı noktasını kabul eder (http://localhost:*). Ana bilgisayarlarda olduğu gibi, herhangi bir bağlantı noktası biçimi yalnızca bir bağlantı noktası taşıyan kaynaklarla eşleşir; standart bağlantı noktalı bir kaynak (https://app.example.com) tam olarak listelenmelidir.
Ters proxy Host işleme

Mümkün olduğunda Host koruyun. Bu, iletilen Host güvenini devre dışı tutar:

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 bağlantı noktası 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 ve ü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 (ör. externalTrafficPolicy: Cluster) gözlemlenen eş, proxy pod'u yerine bir düğüm IP'si olabilir; bu nedenle uygun şekilde pod veya düğüm CIDR'sine güvenin; ingress-nginx hem Host hem de X-Forwarded-Host değerlerini kendisi üzerine yazar.

Ara katman yazılımı değişkenleri

  • MCP_MIDDLEWARE_MODULE: MCP sunucusuna eklenecek özel ara katman yazılımını içeren Python modül adı
    • Varsayılan: Yok (ara katman yazılımı yüklenmez)
    • Ara katman 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 Katman Yazılımı bölümüne bakın

chDB Değişkenleri

  • CHDB_ENABLED: chDB işlevselliğini etkinleştir/devre dışı bırak
    • Varsayılan: "false"
    • chDB araçlarını etkinleştirmek için "true" olarak ayarlayın
    • İsteğe bağlı ek 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 (ör. /path/to/chdb/data)

Yaygın yapılandırma tuzakları

  • CLICKHOUSE_SECURE ile MCP / giriş TLS'si — MCP sunucusu Kubernetes girişinin, bir ters proxy'nin arkasında olduğu veya düz HTTP üzerinden erişildiği için CLICKHOUSE_SECURE kapatmak veritabanı TLS'sini devre dışı bırakmaz; bu yalnızca bu sürecin ClickHouse'a nasıl bağlandığını değiştirir. Giriş TLS'sini veritabanı istemci ayarlarından ayrı olarak yapılandırın.
  • Yerel protokol bağlantı noktaları — CLICKHOUSE_PORT, ClickHouse'un HTTP arayüzünü hedeflemelidir (varsayılan olarak 8123/8443). 9000/9440 bağlantı noktaları 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 istemci sertifikası gerektiğinde:

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

TLS sonlandıran bir proxy istemci sertifikası gerektirdiğinde ve ClickHouse hâlâ Temel kimlik doğrulaması kullandığında CLICKHOUSE_TLS_MODE=proxy kullanın.

Yalnızca chDB için (bellek içi):

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

Kalıcı depolamalı chDB için:

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

MCP Inspector veya HTTP taşımasıyla uzaktan erişim için:

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

HTTP taşımasıyla yerel geliştirme için (kimlik doğrulama devre dışı):

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

HTTP taşıması kullanıldığında, sunucu yapılandırılan bağlantı noktasında (varsayılan 8000) çalışır. Örneğin, yukarıdaki yapılandırmayla:

  • MCP uç noktası: http://localhost:8000/mcp
  • Sağlık kontrolü: http://localhost:8000/health

Bu değişkenleri ortamınızda, bir .env dosyasında veya Claude Desktop yapılandırmasında ayarlayabilirsiniz:

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

Not: Bağlama ana bilgisayarı ve bağlantı noktası ayarları yalnızca taşıma "http" veya "sse" olarak ayarlandığında kullanılır.

Testleri çalıştırma

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 Genel Bakış

YouTube