Hydrolix MCP Server

resmi

Hydrolix zaman serisi veri gölü entegrasyonu, LLM tabanlı iş akışlarına şema keşfi ve sorgulama yetenekleri sağlar.

GitHub
10

Dokümantasyon

Hydrolix MCP Sunucusu

PyPI - Version Install in VS Code Install in VS Code Insiders

Hydrolix için bir MCP sunucusu.

Hızlı Başlangıç

Birkaç dakika içinde çalışmaya başlayın. Bu bölüm Claude Desktop ve Claude Code'u kapsar.

Adım 1 — Ön Koşullar

Başlamadan önce aşağıdakilere sahip olduğunuzdan emin olun:

  • Hydrolix kimlik bilgileri — küme ana makine adınız ve bir kullanıcı adı/parola veya bir hizmet hesabı belirteci. Bunlara sahip değilseniz Hydrolix yöneticinize danışın.
  • Claude Desktop — claude.ai/download adresinden indirin.

Adım 2 — MCP sunucusunu kurun

Kurulumunuza uygun yöntemi seçin:

Seçenek A: uv kullanma (önerilir)

uv Python'u otomatik olarak yönetir ve mcp-hydrolix'i isteğe bağlı olarak indirir, bu nedenle ayrı bir kurulum adımı gerekmez. uv'ye sahip değilseniz kurun:

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Seçenek B: pip kullanma

Python 3.13+ gerektirir. Python'u kurmanız gerekiyorsa python.org adresinden indirin.

pip install mcp-hydrolix

Adım 3 — Claude Desktop'ı yapılandırın

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

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. "mcpServers" nesnesine aşağıdaki girişi ekleyin (dosya henüz yoksa bu içerikle oluşturun):

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<your-hydrolix-hostname>",
        "HYDROLIX_USER": "<your-username>",
        "HYDROLIX_PASSWORD": "<your-password>"
      }
    }
  }
}

<your-hydrolix-hostname>, <your-username> ve <your-password> değerlerini gerçek kimlik bilgilerinizle değiştirin.

[!NOTE] Seçenek B'yi (pip) kullandıysanız, "args" alanı olmadan "command": "mcp-hydrolix" kullanın.

[!TIP] Dosyada zaten başka girişler varsa, tüm dosyayı değiştirmek yerine "mcp-hydrolix" bloğunu mevcut "mcpServers" nesnesinin içine ekleyin.

[!NOTE] Kullanıcı adı/parola yerine bir hizmet hesabı belirteci ile kimlik doğrulaması yapıyorsanız, Kimlik Doğrulama bölümüne bakın.

Komut bulunamadı?

Claude Desktop, kabuğunuzun PATH'i olmadan başlatılır, bu nedenle ikili dosya yüklü olsa bile bulamayabilir. Tam yolu bulun ve yapılandırmada "command" değeri olarak kullanın.

Seçenek A (uv): uvx yolunu bulun:

  • macOS / Linux: which uvx
  • Windows: where.exe uvx

Seçenek B (pip): mcp-hydrolix yolunu bulun:

  • macOS / Linux: which mcp-hydrolix
  • Windows: where.exe mcp-hydrolix

which/where.exe hiçbir şey döndürmezse, ikili dosya PATH'inizde değildir. En temiz çözüm, Python ortamını ve PATH'i sizin için yöneten Seçenek A'ya (uv) geçmektir.

Adım 4 — Claude Desktop'ı yeniden başlatın

Yapılandırmayı uygulamak için uygulamayı yeniden başlatın.

macOS / Windows kullanıcıları: Yeniden başlatmadan önce Claude'dan tamamen çıktığınızdan emin olun. macOS'ta Cmd+Q tuşlarına basın veya Dock simgesine sağ tıklayıp Çık'ı seçin. Windows'ta sistem tepsisi simgesini kullanın.

Adım 5 — Çalıştığını doğrulayın

  1. Claude Desktop'ta yeni bir konuşma açın. Metin girişinin yanında bir araçlar/çekiç simgesi arayın — bu, MCP sunucusunun başarıyla bağlandığını onaylar.

  2. Her şeyin çalıştığını doğrulamak için şu istemi deneyin:

    Hydrolix MCP araçlarınızı kullanarak mevcut veritabanlarını listeleyin.

Claude, list_databases aracını çağırmalı ve kümenizden bir veritabanı listesi döndürmelidir.

Bunun yerine Claude Code mu kullanıyorsunuz?

Komut satırını tercih ediyorsanız, uv'nin kurulu olduğundan emin olun (Adım 2'deki Seçenek A), ardından şunu çalıştırın:

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_URL=https://<your-hydrolix-hostname> \
  --env HYDROLIX_USER=<your-username> \
  --env HYDROLIX_PASSWORD=<your-password> \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

Ardından Claude Code'u açın ve aynı istemle test edin:

Hydrolix MCP araçlarınızı kullanarak mevcut veritabanlarını listeleyin.

Bunun yerine VS Code mu kullanıyorsunuz?

Tek tıklamayla kurulum için bu README'nin üst kısmındaki VS Code'da Kur rozetine tıklayın. Kullanıcı arayüzü akışını tercih ediyorsanız, Komut Paletini (Cmd+Shift+P / Ctrl+Shift+P) açın, MCP: Sunucu Ekle'yi çalıştırın, Komut (stdio) seçeneğini belirleyin ve Adım 3'teki uvx ... komutunu ve env bloğunu yeniden kullanın.

Araçlar

  • run_select_query

    • Hydrolix kümenizde SQL sorguları yürütün.
    • Girdi: sql (dize): Yürütülecek SQL sorgusu.

  • list_databases

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

  • list_tables

    • Bir veritabanındaki tüm tabloları listeleyin.
    • Girdi: database (dize): Veritabanının adı.

  • get_table_info

    • Şema gibi tablo meta verilerini alın
    • Girdi: database (dize): Veritabanının adı.
    • Girdi: table (dize): Tablonun adı.

Etkili Kullanım

LLM mimarilerindeki geniş çeşitlilik nedeniyle, tüm modeller yukarıdaki araçları proaktif olarak kullanmayacak ve çok azı, modele sağlanan dikkatle oluşturulmuş araç açıklamalarına rağmen, rehberlik olmadan bunları etkili bir şekilde kullanacaktır. Hydrolix MCP sunucusunu kullanırken modelinizden en iyi sonuçları almak için aşağıdakileri öneririz:

  • İstemlerinizde Hydrolix veritabanınıza adıyla başvurun ve araç kullanımını talep edin (örn., "Hydrolix veritabanıma erişmek için MCP araçlarını kullanarak, lütfen ...")
    • Bu, modeli mevcut MCP araçlarını kullanmaya teşvik eder ve halüsinasyonları en aza indirir.
  • İstemlerinize zaman aralıklarını dahil edin (örn., "5 Aralık 2023 ile 18 Ocak 2024 arasında, ...") ve özellikle çıktının zaman damgasına göre sıralanmasını isteyin.

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 Hydrolix'e bağlanabiliyorsa, Hydrolix sorgu başlığının Clickhouse sürümüyle birlikte 200 OK döndürür
  • Sunucu Hydrolix sorgu başlığına bağlanamazsa 503 Service Unavailable döndürür

Örnek:

curl http://localhost:8000/health
# Response: OK - Connected to Hydrolix compatible with ClickHouse 24.3.1

Yapılandırma

Hydrolix MCP sunucusu, standart bir MCP sunucu girişi kullanılarak yapılandırılır. MCP sunucularını nerede bulacağınız veya bildireceğinizle ilgili özel talimatlar için istemcinizin belgelerine bakın. Claude Desktop kullanan örnek bir kurulum aşağıda belgelenmiştir.

Hydrolix MCP sunucusunu başlatmanın önerilen yolu, diğer tüm bağımlılıkları yalıtılmış bir ortamda kurmayı yönetecek olan uv proje yöneticisi aracılığıyladır.

Kimlik Doğrulama

Sunucu, aşağıdaki öncelik sırasına göre (en yüksekten en düşüğe) birden çok kimlik doğrulama yöntemini destekler:

  1. İstek başına Taşıyıcı belirteci: Authorization: Bearer <token> başlığı aracılığıyla sağlanan hizmet hesabı belirteci
  2. İstek başına GET parametresi: ?token=<token> sorgu parametresi aracılığıyla sağlanan hizmet hesabı belirteci
  3. Ortam tabanlı kimlik bilgileri: Ortam değişkenleri aracılığıyla yapılandırılan kimlik bilgileri
    • Hizmet hesabı belirteci (HYDROLIX_TOKEN) veya
    • Kullanıcı adı ve parola (HYDROLIX_USER ve HYDROLIX_PASSWORD)

Birden çok kimlik doğrulama yöntemi yapılandırıldığında, sunucu yukarıdaki öncelik sırasına göre ilk kullanılabilir yöntemi kullanacaktır. İstek başına kimlik doğrulama yalnızca HTTP veya SSE aktarım modları kullanılırken kullanılabilir.

Not: Salt okunur role sahip bir hizmet hesabı belirteci kullanılması önerilir.

Kullanıcı adı ve parola kullanan MCP Sunucu tanımı (JSON):

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_USER": "<hydrolix-user>",
    "HYDROLIX_PASSWORD": "<hydrolix-password>"
  }
}

Hizmet hesabı belirteci kullanan MCP Sunucu tanımı (JSON):

{
  "command": "uvx",
  "args": [
    "--python",
    "3.13",
    "--refresh-package",
    "mcp-hydrolix",
    "mcp-hydrolix"
  ],
  "env": {
    "HYDROLIX_URL": "https://<hydrolix-host>",
    "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
  }
}

Kullanıcı adı ve parola kullanan MCP Sunucu tanımı (YAML):

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_URL: https://<hydrolix-host>
  HYDROLIX_USER: <hydrolix-user>
  HYDROLIX_PASSWORD: <hydrolix-password>

Hizmet hesabı belirteci kullanan MCP Sunucu tanımı (YAML):

command: uvx
args:
- --python
- "3.13"
- --refresh-package
- mcp-hydrolix
- mcp-hydrolix
env:
  HYDROLIX_URL: https://<hydrolix-host>
  HYDROLIX_TOKEN: <hydrolix-service-account-token>

Yapılandırma Örneği (Claude Desktop)

  1. Aşağıdaki 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. Kullanıcı adı ve parola kullanmak için mcpServers yapılandırma bloğuna bir mcp-hydrolix sunucu girişi ekleyin:

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<hydrolix-host>",
        "HYDROLIX_USER": "<hydrolix-user>",
        "HYDROLIX_PASSWORD": "<hydrolix-password>"
      }
    }
  }
}

Hizmet hesabından yararlanmak için aşağıdaki yapılandırma bloğunu kullanın:

{
  "mcpServers": {
    "mcp-hydrolix": {
      "command": "uvx",
      "args": [
        "--python",
        "3.13",
        "--refresh-package",
        "mcp-hydrolix",
        "mcp-hydrolix"
      ],
      "env": {
        "HYDROLIX_URL": "https://<hydrolix-host>",
        "HYDROLIX_TOKEN": "<hydrolix-service-account-token>"
      }
    }
  }
}

  1. Ortam değişkeni tanımlarını Hydrolix kümenize işaret edecek şekilde güncelleyin.

  2. (Önerilir) uvx için komut girişini bulun ve uvx yürütülebilir dosyasının mutlak yolu ile değiştirin. Bu, sunucu başlatılırken uvx'in doğru sürümünün kullanılmasını sağlar. Bu yolu which uvx veya where.exe uvx kullanarak bulabilirsiniz.

  3. Değişiklikleri uygulamak için Claude Desktop'ı yeniden başlatın. Windows kullanıyorsanız, sistem tepsisi simgesini kullanarak istemciyi kapatarak Claude'un tamamen durdurulduğundan emin olun.

Yapılandırma Örneği (Claude Code)

Hydrolix MCP sunucusunu Claude Code için yapılandırmak üzere aşağıdaki komutu çalıştırın:

claude mcp add --transport stdio hydrolix \
  --env HYDROLIX_USER=<hydrolix-user> \
  --env HYDROLIX_PASSWORD=<hydrolix-password> \
  --env HYDROLIX_URL=https://<hydrolix-host> \
  --env HYDROLIX_MCP_SERVER_TRANSPORT=stdio \
  -- uvx --python 3.13 --refresh-package mcp-hydrolix mcp-hydrolix

Ortam Değişkenleri

Aşağıdaki değişkenler Hydrolix bağlantısını yapılandırmak için kullanılır. Bu değişkenler MCP yapılandırma bloğu (yukarıda gösterildiği gibi), bir .env dosyası veya geleneksel ortam değişkenleri aracılığıyla sağlanabilir.

Gerekli Değişkenler

Kümeyi tanımlamak için aşağıdakilerden BİRİNİ ayarlamanız ZORUNLUDUR:

  • HYDROLIX_URL (önerilir): Hydrolix kümenizin standart genel URL'si, örn. https://mycluster.hydrolix.live. Tipik küme dışı dağıtımlar için bu tek değişken yeterlidir — hem HTTP sorgu uç noktası hem de REST /version yoklaması için ana bilgisayar, bağlantı noktası (şema varsayılanı 443/80) ve TLS ayarlarını sağlar.
  • HYDROLIX_HOST (kullanımdan kaldırıldı): Hydrolix sunucunuzun ana makine adı. Geriye dönük uyumluluk için hala kabul edilir ancak HYDROLIX_URL ile değiştirilmelidir.

HYDROLIX_MCP_SERVER_TRANSPORT, http veya sse olduğunda, HYDROLIX_URL özellikle gereklidir (OAuth meta veri uç noktası bunu duyurur). Bu aktarımlar için HYDROLIX_HOST tek başına yeterli değildir.

Uç nokta geçersiz kılmaları

Bunlar, HYDROLIX_URL'den türetilen değerleri geçersiz kılar. HTTP sorgu uç noktası ve sürüm API'sinin farklı dahili ana makine adlarında veya bağlantı noktalarında bulunduğu küme içi dağıtımlar için kullanışlıdır. Geçersiz kılma önceliği: açık yeni değişken > kullanımdan kaldırılmış takma ad > HYDROLIX_URL türevli > sabit varsayılan.

  • HYDROLIX_HTTP_QUERY_HOST / HYDROLIX_HTTP_QUERY_PORT / HYDROLIX_HTTP_QUERY_SECURE: ClickHouse HTTP sorgu uç noktasını geçersiz kılar.
  • HYDROLIX_VERSION_API_HOST / HYDROLIX_VERSION_API_PORT / HYDROLIX_VERSION_API_SECURE: REST /version yoklama uç noktasını geçersiz kılar. HYDROLIX_VERSION_API_SECURE, varsayılan olarak çözümlenen HTTP sorgusu güvenli değerinden miras alır.

Kullanımdan kaldırılmış değişkenler

Aşağıdakiler geçiş penceresi sırasında hala kabul edilir ancak gelecekteki bir sürümde kaldırılacaktır. Uygun olduğunda geçiş yapın:

Kullanımdan kaldırıldıDeğiştirme
HYDROLIX_HOSTHYDROLIX_URL (tercih edilir) veya HYDROLIX_HTTP_QUERY_HOST
HYDROLIX_PORTHYDROLIX_HTTP_QUERY_PORT
HYDROLIX_SECUREHYDROLIX_HTTP_QUERY_SECURE
HYDROLIX_API_HOSTHYDROLIX_VERSION_API_HOST
HYDROLIX_API_PORTHYDROLIX_VERSION_API_PORT

Bunlardan herhangi birini kullanan harici operatörler, HYDROLIX_URL'ye geçişi öneren bir kerelik başlangıç uyarısı görecektir. Küme içi (o6r tarafından yönetilen) dağıtımlar bu uyarıyı görmez; geçişleri platform tarafından yönetilir.

Kimlik Doğrulama Değişkenleri

Stdio aktarımı kullanılırken en az bir kimlik doğrulama yöntemi yapılandırılmalıdır:

  • HYDROLIX_TOKEN: Ortam tabanlı kimlik doğrulama için hizmet hesabı belirteci
  • HYDROLIX_USER ve HYDROLIX_PASSWORD: Ortam tabanlı kimlik doğrulama için kullanıcı adı ve parola (her ikisi birlikte sağlanmalıdır)

Özetle:

  • Stdio için, HYDROLIX_TOKEN veya HYDROLIX_USER+HYDROLIX_PASS (ortam kimlik bilgileri) kullanmanız ZORUNLUDUR
  • Http/sse için, HYDROLIX_TOKEN veya HYDROLIX_USER+HYDROLIX_PASS (ortam kimlik bilgileri) kullanabilirsiniz, ancak bunun yerine istek başına kimlik bilgileri kullanabilirsiniz.

Ortam veya istek yoluyla hiçbir kimlik bilgisi sağlanmazsa, istek başarısız olur.

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

  • HYDROLIX_VERIFY: 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 ortamı için önerilmez)
  • HYDROLIX_DATABASE: Kullanılacak varsayılan veritabanı
    • Varsayılan: Yok (sunucu varsayılanını kullanır)
    • Belirli bir veritabanına otomatik olarak bağlanmak için bunu ayarlayın
  • HYDROLIX_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.
  • HYDROLIX_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
  • HYDROLIX_MCP_BIND_PORT: HTTP veya SSE aktarımı kullanırken MCP sunucusunun bağlanacağı bağlantı noktası
    • Varsayılan: "8000"
    • Yalnızca aktarım "http" veya "sse" olduğunda kullanılır
  • HYDROLIX_MAX_RAW_TIMERANGE: Özet olmayan tablolara yönelik sorgular için izin verilen saniye cinsinden maksimum zaman aralığı
    • Varsayılan: 21600 (6 saat)
    • Özet tabloları hedefleyen sorgular bu sınırdan etkilenmez
  • HYDROLIX_QUERY_POOL: Sorguların yönlendirileceği Hydrolix sorgu havuzunun adı (hdx_query_pool_name ayarlar)
    • Varsayılan: Yok (kümenin varsayılan sorgu havuzunu kullanır)
    • Ayarlandığında, sunucunun yaptığı her sorgu adlandırılmış havuza yönlendirilir; havuz kümede zaten mevcut olmalıdır
    • Platform tarafından yönetilen (küme içi) dağıtımlarda küme ayarı bu aynı değişkene eşlenir; dağıtım ortamın sahibidir, bu nedenle değeri yetkilidir
    • Not: bu, istemci tarafı sorgu iş parçacığı havuzunu boyutlandıran HYDROLIX_QUERIES_POOL_SIZE ile ilgisizdir

HTTP aktarımı ile MCP Inspector veya uzaktan erişim için:

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_USER=default
HYDROLIX_PASSWORD=myPassword
HYDROLIX_MCP_SERVER_TRANSPORT=http
HYDROLIX_MCP_BIND_HOST=0.0.0.0  # Bind to all interfaces
HYDROLIX_MCP_BIND_PORT=4200  # Custom port (default: 8000)

HTTP aktarımı kullanırken, sunucu yapılandırılan bağlantı noktasında (varsayılan 8000) çalışacaktır. Örneğin, yukarıdaki yapılandırma ile:

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

HTTP Aktarımı ile İstek Başına Kimlik Doğrulama Kullanımı

HTTP veya SSE aktarımı kullanırken, ortam tabanlı kimlik bilgilerini atlayabilir ve bunun yerine istek başına kimlik doğrulama sağlayabilirsiniz. Bu, çok kullanıcılı senaryolar veya MCP sunucularını yerel olarak çalıştırmayı desteklemeyen istemciler için kullanışlıdır.

İstek başına kimlik doğrulama ile uzak bir HTTP sunucusuna bağlanan örnek mcpServers yapılandırması:

{
  "mcpServers": {
    "mcp-hydrolix-remote": {
      "url": "https://my-hydrolix-mcp.example.com/mcp?token=<service-account-token>"
    }
  }
}

Ortam kimlik bilgileri olmadan kendi HTTP sunucunuzu çalıştırmak için örnek minimal .env yapılandırması:

HYDROLIX_URL=https://my-cluster.hydrolix.net
HYDROLIX_MCP_SERVER_TRANSPORT=http

MCP spesifikasyonunun bir parçası olmasa da, birçok MCP istemcisi MCP tarafından yapılan isteklere başlık eklenmesine izin verir. Bu mümkün olduğunda, daha fazla güvenlik için MCP istemcisini, bir hizmet hesabı belirtecini sorgu parametresi yerine Authorization: Bearer <sa-token-here> başlığı aracılığıyla iletecek şekilde yapılandırmanızı öneririz.

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

Uçtan Uca Testler

tests/e2e/ altındaki ayrı bir paket, yerel çalışma ağacını canlı bir Hydrolix Kubernetes kümesine dağıtır ve çalışan pod'a karşı MCP araçlarını duman testinden geçirir. Varsayılan test çalıştırmalarından ve ön gönderim kancasından hariç tutulur; çalıştırmak için end_to_end pytest işaretleyicisi ve kimlik bilgileri aracılığıyla açıkça katılım gerektirir. Kılavuz için tests/e2e/README.md sayfasına bakın.