ClickHouse

ClickHouse MCP Sunucusu

ClickHouse için bir MCP sunucusu.

Özellikler

ClickHouse Araçları

• run_query

  • ClickHouse kümenizde SQL sorguları çalıştırın.
  • Girdi: query (string): Çalıştırılacak SQL sorgusu.
  • Sorgular varsayılan olarak salt-okunur modda çalışır (CLICKHOUSE_ALLOW_WRITE_ACCESS=false), ancak gerekirse yazma işlemleri açıkça etkinleştirilebilir.

• list_databases

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

• list_tables

  • Sayfalama ile bir veritabanındaki tabloları listeleyin.
  • Zorunlu girdi: database (string).
  • İsteğe bağlı girdiler:
    • like / not_like (string): Tablo adlarına LIKE veya NOT LIKE filtreleri uygulayın.
    • page_token (string): Sonraki sayfayı getirmek için önceki çağrı tarafından döndürülen belirteç.
    • page_size (int, varsayılan 50): Sayfa başına döndürülen tablo sayısı.
    • 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 değeri geri iletin veya daha fazla tablo kalmadığında null.
    • total_tables: Sağlanan filtrelerle eşleşen toplam tablo sayısı.

chDB Araçları

• run_chdb_select_query
  • chDB'nin gömülü ClickHouse motorunu kullanarak SQL sorguları çalıştırın.
  • Girdi: query (string): Çalıştırılacak SQL sorgusu.
  • 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şımacılığı ile çalışırken, /health adresinde bir sağlık kontrolü uç noktası mevcuttur. 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

Uç nokta kasıtlı olarak kimlik doğrulamasız bırakılmıştır, böylece orkestratör probları (örn. Kubernetes canlılık/hazırlık, yük dengeleyiciler) kimlik bilgileri olmadan erişebilir. 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üzeyde tutulur; hataları sunucu günlükleri aracılığıyla ayıklayın.

Örnek:

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

Güvenlik

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

HTTP veya SSE taşımacılığı kullanı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:

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 dahil edecek ş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.) ile ü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. Sağlayıcıya özgü FASTMCP_SERVER_AUTH_* değişkenleriyle birlikte FASTMCP_SERVER_AUTH değerini bir FastMCP kimlik doğrulama sağlayıcısının tam sınıf yoluna ayarlayın ve CLICKHOUSE_MCP_AUTH_TOKEN değerini ayarlanmamış 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>"

Sağlayıcıların tam listesi ve gereken ortam değişkenleri için FastMCP belgelerine bakın.

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

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 bağlı olarak birini veya her ikisini de etkinleştirebilirsiniz.

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.10", "mcp-clickhouse" ], "env": { "CLICKHOUSE_HOST": "<clickhouse-host>", "CLICKHOUSE_PORT": "<clickhouse-port>", "CLICKHOUSE_USER": "<clickhouse-user>", "CLICKHOUSE_PASSWORD": "<clickhouse-password>", "CLICKHOUSE_ROLE": "<clickhouse-role>", "CLICKHOUSE_SECURE": "true", "CLICKHOUSE_VERIFY": "true", "CLICKHOUSE_CONNECT_TIMEOUT": "30", "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30" } } }
}

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.10", "mcp-clickhouse" ], "env": { "CLICKHOUSE_HOST": "sql-clickhouse.clickhouse.com", "CLICKHOUSE_PORT": "8443", "CLICKHOUSE_USER": "demo", "CLICKHOUSE_PASSWORD": "", "CLICKHOUSE_SECURE": "true", "CLICKHOUSE_VERIFY": "true", "CLICKHOUSE_CONNECT_TIMEOUT": "30", "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30" } } }
}

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.10", "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.10", "mcp-clickhouse" ], "env": { "CLICKHOUSE_HOST": "<clickhouse-host>", "CLICKHOUSE_PORT": "<clickhouse-port>", "CLICKHOUSE_USER": "<clickhouse-user>", "CLICKHOUSE_PASSWORD": "<clickhouse-password>", "CLICKHOUSE_SECURE": "true", "CLICKHOUSE_VERIFY": "true", "CLICKHOUSE_CONNECT_TIMEOUT": "30", "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30", "CHDB_ENABLED": "true", "CHDB_DATA_PATH": "/path/to/chdb/data" } } }
}

3. uv için komut girdisini bulun ve uv yürütülebilir dosyasının mutlak yoluyla 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 kazara değişikliklerin olamaması 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 yazma işlemlerine 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 ve SQL yorumlarındaki anahtar kelimeler yok sayılır, bu nedenle kontrolü tetiklemezler veya 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 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ışı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, kazara 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 kurabilir ve 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", "CLICKHOUSE_SEND_RECEIVE_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", "CLICKHOUSE_SEND_RECEIVE_TIMEOUT": "30" } } }
}

Not: Sistem PATH'inizde değillerse, Python yürütülebilir dosyasının veya mcp-clickhouse betiğinin 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.) kesmenize ve işlemenize olanak tanıyan bir ara katman sistemi sağlar.

Nasıl Kullanılır

1. Middleware sınıfını 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.10", "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 (örn. 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ç çalıştırıldığında ç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 aracılığıyla 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 mcp_clickhouse.mcp_server import CLIENT_CONFIG_OVERRIDES_KEY ctx = get_context()
ctx.set_state(CLIENT_CONFIG_OVERRIDES_KEY, { "connect_timeout": 60, "send_receive_timeout": 120
})

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ıdır 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ı ve generic_args altındaki aynı anahtarlar reddedilir.

Bu geçersiz kılmaları güvenilir ara katman girdisi olarak değerlendirin. Ara katman, bunları ayarlamadan önce istekten türetilen değerlerin kimliğini doğrulamalı ve yetkilendirmelidir. İ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 dizinindeki 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ı yüklemek için uv sync komutunu çalıştırın. uv kurmak için buradaki talimatları izleyin. Ardından source .venv/bin/activate komutunu çalıştırın.

4. MCP Inspector ile kolay test için MCP sunucusunu başlatmak üzere fastmcp dev mcp_clickhouse/mcp_server.py komutunu ç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 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:

[!IMPORTANT]
CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY ve CLICKHOUSE_PORT gibi değişkenler yalnızca ClickHouse veritabanı bağlantısına uygulanır. MCP protokol uç noktası için TLS, 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 değerini pod'un ClickHouse'a 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 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.

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

[!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 en düşük 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ıkça 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 veriyorsa, 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 (yerel Docker Compose için 8123 bağlantı noktasında 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. 8443 bağlantı noktasına karşı 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, truststore aracılığıyla TLS sertifika doğrulaması için işletim sistemi güven deposunu kullanır. Doğru sertifika işlemeyi sağlamak için başlangıçta truststore.inject_into_ssl() çağırırız. Python'un varsayılan SSL davranışı yalnızca beklenmeyen bir hata oluşursa yedek olarak kullanılır.
• 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 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"
  • Uzun süren sorgular için bu değeri artırın
• 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 karşı 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 iyi niyetli 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ı)

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ı/bağlantı noktası)
• CLICKHOUSE_MCP_BIND_HOST: HTTP veya SSE taşıması kullanırken MCP sunucusunu bağlayacağı ana bilgisayar
  • Varsayılan: "127.0.0.1"
  • Tüm ağ arayüzlerine bağlamak 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ırken MCP sunucusunu bağlayacağı 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 araç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
• 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'den 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 kimlik doğrulama 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, FastMCP sağlayıcıyı kendi FASTMCP_SERVER_AUTH_* ortam değişkenlerinden otomatik yükler; bu modda CLICKHOUSE_MCP_AUTH_TOKEN ayarını boş bırakın
• CLICKHOUSE_MCP_AUTH_DISABLED: HTTP/SSE taşımaları için kimlik doğrulamayı devre dışı bırakın
  • 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

Ara Katman Değişkenleri

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

chDB Değişkenleri

• CHDB_ENABLED: chDB işlevselliğini etkinleştirin/devre dışı bırakın
  • Varsayılan: "false"
  • chDB araçlarını etkinleştirmek için "true" olarak ayarlayın
  • İsteğe bağlı ekstra kurulum 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 / 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'sini devre dışı bırakmaz; yalnızca bu sürecin ClickHouse'a nasıl bağlandığını değiştirir. Ingress TLS'yi veritabanı istemci ayarlarından ayrı 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)

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)

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!

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:4200/mcp
• Sağlık kontrolü: http://localhost:4200/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.10", "mcp-clickhouse" ], "env": { "CLICKHOUSE_HOST": "<clickhouse-host>", "CLICKHOUSE_USER": "<clickhouse-user>", "CLICKHOUSE_PASSWORD": "<clickhouse-password>", "CLICKHOUSE_DATABASE": "<optional-database>", "CLICKHOUSE_MCP_SERVER_TRANSPORT": "stdio", "CLICKHOUSE_MCP_BIND_HOST": "127.0.0.1", "CLICKHOUSE_MCP_BIND_PORT": "8000" } } }
}

Not: Bağlama ana bilgisayarı ve port ayarları yalnızca transport "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ış