Couchbase

Couchbase MCP Sunucusu

Couchbase MCP Sunucusu, ister Capella ister kendi kendine yönetilen bir ortamda barındırılsın, yapay zeka aracılarının Couchbase kümelerine bağlanmasını ve bu kümelerdeki verilerle etkileşime girmesini sağlayan, kendi kendine barındırılan bir MCP Sunucusudur. Küme Sağlığı, Veri Şeması, Anahtar-Değer, Sorgu ve Performans gibi kategorilerde araçlar sunar; salt okunur mod ve ince ayarlı araç devre dışı bırakma özellikleriyle güvenlik kontrolleri sağlar. Hem STDIO hem de Akışkan HTTP aktarımlarını destekler.

Couchbase MCP sunucusu, bir Python Paket Dizini (PyPI) paketi olarak ve Docker aracılığıyla dağıtılır. Couchbase MCP Sunucusu için kurumsal destek, Couchbase AI Data Plane lisanslanarak edinilebilir; bu lisans aynı zamanda Couchbase Agent Memory ve Couchbase Agent Catalog kullanım ve kurumsal destek hakkı da verir.

Tam belgelendirme için mcp-server.couchbase.com adresini ziyaret edin.

Özellikler/Araçlar

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

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

Doküman KV işlem araçları

Sorgu ve indeksleme araçları

Sorgu performans analizi araçları

Ön Koşullar

• Python 3.10 veya üstü.
• Çalışan bir Couchbase kümesi. Başlamanın en kolay yolu, Couchbase sunucusunun tam yönetilen sürümü olan Capella ücretsiz katmanını kullanmaktır. Örnek veri kümelerinden birini içe aktarmak veya kendi verilerinizi içe aktarmak için talimatları takip edebilirsiniz.
• 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 verilmiştir. Diğer MCP istemcileri de kullanılabilir.

Yapılandırma

MCP sunucusu, önceden oluşturulmuş PyPI paketinden veya uv kullanarak kaynak koddan çalıştırılabilir.

PyPI'den Çalıştırma

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

MCP İstemcileri için Önceden Oluşturulmuş 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 kullanımda olan başka MCP sunucularınız varsa, bunu mevcut mcpServers nesnesine ekleyebilirsiniz.

Kaynak Koddan Çalıştırma

MCP sunucusu, bu depo kullanılarak kaynak koddan çalıştırılabilir.

Depoyu yerel makinenize klonlayın

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

MCP İstemcileri için Kaynak Kod 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 kullanımda olan başka MCP sunucularınız varsa, bunu mevcut mcpServers nesnesine ekleyebilirsiniz.

MCP Sunucusu için Ek Yapılandırma

Sunucu, ortam değişkenleri veya komut satırı argümanları 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 ve Sorgu) devre dışıdır. KV yazma araçları (upsert, insert, replace, delete) yüklenmez ve LLM tarafından kullanılamaz ve verileri veya yapıyı değiştiren SQL++ sorguları engellenir.
• false olduğunda: KV yazma araçları yüklenir ve SQL++ veri/yapı değişiklik sorgularına izin verilir.

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

Not: Kimlik doğrulama için Kullanıcı Adı ve Parola ya da İ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ın yüklenmesini ve MCP istemcisine sunulmasını engellemek için onları devre dışı bırakabilirsiniz. Devre dışı bırakılan araçlar, araç keşfinde görünmez ve LLM tarafından çağrılamaz.

Desteklenen Formatlar

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 (satır başına bir araç adı):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

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

Dosya formatı (ö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 kullanarak:

{
  "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 kullanarak (birçok 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ı: Yalnızca araçları devre dışı bırakmak, 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 denetimidir.

Örneğin, upsert_document_by_id ve delete_document_by_id araçlarını devre dışı bıraksanız bile, aşağıdaki durumlar haricinde run_sql_plus_plus_query aracı kullanılarak SQL++ DML ifadeleri (INSERT, UPDATE, DELETE, MERGE) aracılığıyla veri değişiklikleri yine de gerçekleşebilir:

• CB_MCP_READ_ONLY_MODE, true (varsayılan) olarak ayarlanmışsa, 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 her zaman Couchbase kullanıcı kimlik bilgilerinizde 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 denetimi olarak değil.

Araç Çağrıları için Ortaya Çıkarma/Onaylama

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

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

• Virgülle ayrılmış liste
• Dosya yolu (satır başına 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 ortaya çıkarmayı destekliyorsa, kullanıcıdan onaylaması istenir.
• İstemci ortaya çıkarmayı desteklemiyorsa, araç geriye dönük uyumluluk için onay olmadan yürütülür.

Ayrıca aşağıdakini kullanarak sunucunun sürümünü kontrol edebilirsiniz:

uvx couchbase-mcp-server --version

Günlüğe Kaydetme

MCP sunucusu varsayılan olarak stderr'e günlük kaydeder. Günlüğe kaydetme, 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ının günlüğe kaydedileceği: info (varsayılan) yaşam döngüsü olaylarını ve araç çağrılarını günlüğe kaydeder, debug ayrıntılı dahili ayrıntı ekler ve off tüm günlüğe kaydetmeyi 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).

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

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

İstemciye Özel Yapılandırma

Akışkan HTTP Aktarım Modu

MCP Sunucusu, birden fazla istemcinin HTTP aracılığıyla aynı sunucu örneğine bağlanmasına olanak tanıyan Akışkan HTTP aktarım modunda çalıştırılabilir. Bu modda MCP sunucusuna bağlanmayı denemeden önce MCP istemcinizin akışkan http aktarımını destekleyip desteklemediğini kontrol edin.

Not: Bu aktarımda OAuth 2.1 yetkilendirmesi desteklenir. Bkz. OAuth 2.1 Yetkilendirmesi. OAuth yapılandırılmadığında, HTTP uç noktası kimlik doğrulamasızdır.

Kullanım

Varsayılan olarak, MCP sunucusu 8000 numaralı bağlantı noktasında ç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 aktarım modunu destekleyen MCP istemcilerinde kullanılabilir.

MCP İstemci Yapılandırması

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

SSE Aktarım Modu

MCP sunucusunu Sunucu Tarafından Gönderilen Olaylar (SSE) aktarım 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 desteğimiz bulunmaktadır.

SSE: Kullanım

Varsayılan olarak, MCP sunucusu 8000 numaralı bağlantı noktasında ç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 aktarım 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'leri kimlik sağlayıcınızın JWKS'sine göre 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ç düzenlemez 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 değişkenlerinin üçü de ayarlandığında etkinleşir; yalnızca bazılarının ayarlanması başlangıçta başarısız olur.
• CB_MCP_OAUTH_MCP_BASE_URL ayarlandığında ayrıca RFC 9728 Korumalı Kaynak Meta Verileri yayınlanır, böylece PRM farkında istemciler yetkilendirme sunucusunu keşfedebilir.
• Erişim, belirtecin scope/scp talebinden okunan iki kapsam tarafından denetlenir: couchbase-mcp:read (SQL++ dahil okuma araçları) ve couchbase-mcp:write (KV mutasyon araçları). Tam erişim her ikisini de gerektirir.

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 İmajı

MCP sunucusu ayrıca bir Docker konteyneri olarak oluşturulabilir ve çalıştırılabilir. Önceden oluşturulmuş imajlar DockerHub üzerinde bulunabilir veya docker pull docker.io/couchbase/mcp-server:latest aracılığıyla çekilebilir.

Alternatif olarak, Docker MCP Kataloğu'nun bir parçasıyız.

İmaj Oluşturma

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 kullanılan ortam değişkenleriyle ç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 Konteyneri

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 aktarım modlarında geçerlidir.

Docker: MCP İstemci Yapılandırması

Docker imajı, aşağıdaki yapılandırmayla stdio aktarım 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 konteynerinde veya uzak bir ana makinede çalışıp çalışmadığına bağlıdır. Couchbase sunucunuz ana makinenizde çalışıyorsa, bağlantı dizeniz muhtemelen couchbase://host.docker.internal biçiminde olacaktır. Ayrıntılar için docker belgelerine bakın.
• Konteynerin ağ iletişimini --network=<your_network> seçeneğiyle belirtebilirsiniz. Seçeceğiniz ağ, ortamınıza bağlıdır; varsayılan bridge'dir. 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 teknolojinin kullanımı, hatalı veya zararlı çıktı potansiyeli de dahil olmak üzere riskler içerir.
• Couchbase, bu tür çıktıların kalitesini veya doğruluğunu incelemez veya değerlendirmez ve bu çıktılar Couchbase'in görüşlerini yansıtmayabilir.
• Büyük dil modellerini ve ilgili teknolojiyi kullanıp kullanmamaya karar vermekten ve bunların kullanımını düzenleyen lisans koşullarına, kullanım şartlarına ve kuruluşunuzun politikalarına uymaktan yalnızca siz sorumlusunuz.

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ı dizenizin, 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 bucket'a 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 onaylayın. Yapılandırmadaki command alanında uv/uvx için mutlak yol belirtmeniz gerekebilir.
• MCP sunucusuyla ilgili sorunlara işaret edebilecek 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 kaynaktan MCP sunucunuzu ç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ı sunduğunu ve bunların bir demo Couchbase kümesine karşı çağrılabildiğ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 bucket)
2. Testleri çalıştırın:

uv run pytest tests/ -v

👩‍💻 Katkıda Bulunma

Topluluktan gelecek katkıları memnuniyetle karşılıyoruz! Hataları düzeltmek, özellikler eklemek veya belgeleri iyileştirmek isterseniz, yardımınız için minnettarız.

Yardıma ihtiyacınız varsa, bir hata bulduysanız veya iyileştirmelerle katkıda bulunmak istiyorsanız, bunu yapmak için en iyi yer tam burasıdır — bir 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ı içerir:

• uv ile geliştirme ortamı kurulumu
• Ruff ile kod denetimi ve biçimlendirme
• Ön işleme kancalarının kurulumu
• Proje yapısına genel bakış
• Geliştirme iş akışı ve uygulamaları

Katkıda Bulunanlar İç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 gösterdiğiniz ilgi için gerçekten minnettarız! Bu proje Couchbase topluluğu tarafından sürdürülmektedir, yani destek ekibimiz tarafından resmi olarak desteklenmemektedir. Bununla birlikte, mühendislerimiz bu depoyu aktif olarak izlemekte ve sürdürmekte olup sorunları en iyi çabayla çözmeye çalışacaktır.

Destek portalımız bu projeyle ilgili taleplere yardımcı olamaz, bu nedenle tüm soruların GitHub içinde kalmasını rica ederiz.

İş birliğiniz hep birlikte ilerlememize yardımcı oluyor — teşekkür ederiz!