ClickHouse

resmi

ClickHouse veritabanı sunucunuzu sorgulayın.

GitHub

839

Click House MCP ile neler yapabilirsiniz?

Salt okunur SQL sorguları çalıştırın — Asistanınızdan, run_query kullanarak ClickHouse kümenizde herhangi bir SELECT sorgusu çalıştırmasını isteyin.
Veritabanlarını ve tabloları listeleyin — Tüm veritabanlarını list_databases ile listeleyerek veya belirli bir veritabanındaki tabloları list_tables ile sayfalayarak şemanızı keşfedin.
Dosyaları ve URL'leri doğrudan chDB ile sorgulayın — Yerel dosyalara veya uzak veri kaynaklarına karşı, önce ClickHouse'a yüklemeden SQL çalıştırmak için run_chdb_select_query kullanın.
Yazma ve yıkıcı işlemleri kontrol edin — DDL/DML için CLICKHOUSE_ALLOW_WRITE_ACCESS etkinleştirin ve isteğe bağlı olarak, AI destekli oturumlar sırasında DROP veya TRUNCATE ifadelerine izin vermek için CLICKHOUSE_ALLOW_DROP etkinleştirin.

Dokümantasyon

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
- Bir veritabanındaki tabloları sayfalandırma ile listeleyin.
- Gerekli 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 şekli:
  - 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 olmadığı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 paketini gerektirir: pip install 'mcp-clickhouse[chdb]'

Sağlık Kontrolü Uç Noktası

HTTP veya SSE aktarımı 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 (gövde: OK) döndürür
Sunucu ClickHouse'a bağlanamıyorsa genel bir hata mesajıyla 503 Service Unavailable döndürür

Uç nokta, orkestratör sondalarının (ör. Kubernetes canlılık/hazır olma, yük dengeleyiciler) kimlik bilgileri olmadan erişebilmesi için kasıtlı olarak kimlik doğrulamasızdır. 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 Aktarımları için Kimlik Doğrulama

HTTP veya SSE aktarımı kullanırken, kimlik doğrulama varsayılan olarak zorunludur. stdio aktarımı (varsayılan), yalnızca standart girdi/çıktı aracılığıyla iletişim kurduğu için kimlik doğrulama gerektirmez.

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

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

HTTP/SSE aktarımları için bunlardan hiçbiri yapılandırılmamışsa başlatma başarısız olur.

Kimlik Doğrulamayı Ayarlama

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

# Using uuidgen (macOS/Linux)
uuidgen

# Using openssl
openssl rand -hex 32

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

export CLICKHOUSE_MCP_AUTH_TOKEN="your-generated-token"

MCP istemcinizi isteklere belirteci dahil edecek şekilde yapılandırın:

HTTP/SSE aktarımı 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 gerçekten kimlik doğrulamasız istekleri reddettiğini doğrulamak için, MCP uç noktasının kendisine, örneğin MCP Inspector ile veya /mcp adresine Authorization başlığı ile ve başlık olmadan bir JSON-RPC isteği POST'layarak vurun ve kimlik doğrulamasız çağrının 401 döndürdüğünü onaylayın.

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. FASTMCP_SERVER_AUTH değerini bir FastMCP kimlik doğrulama sağlayıcısının tam sınıf yoluna, sağlayıcıya özel FASTMCP_SERVER_AUTH_* değişkenleriyle birlikte 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 gerekli 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, aşağıdakini ayarlayarak kimlik doğrulamayı 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.

Ş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
Aşağıdakini 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"
      }
    }
  }
}

Ortam değişkenlerini kendi ClickHouse hizmetinizi işaret edecek şekilde güncelleyin.

Veya ClickHouse SQL Oyun Alanı 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 hem ClickHouse'ı hem de 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"
      }
    }
  }
}

uv için komut girişini bulun ve bunu uv yürütülebilir dosyasının mutlak yolu ile değiştirin. Bu, sunucu başlatılırken uv'in doğru sürümünün kullanılmasını sağlar. Mac'te bu yolu which uv kullanarak bulabilirsiniz.
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 mutasyonların gerçekleşmemesi için salt okunur sorguları zorunlu kılar. DDL veya INSERT/UPDATE ifadelerine izin vermek için CLICKHOUSE_ALLOW_WRITE_ACCESS ortam değişkenini true olarak ayarlayın. ClickHouse örneğinin kendisi yazmalara izin vermiyorsa, sunucu salt okunur modu uygulamaya devam eder.

Yıkıcı İşlem Koruması

Yazma erişimi etkinleştirilmiş olsa bile (CLICKHOUSE_ALLOW_WRITE_ACCESS=true), yıkıcı işlemler (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE) güvenlik için ek bir katılım bayrağı gerektirir. Bu, AI keşfi sırasında kazara veri silinmesini önler.

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 silmelerin çok zor olmasını sağlar:

Yazma işlemleri (INSERT, UPDATE, CREATE) CLICKHOUSE_ALLOW_WRITE_ACCESS=true gerektirir
Yıkıcı işlemler (DROP, TRUNCATE) ek olarak CLICKHOUSE_ALLOW_DROP=true gerektirir

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

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

Paketi pip kullanarak yükleyin:

python3 -m pip install mcp-clickhouse

chDB desteğini de yüklemek 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

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, yüklenen 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: Python yürütülebilir dosyasının veya mcp-clickhouse betiğinin tam yolunu kullandığınızdan emin olun, eğer sistem PATH'inizde değillerse. Yolları şunları kullanarak bulabilirsiniz:

Python yürütülebilir dosyası için which python3
Yüklenen 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.) yakalamanıza ve işlemenize olanak tanıyan bir ara yazılım sistemi sağlar.

Nasıl Kullanılır

Middleware'i 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())

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

Ara yazılım modülünüzün Python'un içe aktarma yolunda olduğundan emin olun (örneğin, MCP sunucusunun çalıştığı dizinde veya bir paket olarak yüklenmiş).

Örnek Ara Yazılım

example_middleware.py içinde yaygın kalıpları 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 işlem hattını 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 istek bazında ClickHouse istemci yapılandırmasını geçersiz kılabilir. Sunucu, bu geçersiz kılmaları ortam değişkenlerinden gelen temel yapılandırma ile 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ı mümkün kılar.

Geliştirme

ClickHouse kümesini başlatmak için test-services dizininde docker compose up -d komutunu çalıştırın.
Deponun kökündeki 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

Bağımlılıkları yüklemek için uv sync komutunu çalıştırın. uv'i yüklemek için buradaki talimatları izleyin. Ardından source .venv/bin/activate yapın.
MCP Inspector ile kolay test için, MCP sunucusunu başlatmak üzere fastmcp dev mcp_clickhouse/mcp_server.py komutunu çalıştırın.

HTTP aktarımı ve sağlık kontrolü uç noktası ile 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:

Grup	Değişkenler	Kontrol Ettiği
ClickHouse veritabanı bağlantısı	`CLICKHOUSE_HOST`, `CLICKHOUSE_PORT`, `CLICKHOUSE_SECURE`, `CLICKHOUSE_VERIFY`, …	Bu MCP sunucusunun ClickHouse kümenize HTTP arayüzü üzerinden nasıl bağlandığı
MCP sunucusu / aktarım	`CLICKHOUSE_MCP_`, `FASTMCP_SERVER_AUTH`, `FASTMCP_SERVER_AUTH_`	MCP aktarımı, kimlik doğrulama ve sorgu aracı yürütme limitleri
Ara yazılım / chDB	`MCP_MIDDLEWARE_MODULE`, `CHDB_*`	İsteğe bağlı uzantılar

[!ÖNEMLİ] CLICKHOUSE_SECURE, CLICKHOUSE_VERIFY ve CLICKHOUSE_PORT gibi değişkenler yalnızca ClickHouse veritabanı bağlantısı için geçerlidir. 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 girişin arkasında çalışıyorsa, bu bir MCP aktarımı sorunudur. CLICKHOUSE_SECURE değerini, pod'un ClickHouse'a 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'u HTTP üzerinden aramasına neden olur — genellikle yalnızca HTTPS bağlantı noktasına karşı — 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ğlanma 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 yalnızca çalışması için gereken minimum ayrıcalıkları vermeniz önemlidir. Varsayılan veya yönetici kullanıcıların kullanımından her zaman kesinlikle kaçınılmalıdır.

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

CLICKHOUSE_PORT: ClickHouse sunucunuzun HTTP arayüz portu
- Varsayılan: 8443 eğer CLICKHOUSE_SECURE=true ise, 8123 eğer CLICKHOUSE_SECURE=false ise
- Standart olmayan bir port kullanılmadığı sürece genellikle ayarlanması gerekmez
- Bir HTTP arayüz portu olmalıdır, clickhouse-client tarafından kullanılan yerel TCP protokol portu değil
- Yaygın değerler:
  - HTTP: 8123 (düz) / 8443 (TLS) — bu sunucu ve ClickHouse Cloud HTTPS tarafından kullanılır
  - Yerel TCP (burada desteklenmez): 9000 (düz) / 9440 (TLS) — clickhouse-client tarafından kullanılır
- Sunucu Port 9000 is for clickhouse-client program ile yanıt verirse, yerel protokole yönlendiriliyorsunuz demektir; HTTP portuna geçin (8123/8443 veya dağıtımınızın HTTP eşlemesi)
CLICKHOUSE_ROLE: Kimlik doğrulaması 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ştir (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 (8123 portunda yerel Docker Compose için tipik)
- ClickHouse Cloud ve herhangi bir HTTPS veritabanı uç noktası için "true" olarak bırakın—MCP sunucusunun kendisi HTTP, stdio veya TLS'yi ayrı olarak sonlandıran bir giriş üzerinden sunulsa bile
- Bu bayrağın veritabanı portuyla eşleşmemesi (örn. CLICKHOUSE_SECURE=false portuna karşı 8443) 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ştir/devre dışı bırak
- Varsayılan: "true"
- Sertifika doğrulamasını devre dışı bırakmak için "false" olarak ayarlayın (üretim için önerilmez)
- TLS sertifikaları: Paket, TLS sertifika doğrulaması için truststore aracılığıyla işletim sistemi güven deposunu kullanır. Uygun sertifika işlemeyi sağlamak için başlangıçta truststore.inject_into_ssl() çağrısı yaparı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ılacaktır.
CLICKHOUSE_PROXY_PATH: ClickHouse HTTP uç noktası için URL yol öneki
- Varsayılan: Yok
- ClickHouse HTTP arayüzü bir yol öneki altında ters proxy arkası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şarsanı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 olarak bağlanmak için bunu ayarlayın
CLICKHOUSE_ENABLED: ClickHouse veritabanı araçlarını etkinleştir/devre dışı bırak
- 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"
- DDL (CREATE, ALTER, DROP) ve DML (INSERT, UPDATE, DELETE) işlemlerine izin vermek için "true" olarak ayarlayın
- 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 (DROP TABLE, DROP DATABASE, DROP VIEW, DROP DICTIONARY, TRUNCATE TABLE)
- Varsayılan: "false"
- Yalnızca CLICKHOUSE_ALLOW_WRITE_ACCESS=true de ayarlandığında etkili olur
- Yıkıcı DROP ve TRUNCATE işlemlerine açıkça izin vermek için "true" olarak ayarlayın
- Bu, AI keşfi sırasında yanlışlıkla veri silinmesini önlemek için bir güvenlik özelliğidir

MCP sunucusu ve aktarım

Bu değişkenler, aktarım, 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 Aktarımları için Kimlik Doğrulama.

CLICKHOUSE_MCP_SERVER_TRANSPORT: MCP sunucusu için aktarım 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ğlanma ana bilgisayarı/portu)
CLICKHOUSE_MCP_BIND_HOST: HTTP veya SSE aktarımı kullanı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 aktarım "http" veya "sse" olduğunda kullanılır — CLICKHOUSE_HOST ile ilgili değildir
CLICKHOUSE_MCP_BIND_PORT: HTTP veya SSE aktarımı kullanırken MCP sunucusunun bağlanacağı port
- Varsayılan: "8000"
- Yalnızca aktarım "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ürseniz bunu artırın
CLICKHOUSE_MCP_AUTH_TOKEN: HTTP/SSE aktarımları için statik taşıyıcı belirteç
- Varsayılan: Yok
- HTTP/SSE aktarımları için CLICKHOUSE_MCP_AUTH_TOKEN, FASTMCP_SERVER_AUTH veya CLICKHOUSE_MCP_AUTH_DISABLED=true'den biri gereklidir
- 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 devret
- Varsayılan: Yok
- Değer, bir AuthProvider alt sınıfının tam sınıf yoludur, örn. fastmcp.server.auth.providers.azure.AzureProvider veya fastmcp.server.auth.providers.google.GoogleProvider
- Ayarlandığında, FastMCP sağlayıcıyı kendi FASTMCP_SERVER_AUTH_* ortam değişkenlerinden otomatik olarak yükler; bu modda CLICKHOUSE_MCP_AUTH_TOKEN'i ayarsız bırakın
CLICKHOUSE_MCP_AUTH_DISABLED: HTTP/SSE aktarımları için kimlik doğrulamayı devre dışı bırak
- 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 Yazılım Değişkenleri

MCP_MIDDLEWARE_MODULE: MCP sunucusuna enjekte edilecek özel ara yazılımı içeren Python modül adı
- Varsayılan: Yok (ara yazılım yüklenmez)
- Ara yazılım modülünüzün modül adına (.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 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ı ekstraların yüklenmesini gerektirir: mcp-clickhouse[chdb]
CHDB_DATA_PATH: chDB veri dizininin yolu
- Varsayılan: ":memory:" (bellek içi veritabanı)
- Bellek içi veritabanı için :memory: kullanın
- Kalıcı depolama için bir dosya yolu kullanın (örn., /path/to/chdb/data)

Yaygın yapılandırma tuzakları

CLICKHOUSE_SECURE ve MCP / giriş TLS'si — MCP sunucusu Kubernetes girişi, bir 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. Giriş TLS'sini veritabanı istemci ayarlarından ayrı olarak yapılandırın.
Yerel protokol portları — CLICKHOUSE_PORT, ClickHouse'un HTTP arayüzünü hedeflemelidir (varsayılan olarak 8123/8443). 9000/9440 portları yerel TCP protokolü (clickhouse-client) içindir 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

HTTP aktarımı ile MCP Inspector veya 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 aktarımı ile 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 aktarımı kullanırken, sunucu yapılandırılan portta (varsayılan 8000) çalışacaktı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ğlanma ana bilgisayarı ve port ayarları yalnızca aktarım "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