Couchbase

Couchbase MCP Sunucusu

Couchbase MCP Sunucusu, kendi kendine barındırılan bir Model Context Protocol (MCP) sunucusudur; AI ajanlarını ve LLM destekli asistanları — Claude, Cursor, Windsurf, VS Code Copilot ve diğer MCP istemcilerini — Capella üzerinde veya kendi kendine yönetilen Couchbase kümelerindeki verilere bağlar. MCP, AI asistanlarının araçları çağırmasına ve harici veri kaynaklarını sorgulamasına izin veren açık bir standarttır; bu sunucu, bu standardı Couchbase için uygular; böylece bir AI ajanı kümenizi inceleyebilir, SQL++ sorguları çalıştırabilir, belgeleri okuyup yazabilir ve el yazısı kod yerine doğal dil kullanarak sorgu performansını analiz edebilir.

Küme Sağlığı, Veri Şeması, Anahtar-Değer, Sorgu ve Performans dahil olmak üzere kategorilerde araçlar sağlar — salt okunur mod (varsayılan olarak açık) ve ayrıntılı araç devre dışı bırakma yoluyla güvenlik kontrolleri sunar; böylece bir AI ajanının istenmeyen yazma işlemleri riski olmadan verilerinizi keşfetmesine ve sorgulamasına izin verebilirsiniz. Hem STDIO hem de Streamable HTTP taşıma protokollerini destekler.

Couchbase MCP sunucusu, Python Package Index (PyPI) paketi olarak ve Docker aracılığıyla dağıtılır. Couchbase MCP Sunucusu için kurumsal destek, Couchbase AI Data Plane lisansı alınarak sağlanır; bu lisans aynı zamanda Couchbase Agent Memory ve Couchbase Agent Catalog kullanımını ve kurumsal desteğini de içerir.

Tam dokümantasyon için mcp-server.couchbase.com adresini ziyaret edin.

Tam dokümantasyon için docs.couchbase.com/mcp-server adresini ziyaret edin.

İçindekiler

• Neden Couchbase MCP Sunucusu
• Örnek Komutlar
• Özellikler/Araçlar
• Ön Koşullar
• Yapılandırma
• Operasyonel İçgörüler Sunucusu
• Streamable HTTP Taşıma Modu
• SSE Taşıma Modu
• OAuth 2.1 Yetkilendirme
• Docker Görüntüsü
• Kullanım Verisi Toplama
• Sorun Giderme İpuçları
• Entegrasyon Testi
• SSS
• Katkıda Bulunma
• Destek Politikası

Neden Couchbase MCP Sunucusu

• Varsayılan olarak güvenli — yazma işlemleri (belge upsert/insert/delete ve veri değiştiren SQL++ sorguları), CB_MCP_READ_ONLY_MODE=false değerini açıkça ayarlamadığınız sürece engellenir ve bireysel araçlar devre dışı bırakılabilir veya kullanıcı onayının arkasına alınabilir.
• Capella ve kendi kendine yönetilen kümelerle çalışır — aynı yapılandırma, Couchbase Capella'ya (tamamen yönetilen) veya kendi kendine barındırılan bir Couchbase Server kümesine bağlanır.
• RBAC farkındalığı — araç devre dışı bırakma, LLM davranışını yönlendirmek için bir kolaylık katmanıdır; altta yatan Couchbase kullanıcısının rol tabanlı erişim kontrolü, yetkili güvenlik sınırı olmaya devam eder.
• Üretim taşıma protokolleri — yerel masaüstü istemciler için STDIO üzerinden veya paylaşılan/uzak dağıtımlar için isteğe bağlı OAuth 2.1 (JWT/JWKS, sağlayıcıdan bağımsız — Auth0, Okta, Keycloak, Entra, Cognito vb.) ile Streamable HTTP üzerinden çalışır.
• Herhangi bir MCP istemcisi — Claude Desktop, Cursor, Windsurf, VS Code ve JetBrains AI Assistant/Junie ile test edilmiştir; MCP spesifikasyonunu uygulayan herhangi bir istemciyle çalışır.

Örnek Komutlar

Sunucu bağlandıktan sonra, AI asistanınız aracılığıyla Couchbase kümenizle doğal dilde konuşabilirsiniz. Örneğin:

• "Bu kümede hangi bucket, scope ve collection'larım var ve orders collection'ının şeması nedir?"
• "SQL++ sorgusu çalıştırarak users collection'ındaki en son 10 belgeyi bul where status = 'active'."
• "Bu kümede son bir saatteki en yavaş 5 sorgu hangileri ve bunlardan herhangi biri kapsayan bir indeksten yoksun mu?"
• "Bu kümenin sağlıklı olup olmadığını kontrol et ve hangi servislerin çalıştığını söyle."
• "products collection'ına şu alanlarla yeni bir belge ekle: ..." (CB_MCP_READ_ONLY_MODE=false gerektirir)

Özellikler/Araçlar

Bu dağıtım iki sunucu içerir: operasyonel sunucu (varsayılan — hemen aşağıdaki tablolar) normal bir Couchbase kümesiyle couchbase SDK üzerinden konuşur ve Operational Insights sunucusu (kendi tablosu daha aşağıda) Operational Insights kümeleriyle couchbase-operational-insights SDK üzerinden konuşur.

Küme kurulumu ve sağlık araçları

Veri modeli ve şema keşif araçları

Belge KV işlem araçları

Sorgu ve indeksleme araçları

Tam metin arama (FTS) araçları

Couchbase Server 7.6+ ve Search servisi gerektirir. Vektör arama bu araçlar tarafından desteklenmez (ayrı vektör arama araçlarına bakın).

Sorgu performansı analiz araçları

Operasyonel İçgörüler araçları

Ayrı operational-insights sunucusu tarafından kaydedilir (aşağıdaki Operational Insights Sunucusu bölümüne bakın), varsayılan operational sunucusu tarafından değil.

Sunucu Zaman Uyumsuz İstek API araçları, uzun süren sorgular için başlat → yokla → at veya iptal et akışını oluşturur: run_query_async bir query_handle döndürür, get_async_query_results hazır olduğunu bildirene kadar yoklanır (ve satırları döndürür), ardından discard_async_query_results sonuçları serbest bırakır veya hâlâ çalışan bir sorgu için cancel_async_query onu durdurur.

Not: get_collections_in_scope, get_schema_for_collection, create_index ve list_indexes her iki sunucuda da farklı davranışlarla mevcuttur. (get_server_configuration_status da her ikisinde de görünür, ancak kasıtlı olarak tek paylaşılan araçtır — aynı uygulama, aynı sonuç şekli — bu nedenle ayrıştırma gerektirmez.) Her sunucu ayrı bir süreçtir, bu nedenle bu yalnızca tek bir MCP istemcisi hem operational hem de operational-insights aynı anda kaydederse bir sorundur — bu durumda, istemci yapılandırma katmanında ayrıştırın (ör. iki sunucu girişine istemcinin kendi yapılandırmasında farklı adlar vererek).

Ön Koşullar

• Python 3.10 veya üzeri.
• Çalışan bir Couchbase kümesi. Başlamanın en kolay yolu, Couchbase sunucusunun tamamen yönetilen sürümü olan Capella ücretsiz katmanını kullanmaktır. Örnek veri kümelerinden birini içe aktarmak veya kendi verinizi içe aktarmak için talimatları izleyebilirsiniz.
• Sunucuyu çalıştırmak için uv kurulu olmalıdır.
• Sunucuyu Claude'a bağlamak için Claude Desktop gibi bir MCP istemcisi kurulu olmalıdır. Talimatlar Claude Desktop ve Cursor için sağlanmıştır. Diğer MCP istemcileri de kullanılabilir.

Yapılandırma

MCP sunucusu, önceden derlenmiş PyPI paketinden veya uv kullanarak kaynaktan çalıştırılabilir.

PyPI'dan Çalıştırma

MCP sunucusu için önceden derlenmiş bir PyPI paketi yayınlıyoruz.

MCP İstemcileri için Önceden Derlenmiş Paket Kullanarak Sunucu Yapılandırması

Temel Kimlik Doğrulama

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

veya

mTLS

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
      }
    }
  }
}

Not: İstemcide başka MCP sunucuları kullanıyorsanız, bunu mevcut mcpServers nesnesine ekleyebilirsiniz.

Kaynaktan Çalıştırma

MCP sunucusu, bu depoyu kullanarak kaynaktan çalıştırılabilir.

Depoyu yerel makinenize klonlayın

git clone https://github.com/couchbase/mcp-server-couchbase.git

MCP İstemcileri için Kaynak Kullanarak Sunucu Yapılandırması

Bu, Claude Desktop, Cursor, Windsurf Editor gibi MCP istemcileri için ortak yapılandırmadır.

{
  "mcpServers": {
    "couchbase": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/mcp-server-couchbase/",
        "run",
        "src/mcp_server.py"
      ],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password"
      }
    }
  }
}

Not: path/to/cloned/repo/mcp-server-couchbase/, yerel makinenizdeki klonlanmış deponun yolu olmalıdır. Sondaki eğik çizgiyi unutmayın!

Not: İstemcide başka MCP sunucuları kullanıyorsanız, bunu mevcut mcpServers nesnesine ekleyebilirsiniz.

MCP Sunucusu için Ek Yapılandırma

Sunucu, ortam değişkenleri veya komut satırı bağımsız değişkenleri kullanılarak yapılandırılabilir:

Salt Okunur Mod Yapılandırması

CB_MCP_READ_ONLY_MODE yazma işlemlerini kontrol eden tek anahtardır:

• true olduğunda (varsayılan): Tüm yazma işlemleri (KV, Sorgu, kapsam/koleksiyon yönetimi ve dizin yönetimi) devre dışıdır. Tüm yazma araçları (KV: upsert, insert, replace, delete, alt belge değiştirme; kapsam/koleksiyon yönetimi: create_scope, create_collection, delete_scope, delete_collection; dizin yönetimi: create_index, build_index, drop_index) yüklenmez ve LLM için kullanılabilir olmayacaktır ve verileri veya yapıyı değiştiren SQL++ sorguları engellenir.
• false olduğunda: Tüm yazma araçları yüklenir ve SQL++ veri/yapı değiştirme sorgularına izin verilir.

Bu, LLM'ler tarafından yanlışlıkla veri değişikliklerini önlemek için önerilen güvenli varsayılandır.

Not: Kimlik doğrulama için Kullanıcı Adı ve Parola veya İstemci Sertifikası ve anahtar yollarından birine ihtiyacınız vardır. İsteğe bağlı olarak, sunucu sertifikalarını doğrulamak için kullanılacak CA kök sertifika yolunu belirtebilirsiniz. Hem İstemci Sertifikası ve anahtar yolu hem de kullanıcı adı ve parola belirtilirse, kimlik doğrulama için istemci sertifikaları kullanılacaktır.

Araçları Devre Dışı Bırakma

Belirli araçları devre dışı bırakarak bunların yüklenmesini ve MCP istemcisine sunulmasını engelleyebilirsiniz. Devre dışı bırakılan araçlar araç keşfinde görünmez ve LLM tarafından çağrılamaz.

Desteklenen Biçimler

Virgülle ayrılmış liste:

# Environment variable
CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"

# Command line
uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id

Dosya yolu (her satırda bir araç adı):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

# Command line
uvx couchbase-mcp-server --disabled-tools disabled_tools.txt

Dosya biçimi (örn. disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

# ile başlayan satırlar yorum olarak kabul edilir ve yok sayılır.

MCP İstemci Yapılandırma Örnekleri

Virgülle ayrılmış liste kullanma:

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"
      }
    }
  }
}

Dosya yolu kullanma (çok sayıda araç için önerilir):

{
  "mcpServers": {
    "couchbase": {
      "command": "uvx",
      "args": ["couchbase-mcp-server"],
      "env": {
        "CB_CONNECTION_STRING": "couchbases://connection-string",
        "CB_USERNAME": "username",
        "CB_PASSWORD": "password",
        "CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"
      }
    }
  }
}

Önemli Güvenlik Notu

Uyarı: Araçları devre dışı bırakmak tek başına belirli işlemlerin gerçekleştirilemeyeceğini garanti etmez. Temel veritabanı kullanıcısının RBAC (Rol Tabanlı Erişim Kontrolü) izinleri yetkili güvenlik kontrolüdür.

Örneğin, upsert_document_by_id ve delete_document_by_id araçlarını devre dışı bıraksanız bile, aşağıdaki durumlar söz konusu olmadıkça veri değişiklikleri yine de run_sql_plus_plus_query aracı üzerinden SQL++ DML ifadeleri (INSERT, UPDATE, DELETE, MERGE) kullanılarak gerçekleştirilebilir:

• CB_MCP_READ_ONLY_MODE değeri true olarak ayarlanmışsa (varsayılan), VEYA
• Veritabanı kullanıcısı veri değişikliği için gerekli RBAC izinlerine sahip değilse

En İyi Uygulama: Birincil güvenlik önlemi olarak Couchbase kullanıcı kimlik bilgilerinizde her zaman uygun RBAC izinlerini yapılandırın. Araç devre dışı bırakmayı LLM davranışını yönlendirmek ve saldırı yüzeyini azaltmak için ek bir katman olarak kullanın, tek güvenlik kontrolü olarak değil.

Araç Çağrıları için Bilgi İsteme/Onay

Belirli araçlar için yürütmeden önce açık kullanıcı onayı isteyebilirsiniz (MCP istemcisi bilgi istemeyi desteklediğinde).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools şu biçimleri destekler:

• Virgülle ayrılmış liste
• Dosya yolu (her satırda bir araç adı, # yorumları desteklenir)

Örnek:

# Environment variable
CB_MCP_CONFIRMATION_REQUIRED_TOOLS="delete_document_by_id,replace_document_by_id"

# Command line
uvx couchbase-mcp-server --confirmation-required-tools delete_document_by_id,replace_document_by_id

Listelenen bir araç çağrıldığında:

• İstemci bilgi istemeyi destekliyorsa, kullanıcıdan onay istenir.
• İstemci bilgi istemeyi desteklemiyorsa, geriye dönük uyumluluk için araç onay olmadan yürütülür.

Sunucunun sürümünü de şu şekilde kontrol edebilirsiniz:

uvx couchbase-mcp-server --version

Günlükleme

MCP sunucusu varsayılan olarak stderr konumuna günlük kaydeder. Günlükleme, Ek Yapılandırma bölümünde listelenen CB_MCP_LOG_* değişkenleriyle yapılandırılır:

• CB_MCP_LOG_LEVEL — ne kadar günlük kaydedileceği: info (varsayılan) yaşam döngüsü olaylarını ve araç çağrılarını kaydeder, debug ayrıntılı dahili bilgi ekler ve off tüm günlüklemeyi devre dışı bırakır.
• CB_MCP_LOG_SINKS — günlüklerin nereye gideceği: stderr (varsayılan), seviye başına dönen dosyalar (file) veya her ikisi. file ile, CB_MCP_LOG_FILE tarafından belirlenen yolda seviye başına bir dosya yazılır (örneğin mcp_server.info.log ve mcp_server.error.log).
• Döndürme boyutu — CB_MCP_LOG_ROTATION_MAX_SIZE_MB, her seviyedeki dosyanın döndüğü genel boyuttur (MB cinsinden). Tek tek seviyeleri CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG) ile geçersiz kılın, ayrıca MB cinsinden, ayarlanmadığında genel değeri devralır. 0 boyutu (genel veya seviye başına) geçersizdir ve başlangıç uyarısıyla varsayılana (1 MB) geri döner. CB_MCP_LOG_MAX_BYTES (bayt) kullanımdan kaldırıldı ancak geriye dönük uyumluluk için hâlâ onurlandırılır; CB_MCP_LOG_ROTATION_MAX_SIZE_MB de ayarlandığında yok sayılır ve başlangıçta bir kullanımdan kaldırma uyarısı yazdırır.
• Saklama — CB_MCP_LOG_RETENTION_BACKUP_COUNT, seviye başına (canlı dosya hariç) kaç döndürülmüş yedek kopyanın tutulacağını belirler; 1 varsayılanı önceki davranışı korur. Tek tek seviyeleri CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG) ile geçersiz kılın, ayarlanmadığında genel değeri devralır. Bir sayımı 0 olarak ayarlayın; bu seviye için yalnızca canlı dosya tutulur — yine de döndürme boyutuyla sınırlıdır (yedeklenmek yerine döndürmede sıfırlanır).
• Sunucu yapılandırma anlık görüntüsü — file havuzu etkin olduğunda, tek seferlik bir kayıt (OS, Python, bağımlılık sürümleri, taşıma, çözümlenmiş günlükleme yapılandırması ve gizlenmiş sunucu yapılandırması) özel bir mcp_server_config.log.json dosyasına (CB_MCP_LOG_FILE tabanından türetilir) JSON olarak yazılır. Her başlangıçta üzerine yazılır, böylece destek her zaman güncel yapılandırmaya sahip olur ve dönen bir günlükten asla kaybolmaz.

# Enable debug logging to both stderr and rotating per-level files
uvx couchbase-mcp-server --log-level=debug --log-sinks=stderr,file

# Keep 30 rotated ERROR backups but only the live DEBUG file
uvx couchbase-mcp-server --log-level=debug --log-sinks=file \
  --log-error-retention-backup-count=30 --log-debug-retention-backup-count=0

Daha fazla ayrıntı için belgelere bakın.

İstemciye Özel Yapılandırma

Operasyonel İçgörüler Sunucusu

Varsayılan operational sunucusunun (yukarıdaki her bölümün açıkladığı) yanında, bu dağıtım Operasyonel İçgörüler kümeleri için ayrı bir couchbase-operational-insights SDK kullanan ikinci bir sunucu içerir. Normal bir Couchbase kümesinden farklı bir üründür ve kendi bağlantı noktasında bağımsız bir işlem olarak çalışır.

CLI alt komutu olarak operational-insights ileterek çalıştırın (veya kapsayıcının komutuna ekleyerek):

uvx couchbase-mcp-server operational-insights
# or, from source:
uv run src/mcp_server.py operational-insights
# or, via Docker:
docker run --rm -i \
  -e CB_OI_CONNECTION_STRING=http://localhost:8095 \
  -e CB_OI_USERNAME=Administrator \
  -e CB_OI_PASSWORD=password \
  couchbase/mcp-server:<version> operational-insights

--connection-string bir HTTP(S) URL'sidir, couchbase:// bağlantı dizesi değildir — örn. yerel bir Operasyonel İçgörüler sunucusu için http://localhost:8095 veya Capella için https://<host>:18095. Bu, bu sunucuyu bir kümeye yönlendirirken en yaygın yanlış yapılandırmadır.

Diğer tüm bayraklar (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) operasyonel sunucununkilerle aynıdır — bkz. MCP Sunucusu için Ek Yapılandırma — port (8001, 8000 değil) ve günlük dosyası (mcp_server_operational_insights.log, mcp_server.log değil) varsayılanları hariç, çünkü iki sunucu bunların hiçbirini paylaşamaz. OAuth, operasyonel sunucuyla aynı kapsam etiketlerini (couchbase-mcp:read / couchbase-mcp:write) kullanır, bu nedenle mevcut bir IdP yapılandırması her ikisi için de değişiklik yapılmadan çalışır.

Örnek MCP istemci yapılandırması:

{
  "mcpServers": {
    "couchbase-operational-insights": {
      "command": "uvx",
      "args": ["couchbase-mcp-server", "operational-insights"],
      "env": {
        "CB_OI_CONNECTION_STRING": "http://localhost:8095",
        "CB_OI_USERNAME": "Administrator",
        "CB_OI_PASSWORD": "password"
      }
    }
  }
}

Araç listesi için yukarıdaki Operational Insights araçları bölümüne ve operasyonel sunucuyla paylaşılan üç araç adı hakkındaki nota bakın.

Her iki sunucu da tek bir MCP Kayıt Defteri listesini paylaşır, io.github.couchbase/mcp-server-couchbase, şuradan yayınlanır: server.json. Liste, her sunucu için ayrı bir paket girişine sahiptir (PyPI ve Docker). Her giriş, kendi alt komutunu (operational veya operational-insights) iletir ve yalnızca o sunucunun argümanlarını ve ortam değişkenlerini bildirir.

Akışkan HTTP Taşıma Modu

MCP Sunucusu, birden çok istemcinin aynı sunucu örneğine HTTP üzerinden bağlanmasına olanak tanıyan Akışkan HTTP taşıma modunda çalıştırılabilir. Bu modda MCP sunucusuna bağlanmaya çalışmadan önce MCP istemcinizin akışkan http taşımasını destekleyip desteklemediğini kontrol edin.

Not: Bu taşımada OAuth 2.1 yetkilendirmesi desteklenir. Bkz. OAuth 2.1 Yetkilendirmesi. OAuth yapılandırılmamışsa, HTTP uç noktası kimlik doğrulamasızdır.

Kullanım

Varsayılan olarak, MCP sunucusu 8000 portunda çalışır, ancak bu, --port veya CB_MCP_PORT ortam değişkeni kullanılarak yapılandırılabilir.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=http

Sunucu http://localhost:8000/mcp adresinde kullanılabilir olacaktır. Bu, Cursor gibi akışkan http taşıma modunu destekleyen MCP istemcilerinde kullanılabilir.

MCP İstemci Yapılandırması

{
  "mcpServers": {
    "couchbase-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

SSE Taşıma Modu

MCP sunucusunu Sunucu Tarafından Gönderilen Olaylar (SSE) taşıma modunda çalıştırma seçeneği vardır.

Not: SSE modu MCP tarafından kullanımdan kaldırılmıştır. Akışkan HTTP için desteğimiz vardır.

SSE: Kullanım

Varsayılan olarak, MCP sunucusu 8000 portunda çalışır, ancak bu, --port veya CB_MCP_PORT ortam değişkeni kullanılarak yapılandırılabilir.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --read-only-mode=true \
  --transport=sse

Sunucu http://localhost:8000/sse adresinde kullanılabilir olacaktır. Bu, Cursor gibi SSE taşıma modunu destekleyen MCP istemcilerinde kullanılabilir.

SSE: MCP İstemci Yapılandırması

{
  "mcpServers": {
    "couchbase-sse": {
      "url": "http://localhost:8000/sse"
    }
  }
}

OAuth 2.1 Yetkilendirmesi

--transport=http ile çalışırken, MCP sunucusu bir OAuth 2.1 kaynak sunucusu olarak hareket edebilir: gelen taşıyıcı JWT'lerini kimlik sağlayıcınızın JWKS'sine karşı doğrular. Sağlayıcıdan bağımsızdır (JWKS yayınlayan herhangi bir OAuth 2.1 / OIDC sağlayıcısı — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, vb.) ve belirteç vermez veya kullanıcıları yönetmez. OAuth ayarları stdio üzerinde yok sayılır.

OAuth, Ek Yapılandırma bölümünde listelenen CB_MCP_OAUTH_* değişkenleriyle yapılandırılır:

• OAuth yalnızca CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER ve CB_MCP_OAUTH_JWT_AUDIENCE öğelerinin üçü de ayarlandığında etkinleşir; yalnızca bazılarını ayarlamak başlangıçta başarısız olur.
• CB_MCP_OAUTH_MCP_BASE_URL ayarının yapılması, PRM farkında istemcilerin yetkilendirme sunucusunu keşfedebilmesi için RFC 9728 Korumalı Kaynak Meta Verilerini ek olarak yayınlar.
• Erişim, belirtecin scope/scp iddiasından okunan iki kapsam tarafından denetlenir: couchbase-mcp:read (SQL++ dahil okuma araçları) ve couchbase-mcp:write (yazma araçları: KV mutasyonları, kapsam/koleksiyon yönetimi ve dizin yönetimi). Tam erişim her ikisini de gerektirir. IdP'niz bu standart etiketleri yayamıyorsa, bunları CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL ile geçersiz kılın.

uvx couchbase-mcp-server \
  --connection-string='<couchbase_connection_string>' \
  --username='<database_username>' \
  --password='<database_password>' \
  --transport=http \
  --oauth-jwks-uri='https://auth.example.com/.well-known/jwks.json' \
  --oauth-issuer='https://auth.example.com/' \
  --oauth-audience='couchbase-mcp-server' \
  --oauth-mcp-base-url='<public_base_url_of_this_server>'

Tam ayrıntılar için belgelere bakın.

Docker Görüntüsü

MCP sunucusu ayrıca bir Docker kapsayıcısı olarak derlenebilir ve çalıştırılabilir. Önceden derlenmiş görüntüler DockerHub üzerinde bulunabilir veya docker pull docker.io/couchbase/mcp-server:latest ile çekilebilir.

Alternatif olarak, Docker MCP Kataloğu bölümünün bir parçasıyız.

Görüntü Derleme

docker build -t mcp/couchbase-src .

docker build --build-arg GIT_COMMIT_HASH=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') \
  -t mcp/couchbase-src .

# Build with default image name (mcp/couchbase-src)
./build.sh

# Build with custom image name
./build.sh my-custom/image-name

# View git commit hash in image
docker inspect --format='{{index .Config.Labels "org.opencontainers.image.revision"}}' mcp/couchbase-src:latest

# View all metadata labels
docker inspect --format='{{json .Config.Labels}}' mcp/couchbase-src:latest

Çalıştırma

MCP sunucusu, Couchbase ayarlarını yapılandırmak için ortam değişkenleri kullanılarak çalıştırılabilir. Ortam değişkenleri, Ek Yapılandırma bölümünde açıklananlarla aynıdır.

Bağımsız Docker Kapsayıcısı

docker run --rm -i \
  -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
  -e CB_USERNAME='<database_user>' \
  -e CB_PASSWORD='<database_password>' \
  -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
  -e CB_MCP_READ_ONLY_MODE='<true|false>' \
  -e CB_MCP_CONFIRMATION_REQUIRED_TOOLS='delete_document_by_id' \
  -e CB_MCP_PORT=9001 \
  -e CB_MCP_HOST=0.0.0.0 \
  -p 9001:9001 \
  mcp/couchbase-src

CB_MCP_PORT ve CB_MCP_HOST ortam değişkenleri yalnızca http ve sse gibi HTTP taşıma modları durumunda geçerlidir.

Docker: MCP İstemci Yapılandırması

Docker görüntüsü, aşağıdaki yapılandırmayla stdio taşıma modunda kullanılabilir.

{
  "mcpServers": {
    "couchbase-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CB_CONNECTION_STRING=<couchbase_connection_string>",
        "-e",
        "CB_USERNAME=<database_user>",
        "-e",
        "CB_PASSWORD=<database_password>",
        "mcp/couchbase-src"
      ]
    }
  }
}

Notlar

• couchbase_connection_string değeri, Couchbase sunucusunun aynı ana makinede, başka bir Docker kapsayıcısında veya uzak bir ana bilgisayarda çalışıp çalışmadığına bağlıdır. Couchbase sunucunuz ana makinenizde çalışıyorsa, bağlantı dizginiz büyük olasılıkla couchbase://host.docker.internal biçiminde olacaktır. Ayrıntılar için docker belgelerine bakın.
• Kapsayıcının ağını --network=<your_network> seçeneğini kullanarak belirtebilirsiniz. Seçtiğiniz ağ ortamınıza bağlıdır; varsayılan bridge'dır. Ayrıntılar için docker'daki ağ sürücülerine bakın.

LLM'lerle İlişkili Riskler

• Büyük dil modellerinin ve benzer teknolojilerin kullanımı, yanlış veya zararlı çıktılar potansiyeli dahil olmak üzere riskler içerir.
• Couchbase, bu tür çıktıların kalitesini veya doğruluğunu incelemez veya değerlendirmez ve bu tür çıktılar Couchbase'in görüşlerini yansıtmayabilir.
• Büyük dil modellerini ve ilgili teknolojiyi kullanıp kullanmamaya karar vermek ve bunların kullanımını yöneten herhangi bir lisans hükmüne, kullanım koşuluna ve kuruluşunuzun politikalarına uymak yalnızca sizin sorumluluğunuzdadır.

Kullanım Verisi Toplama

Bu ürün otomatik olarak kullanım ve performans verilerini (ürün adı ve sürümü gibi) ve tarayıcı bilgilerini (IP adresi gibi) (topluca "Kullanım Verileri") toplar. Couchbase, Kullanım Verilerini, Couchbase'e sağlayabileceğiniz diğer verilerle (kullanıcı adınız veya e-posta adresiniz gibi) birlikte, ürünlerimizi geliştirmek ve iyileştirmek ve satış ve pazarlama programlarımızı bilgilendirmek için kullanır. Couchbase ürünlerinde sakladığınız hiçbir veriye erişmez veya toplamayız. Kullanım Verilerini, toplu kullanım kalıplarını anlamak ve ürünlerimizi sizin için daha kullanışlı hale getirmek için kullanırız. Couchbase'in bilgileri nasıl topladığı, koruduğu ve işlediği hakkında daha fazla bilgi için lütfen https://www.couchbase.com/privacy-policy. adresinde görüntülenebilen Couchbase Gizlilik Politikasına bakın.

Sorun Giderme İpuçları

• Kaynaktan çalıştırıyorsanız, yapılandırmada MCP sunucu deponuzun yolunun doğru olduğundan emin olun.
• Couchbase bağlantı dizginizin, veritabanı kullanıcı adınızın, parolanızın veya sertifikaların yolunun doğru olduğunu doğrulayın.
• Couchbase Capella kullanıyorsanız, kümenin MCP sunucusunun çalıştığı makineden erişilebilir olduğundan emin olun.
• Veritabanı kullanıcısının en az bir kovaya erişmek için uygun izinlere sahip olduğunu kontrol edin.
• uv paket yöneticisinin düzgün şekilde kurulu ve erişilebilir olduğunu doğrulayın. Yapılandırmadaki command alanında uv/uvx için mutlak yol sağlamanız gerekebilir.
• MCP sunucusuyla ilgili sorunları gösterebilecek hatalar veya uyarılar için günlükleri kontrol edin. Günlüklerin konumu MCP istemcinize bağlıdır.
• Yerel MCP sunucu deponuzu güncelledikten sonra MCP sunucunuzu kaynaktan çalıştırırken sorunlar yaşıyorsanız, bağımlılıkları güncellemek için uv sync komutunu çalıştırmayı deneyin.

Entegrasyon testi

Sunucunun beklenen araçları ortaya çıkardığını ve bunların bir demo Couchbase kümesine karşı çağrılabileceğini doğrulamak için üst düzey MCP entegrasyon testleri sağlıyoruz.

1. Demo küme kimlik bilgilerini dışa aktarın:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • İsteğe bağlı: CB_MCP_TEST_BUCKET (testler sırasında yoklanacak bir kova)
   • İsteğe bağlı, Operational Insights sunucusunun kendi testleri için: CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD. Bu testler ayarlanmadığında otomatik olarak atlanır (başarısız olmaz).
2. Testleri çalıştırın:

uv run --extra dev pytest tests/integration -v

SSS

Couchbase MCP Sunucusu nedir? Yapay zeka asistanlarının ve aracılarının (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie ve diğer tüm MCP istemcileri) doğal dil kullanarak bir Couchbase kümesindeki verileri sorgulamasına ve isteğe bağlı olarak değiştirmesine olanak tanıyan, kendi kendine barındırılan bir Model Context Protocol uygulamasıdır.

Claude Desktop'ı Couchbase'e nasıl bağlarım? Sunucuyu uvx couchbase-mcp-server ile kurun (veya kaynaktan ya da Docker'dan çalıştırın), ardından Yapılandırma bölümünde gösterildiği gibi yapılandırmasını Claude Desktop'un claude_desktop_config.json dosyasına ekleyin. Claude Desktop'ı yeniden başlatın; yeni araçları algılayacaktır.

Bunu Couchbase Capella ile kullanabilir miyim? Evet. Aynı CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD (veya mTLS sertifikası) yapılandırması hem Couchbase Capella hem de kendi kendine yönetilen Couchbase Server kümeleri için çalışır.

Bir yapay zeka aracısının veritabanıma yazmasına izin vermek güvenli mi? Varsayılan olarak, CB_MCP_READ_ONLY_MODE true'dur, bu nedenle tüm yazma işlemleri — belge upsert/insert/replace/delete ve veri değiştiren SQL++ ifadeleri — devre dışıdır ve yazma araçları yüklenmez bile. Ayrıca tek tek araçları devre dışı bırakabilir (bkz. Araçları Devre Dışı Bırakma) veya belirli araçlar çalışmadan önce açık kullanıcı onayı isteyebilirsiniz (bkz. Elicitation/Onay). Araç düzeyindeki kontroller LLM davranışını yönlendirir; Couchbase kullanıcınızın RBAC izinleri gerçek güvenlik sınırı olmaya devam eder.

Verilerime karşı SQL++ yazmadan doğal dil sorguları çalıştırabilir miyim? Evet — yapay zeka asistanınıza düz İngilizce bir soru sorun (ör. "bana 100$ üzerindeki en son 10 siparişi göster") ve run_sql_plus_plus_query aracını kullanarak bunu bir SQL++ sorgusuna çevirebilir. Ayrıca asistandan bir sorguyu explain_sql_plus_plus_query yapmasını veya dizin danışmanından öneriler istemesini isteyebilirsiniz. STDIO, Streamable HTTP ve SSE taşımacılığı arasındaki fark nedir? STDIO, tek bir yerel MCP istemcisi (ör. Claude Desktop) için sunucuyu bir alt süreç olarak başlatan yapıdır. Streamable HTTP, birden fazla istemcinin HTTP üzerinden tek bir çalışan sunucu örneğini paylaşmasına olanak tanır ve OAuth 2.1'i destekler. SSE, daha eski HTTP taşımacılığıdır ve MCP spesifikasyonu tarafından Streamable HTTP lehine kullanımdan kaldırılmıştır — bkz. Streamable HTTP Taşıma Modu.

Bu, Couchbase tarafından resmi olarak destekleniyor mu? Bu proje Couchbase topluluğu tarafından bakımı yapılmaktadır — bkz. Destek Politikası. Kurumsal destek, Couchbase AI Veri Düzlemi aracılığıyla ayrıca sağlanmaktadır.

Katkıda Bulunma

Topluluktan gelen katkıları memnuniyetle karşılıyoruz! Hata düzeltmek, özellik eklemek veya dokümantasyonu iyileştirmek istiyorsanız, yardımınız takdir edilir.

Yardıma ihtiyacınız varsa, bir hata bulduysanız veya iyileştirmelere katkıda bulunmak istiyorsanız, bunu yapmak için en iyi yer tam da burasıdır — GitHub sorunu açarak.

Geliştiriciler İçin

Kod katkısında bulunmak veya bir geliştirme ortamı kurmakla ilgileniyorsanız:

📖 Kapsamlı geliştirici kurulum talimatları için CONTRIBUTING.md dosyasına bakın, şunlar dahil:

• uv ile geliştirme ortamı kurulumu
• Ruff ile kod lint ve biçimlendirme
• Pre-commit hook'larının kurulumu
• Proje yapısına genel bakış
• Geliştirme iş akışı ve uygulamaları

Katkıda Bulunanlar için Hızlı Başlangıç

# Clone and setup
git clone https://github.com/couchbase/mcp-server-couchbase.git
cd mcp-server-couchbase

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

# Run linting
./scripts/lint.sh

📢 Destek Politikası

Bu projeye olan ilginizi gerçekten takdir ediyoruz! Bu proje Couchbase topluluğu tarafından bakımı yapılmaktadır, yani destek ekibimiz tarafından resmi olarak desteklenmemektedir. Ancak mühendislerimiz bu depoyu aktif olarak izlemekte ve bakımını yapmakta olup, sorunları en iyi çaba düzeyinde çözmeye çalışacaktır.

Destek portalımız bu projeyle ilgili taleplerde yardımcı olamamaktadır, bu nedenle tüm sorularınızı GitHub üzerinde tutmanızı rica ediyoruz.

İş birliğiniz hepimizin birlikte ilerlemesine yardımcı oluyor — teşekkürler!