Couchbase

resmi

Berinteraksi dengan data yang tersimpan di klaster Couchbase menggunakan bahasa alami.

Apa yang bisa Anda lakukan dengan Couchbase MCP?

Minta asisten Anda untuk memeriksa kesehatan cluster, menjelajahi skema, menjalankan kueri SQL++, dan mengelola dokumen di cluster Couchbase Anda.

  • Jalankan kueri SQL++ — Minta asisten Anda untuk mengkueri data dengan run_sql_plus_plus_query, secara otomatis dibatasi pada bucket dan collection.
  • Jelajahi skema — Temukan bucket, scope, dan collection melalui get_buckets_in_cluster dan get_schema_for_collection.
  • Kelola dokumen — Baca, upsert, atau hapus dokumen berdasarkan ID dengan get_document_by_id dan upsert_document_by_id.
  • Periksa kesehatan cluster — Verifikasi konektivitas dan status layanan dengan test_cluster_connection dan get_cluster_health_and_services.
  • Optimalkan indeks — Daftarkan indeks dan dapatkan rekomendasi melalui list_indexes dan get_index_advisor_recommendations.
  • Analisis performa kueri — Temukan kueri yang lambat atau tidak selektif dengan get_longest_running_queries dan get_queries_using_primary_index.

Dokumentasi

Couchbase MCP Server

Couchbase MCP Server adalah MCP Server yang di-host sendiri yang memungkinkan agen AI terhubung dan berinteraksi dengan data di kluster Couchbase, baik yang di-host di Capella maupun yang dikelola sendiri. Server ini menyediakan alat di berbagai kategori termasuk Cluster Health, Data Schema, Key-Value, Query, dan Performa — dengan kontrol keamanan melalui mode baca-saja dan penonaktifan alat secara terperinci. Server ini mendukung transport STDIO dan Streamable HTTP.

Couchbase MCP server didistribusikan sebagai paket Python Package Index (PyPI) dan melalui Docker. Dukungan enterprise untuk Couchbase MCP Server tersedia dengan melisensikan Couchbase AI Data Plane, yang juga memberikan hak penggunaan dan dukungan enterprise untuk Couchbase Agent Memory dan Couchbase Agent Catalog.

Docs License Python 3.10+ PyPI version Install in Cursor Verified on MseeP Trust Score

Untuk dokumentasi lengkap, kunjungi mcp-server.couchbase.com.

Couchbase Server MCP server

Fitur/Alat

Alat pengaturan & kesehatan kluster

Nama AlatDeskripsi
get_server_configuration_statusDapatkan status dan konfigurasi server tanpa terhubung ke kluster — melaporkan mode baca-saja, alat yang dinonaktifkan/ memerlukan konfirmasi, pengaturan OAuth, dan konfigurasi logging yang diselesaikan
test_cluster_connectionPeriksa kredensial kluster dengan terhubung ke kluster
get_cluster_health_and_servicesDapatkan status kesehatan kluster dan daftar semua layanan yang berjalan

Alat penemuan model data & skema

Nama AlatDeskripsi
get_buckets_in_clusterDapatkan daftar semua bucket di kluster
get_scopes_in_bucketDapatkan daftar semua scope di bucket yang ditentukan
get_collections_in_scopeDapatkan daftar semua koleksi di scope dan bucket yang ditentukan. Perhatikan bahwa alat ini memerlukan kluster untuk memiliki layanan Query.
get_scopes_and_collections_in_bucketDapatkan daftar semua scope dan koleksi di bucket yang ditentukan
get_schema_for_collectionDapatkan struktur untuk sebuah koleksi
create_scopeBuat scope baru di bucket (Couchbase Server 7.6+ dan Capella). Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
create_collectionBuat koleksi baru di scope yang sudah ada (Couchbase Server 7.6+ dan Capella). Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
delete_scopeHapus scope dan semua koleksinya dari bucket — permanen. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
delete_collectionHapus koleksi dan semua dokumennya dari scope — permanen. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.

Alat operasi KV dokumen

Nama AlatDeskripsi
get_document_by_idDapatkan dokumen berdasarkan ID dari scope dan koleksi yang ditentukan
lookup_subdocumentCari bagian-bagian dokumen (bidang tertentu, pemeriksaan keberadaan, atau jumlah array/objek) berdasarkan jalur tanpa mengambil seluruh dokumen
upsert_document_by_idUpsert dokumen berdasarkan ID ke scope dan koleksi yang ditentukan. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
insert_document_by_idSisipkan dokumen baru berdasarkan ID (gagal jika dokumen sudah ada). Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
replace_document_by_idGanti dokumen yang ada berdasarkan ID (gagal jika dokumen tidak ada). Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
delete_document_by_idHapus dokumen berdasarkan ID dari scope dan koleksi yang ditentukan. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
mutate_subdocumentUbah bagian-bagian dokumen yang ada (upsert, sisipkan, ganti, hapus, operasi array, penghitung) berdasarkan jalur tanpa menulis ulang seluruh dokumen. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.

Alat kueri dan pengindeksan

Nama AlatDeskripsi
list_indexesDaftarkan semua indeks di kluster beserta definisinya, dengan penyaringan opsional berdasarkan bucket, scope, koleksi, dan nama indeks. Atur return_raw_index_stats=true untuk mengembalikan informasi indeks yang belum diproses.
get_index_advisor_recommendationsDapatkan rekomendasi indeks dari Couchbase Index Advisor untuk kueri SQL++ tertentu untuk mengoptimalkan performa kueri
create_indexBuat indeks sekunder GSI skalar (non-vektor) pada koleksi. Ditunda secara default — panggil build_index setelahnya untuk membangunnya. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
build_indexPicu pembangunan semua indeks yang ditunda pada koleksi. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
drop_indexHapus indeks GSI (skalar atau vektor) dari koleksi. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true.
run_sql_plus_plus_queryJalankan kueri SQL++ pada scope yang ditentukan.

Kueri secara otomatis dibatasi pada bucket dan scope yang ditentukan, jadi gunakan nama koleksi secara langsung (misalnya, SELECT * FROM users alih-alih SELECT * FROM bucket.scope.users).

CB_MCP_READ_ONLY_MODE adalah true secara default, yang berarti semua operasi penulisan (KV, Kueri, manajemen scope/koleksi, dan manajemen indeks) dinonaktifkan. Saat diaktifkan, alat penulisan KV, manajemen koleksi, dan indeks tidak dimuat dan kueri SQL++ yang mengubah data diblokir.
explain_sql_plus_plus_queryBuat dan evaluasi rencana EXPLAIN untuk kueri SQL++. Mengembalikan metadata kueri, rencana yang diekstrak, dan temuan evaluasi rencana.

Alat analisis performa kueri

Nama AlatDeskripsi
get_longest_running_queriesDapatkan kueri yang berjalan paling lama berdasarkan waktu layanan rata-rata
get_most_frequent_queriesDapatkan kueri yang paling sering dijalankan
get_queries_with_largest_response_sizesDapatkan kueri dengan ukuran respons terbesar
get_queries_with_large_result_countDapatkan kueri dengan jumlah hasil terbesar
get_queries_using_primary_indexDapatkan kueri yang menggunakan indeks primer (potensi masalah performa)
get_queries_not_using_covering_indexDapatkan kueri yang tidak menggunakan covering index
get_queries_not_selectiveDapatkan kueri yang tidak selektif (pemindaian indeks mengembalikan lebih banyak dokumen daripada hasil akhir)

Prasyarat

  • Python 3.10 atau lebih tinggi.
  • Kluster Couchbase yang berjalan. Cara termudah untuk memulai adalah menggunakan Capella tingkat gratis, yang merupakan versi terkelola penuh dari server Couchbase. Anda dapat mengikuti instruksi untuk mengimpor salah satu kumpulan data sampel atau mengimpor data Anda sendiri.
  • uv terinstal untuk menjalankan server.
  • Klien MCP seperti Claude Desktop yang terinstal untuk menghubungkan server ke Claude. Instruksi disediakan untuk Claude Desktop dan Cursor. Klien MCP lain juga dapat digunakan.

Konfigurasi

Server MCP dapat dijalankan baik dari paket PyPI yang sudah dibuat maupun dari sumber menggunakan uv.

Menjalankan dari PyPI

Kami menerbitkan paket PyPI yang sudah dibuat untuk server MCP.

Konfigurasi Server menggunakan Paket yang Sudah Dibuat untuk Klien MCP

Autentikasi Dasar

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

atau

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

Catatan: Jika Anda memiliki server MCP lain yang digunakan di klien, Anda dapat menambahkannya ke objek mcpServers yang sudah ada.

Menjalankan dari Sumber

Server MCP dapat dijalankan dari sumber menggunakan repositori ini.

Klon repositori ke mesin lokal Anda

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

Konfigurasi Server menggunakan Sumber untuk Klien MCP

Ini adalah konfigurasi umum untuk klien MCP seperti Claude Desktop, Cursor, Windsurf Editor.

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

Catatan: path/to/cloned/repo/mcp-server-couchbase/ harus menjadi jalur ke repositori yang dikloning di mesin lokal Anda. Jangan lupa garis miring di akhir!

Catatan: Jika Anda memiliki server MCP lain yang digunakan di klien, Anda dapat menambahkannya ke objek mcpServers yang sudah ada.

Konfigurasi Tambahan untuk Server MCP

Server dapat dikonfigurasi menggunakan variabel lingkungan atau argumen baris perintah:

Variabel LingkunganArgumen CLIDeskripsiBawaan
CB_CONNECTION_STRING--connection-stringString koneksi ke cluster CouchbaseDiperlukan
CB_USERNAME--usernameNama pengguna dengan akses ke bucket yang diperlukan untuk autentikasi dasarDiperlukan (atau Sertifikat Klien dan Kunci diperlukan untuk mTLS)
CB_PASSWORD--passwordKata sandi untuk autentikasi dasarDiperlukan (atau Sertifikat Klien dan Kunci diperlukan untuk mTLS)
CB_CLIENT_CERT_PATH--client-cert-pathJalur ke file sertifikat klien untuk autentikasi mTLSDiperlukan jika menggunakan mTLS (atau Nama Pengguna dan Kata Sandi diperlukan)
CB_CLIENT_KEY_PATH--client-key-pathJalur ke file kunci klien untuk autentikasi mTLSDiperlukan jika menggunakan mTLS (atau Nama Pengguna dan Kata Sandi diperlukan)
CB_CA_CERT_PATH--ca-cert-pathJalur ke sertifikat root server untuk TLS jika server dikonfigurasi dengan sertifikat yang ditandatangani sendiri/tidak tepercaya. Ini tidak diperlukan jika Anda terhubung ke Capella
CB_MCP_READ_ONLY_MODE--read-only-modeMencegah semua modifikasi data (KV, Query, manajemen scope/collection, dan manajemen indeks). Saat diaktifkan, alat tulis KV, manajemen collection, dan indeks tidak dimuat.true
CB_MCP_TRANSPORT--transportMode transport: stdio, http, ssestdio
CB_MCP_HOST--hostHost untuk mode transport HTTP/SSE127.0.0.1
CB_MCP_PORT--portPort untuk mode transport HTTP/SSE8000
CB_MCP_DISABLED_TOOLS--disabled-toolsAlat untuk dinonaktifkan (lihat Menonaktifkan Alat)Tidak ada
CB_MCP_CONFIRMATION_REQUIRED_TOOLS--confirmation-required-toolsAlat yang memerlukan konfirmasi eksplisit pengguna sebelum eksekusi melalui elisitasi MCP (lihat Alat yang Memerlukan Elisitasi/Konfirmasi)Tidak ada
CB_MCP_LOG_LEVEL--log-levelTingkat pencatatan untuk server MCP: off, debug, info, warning, error (lihat Pencatatan)info
CB_MCP_LOG_SINKS--log-sinksTujuan log yang dipisahkan koma: stderr, file, atau keduanya (lihat Pencatatan)stderr
CB_MCP_LOG_FILE--log-fileJalur dasar untuk file log per tingkat (hanya digunakan saat sink file diaktifkan)mcp_server.log
CB_MCP_LOG_ROTATION_MAX_SIZE_MB--log-rotation-max-size-mbUkuran maksimum global dalam MB per file log sebelum rotasi, diwarisi oleh setiap tingkat kecuali ditimpa. 0 tidak valid dan kembali ke bawaan dengan peringatan saat startup1 (1 MB)
CB_MCP_LOG_MAX_BYTES--log-max-bytesTidak digunakan lagi — gunakan CB_MCP_LOG_ROTATION_MAX_SIZE_MB (MB). Ukuran rotasi global dalam byte, masih dihormati untuk kompatibilitas mundur; diabaikan saat CB_MCP_LOG_ROTATION_MAX_SIZE_MB juga diaturTidak diatur
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB--log-error-rotation-max-size-mbUkuran rotasi dalam MB untuk file log ERROR; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk ERRORMewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB--log-warning-rotation-max-size-mbUkuran rotasi dalam MB untuk file log WARNING; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk WARNINGMewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB--log-info-rotation-max-size-mbUkuran rotasi dalam MB untuk file log INFO; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk INFOMewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB--log-debug-rotation-max-size-mbUkuran rotasi dalam MB untuk file log DEBUG; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk DEBUGMewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB
CB_MCP_LOG_RETENTION_BACKUP_COUNT--log-retention-backup-countFile cadangan rotasi yang disimpan per file log tingkat (tidak termasuk file aktif), diterapkan ke setiap tingkat kecuali ditimpa. 0 hanya menyimpan file aktif (lihat Pencatatan)1
CB_MCP_LOG_ERROR_RETENTION_BACKUP_COUNT--log-error-retention-backup-countCadangan rotasi yang disimpan untuk file log ERROR; menimpa jumlah global untuk ERRORMewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT--log-warning-retention-backup-countCadangan rotasi yang disimpan untuk file log WARNING; menimpa jumlah global untuk WARNINGMewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT--log-info-retention-backup-countCadangan rotasi yang disimpan untuk file log INFO; menimpa jumlah global untuk INFOMewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT--log-debug-retention-backup-countCadangan rotasi yang disimpan untuk file log DEBUG; menimpa jumlah global untuk DEBUGMewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT
CB_MCP_OAUTH_JWT_JWKS_URI--oauth-jwks-uriEndpoint JWKS dari penyedia identitas yang digunakan untuk memverifikasi JWT bearer. Mengaktifkan OAuth saat diatur dengan issuer dan audience (lihat Otorisasi OAuth 2.1)Tidak ada
CB_MCP_OAUTH_JWT_ISSUER--oauth-issuerKlaim iss JWT yang diharapkan. Diperlukan untuk mengaktifkan OAuthTidak ada
CB_MCP_OAUTH_JWT_AUDIENCE--oauth-audienceKlaim aud JWT yang diharapkan. Diperlukan untuk mengaktifkan OAuthTidak ada
CB_MCP_OAUTH_JWT_ALGORITHM--oauth-algorithmAlgoritma penandatanganan JWT: salah satu dari RS256/384/512, ES256/384/512, PS256/384/512RS256
CB_MCP_OAUTH_MCP_BASE_URL--oauth-mcp-base-urlURL dasar publik dari server ini. Saat diatur, menerbitkan Metadata Sumber Daya yang Dilindungi RFC 9728 sehingga klien yang sadar PRM dapat menemukan IdPTidak ada
CB_MCP_OAUTH_SCOPE_READ_LABEL--oauth-scope-read-labelTimpa label lingkup OAuth yang diperlakukan sebagai akses 'baca' (diiklankan di PRM dan dicocokkan dengan klaim scope/scp token). Gunakan saat IdP Anda tidak dapat mengeluarkan bentuk kanonikcouchbase-mcp:read
CB_MCP_OAUTH_SCOPE_WRITE_LABEL--oauth-scope-write-labelTimpa label lingkup OAuth yang diperlakukan sebagai akses 'tulis'; semantik yang sama dengan label bacacouchbase-mcp:write

Konfigurasi Mode Hanya-Baca

CB_MCP_READ_ONLY_MODE adalah sakelar tunggal yang mengontrol operasi tulis:

  • Saat true (bawaan): Semua operasi tulis (KV, Query, manajemen scope/collection, dan manajemen indeks) dinonaktifkan. Alat tulis KV (upsert, insert, replace, delete, sub-document mutate), alat tulis manajemen scope/collection (create_scope, create_collection, delete_scope, delete_collection), dan alat tulis indeks (create_index, build_index, drop_index) tidak dimuat dan tidak akan tersedia untuk LLM, serta kueri SQL++ yang memodifikasi data atau struktur diblokir.
  • Saat false: Alat tulis KV, manajemen scope/collection, dan indeks dimuat dan kueri modifikasi data/struktur SQL++ diizinkan.

Ini adalah bawaan aman yang direkomendasikan untuk mencegah modifikasi data yang tidak disengaja oleh LLM.

Catatan: Untuk autentikasi, Anda memerlukan Nama Pengguna dan Kata Sandi atau jalur Sertifikat Klien dan kunci. Secara opsional, Anda dapat menentukan jalur sertifikat root CA yang akan digunakan untuk memvalidasi sertifikat server. Jika kedua jalur Sertifikat Klien & kunci dan nama pengguna dan kata sandi ditentukan, sertifikat klien akan digunakan untuk autentikasi.

Menonaktifkan Alat

Anda dapat menonaktifkan alat tertentu untuk mencegahnya dimuat dan diekspos ke klien MCP. Alat yang dinonaktifkan tidak akan muncul dalam penemuan alat dan tidak dapat dipanggil oleh LLM.

Format yang Didukung

Daftar yang dipisahkan koma:

# 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

Jalur file (satu nama alat per baris):

# Environment variable
CB_MCP_DISABLED_TOOLS=disabled_tools.txt

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

Format file (mis., disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Baris yang dimulai dengan # diperlakukan sebagai komentar dan diabaikan.

Contoh Konfigurasi Klien MCP

Menggunakan daftar yang dipisahkan koma:

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

Menggunakan jalur file (disarankan untuk banyak alat):

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

Catatan Keamanan Penting

Peringatan: Menonaktifkan alat saja tidak menjamin bahwa operasi tertentu tidak dapat dilakukan. Izin RBAC (Role-Based Access Control) pengguna basis data yang mendasarinya adalah kontrol keamanan yang berwenang.

Misalnya, bahkan jika Anda menonaktifkan upsert_document_by_id dan delete_document_by_id, modifikasi data masih dapat terjadi melalui alat run_sql_plus_plus_query menggunakan pernyataan DML SQL++ (INSERT, UPDATE, DELETE, MERGE) kecuali:

  • CB_MCP_READ_ONLY_MODE diatur ke true (bawaan), ATAU
  • Pengguna basis data tidak memiliki izin RBAC yang diperlukan untuk modifikasi data

Praktik Terbaik: Selalu konfigurasikan izin RBAC yang sesuai pada kredensial pengguna Couchbase Anda sebagai langkah keamanan utama. Gunakan penonaktifan alat sebagai lapisan tambahan untuk memandu perilaku LLM dan mengurangi permukaan serangan, bukan sebagai satu-satunya kontrol keamanan.

Elisitasi/Konfirmasi untuk Panggilan Alat

Anda dapat memerlukan konfirmasi eksplisit pengguna untuk alat tertentu sebelum eksekusi (saat klien MCP mendukung elisitasi).

CB_MCP_CONFIRMATION_REQUIRED_TOOLS / --confirmation-required-tools mendukung format berikut:

  • Daftar yang dipisahkan koma
  • Jalur file (satu nama alat per baris, komentar # didukung)

Contoh:

# 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

Saat alat yang terdaftar dipanggil:

  • Jika klien mendukung elisitasi, pengguna diminta untuk mengonfirmasi.
  • Jika klien tidak mendukung elisitasi, alat dieksekusi tanpa konfirmasi untuk kompatibilitas mundur.

Anda juga dapat memeriksa versi server menggunakan:

uvx couchbase-mcp-server --version

Pencatatan

Server MCP mencatat ke stderr secara bawaan. Pencatatan dikonfigurasi dengan variabel CB_MCP_LOG_* yang tercantum di Konfigurasi Tambahan:

  • CB_MCP_LOG_LEVEL — seberapa banyak yang dicatat: info (bawaan) mencatat peristiwa siklus hidup dan pemanggilan alat, debug menambahkan detail internal yang verbose, dan off menonaktifkan semua pencatatan.
  • CB_MCP_LOG_SINKS — ke mana log pergi: stderr (bawaan), file rotasi per tingkat (file), atau keduanya. Dengan file, satu file ditulis per tingkat (misalnya mcp_server.info.log dan mcp_server.error.log) di jalur yang ditetapkan oleh CB_MCP_LOG_FILE.
  • Ukuran rotasiCB_MCP_LOG_ROTATION_MAX_SIZE_MB adalah ukuran global (dalam MB) saat setiap file per tingkat berotasi. Timpa tingkat individu dengan CB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB (ERROR/WARNING/INFO/DEBUG), juga dalam MB, yang mewarisi global saat tidak diatur. Ukuran 0 (global atau per tingkat) tidak valid dan kembali ke bawaan (1 MB) dengan peringatan startup. CB_MCP_LOG_MAX_BYTES (byte) tidak digunakan lagi tetapi masih dihormati untuk kompatibilitas mundur; diabaikan saat CB_MCP_LOG_ROTATION_MAX_SIZE_MB juga diatur, dan mencetak peringatan deprecation saat startup.
  • RetensiCB_MCP_LOG_RETENTION_BACKUP_COUNT menetapkan berapa banyak cadangan rotasi yang disimpan per tingkat (tidak termasuk file aktif); bawaan 1 mempertahankan perilaku sebelumnya. Timpa tingkat individu dengan CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG), yang mewarisi nilai global saat tidak diatur. Atur jumlah ke 0 untuk hanya menyimpan file aktif untuk tingkat tersebut — masih dibatasi oleh ukuran rotasi (direset saat rollover daripada dicadangkan).
  • Snapshot konfigurasi server — saat sink file aktif, rekaman satu kali (OS, Python, versi dependensi, transport, konfigurasi logging yang diselesaikan, dan konfigurasi server yang disunting) ditulis sebagai JSON ke file mcp_server_config.log.json khusus (diturunkan dari basis CB_MCP_LOG_FILE). File ini ditimpa setiap kali mulai, sehingga dukungan selalu memiliki konfigurasi saat ini dan tidak pernah terlewati dari log rotasi.
# 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

Untuk detail lebih lanjut, lihat dokumentasi.

Konfigurasi Khusus Klien

Claude Desktop

Ikuti langkah-langkah di bawah ini untuk menggunakan server MCP Couchbase dengan klien MCP Claude Desktop

  1. Server MCP sekarang dapat ditambahkan ke Claude Desktop dengan mengedit file konfigurasi. Instruksi lebih detail dapat ditemukan di panduan memulai cepat MCP.

    • Di Mac, file konfigurasi terletak di ~/Library/Application Support/Claude/claude_desktop_config.json
    • Di Windows, file konfigurasi terletak di %APPDATA%\Claude\claude_desktop_config.json Buka file konfigurasi dan tambahkan konfigurasi ke bagian mcpServers.
  2. Mulai ulang Claude Desktop untuk menerapkan perubahan.

  3. Anda kini dapat menggunakan server di Claude Desktop untuk menjalankan kueri pada klaster Couchbase menggunakan bahasa alami dan melakukan operasi CRUD pada dokumen.

Log

Log untuk Claude Desktop dapat ditemukan di lokasi berikut:

  • MacOS: ~/Library/Logs/Claude
  • Windows: %APPDATA%\Claude\Logs

Log dapat digunakan untuk mendiagnosis masalah koneksi atau masalah lain dengan konfigurasi server MCP Anda. Untuk detail lebih lanjut, lihat dokumentasi resmi.

Cursor

Ikuti langkah-langkah berikut untuk menggunakan server MCP Couchbase dengan Cursor:

  1. Instal Cursor di mesin Anda.

  2. Di Cursor, buka Cursor > Cursor Settings > Tools & Integrations > MCP Tools. Selain itu, periksa dokumentasi tentang pengaturan konfigurasi server MCP dari Cursor.

  3. Tentukan konfigurasi yang sama secara manual, atau gunakan tautan Instal di Cursor sekali klik. Anda mungkin perlu menambahkan konfigurasi server di bawah kunci induk mcpServers.

    Catatan: Tautan instalasi menggunakan nilai placeholder dari contoh konfigurasi di atas. Perbarui string koneksi dan kredensial setelah instalasi.

  4. Simpan konfigurasi.

  5. Anda akan melihat couchbase sebagai server yang ditambahkan dalam daftar server MCP. Muat ulang untuk melihat apakah server telah diaktifkan.

  6. Anda kini dapat menggunakan server MCP Couchbase di Cursor untuk mengkueri klaster Couchbase Anda menggunakan bahasa alami dan melakukan operasi CRUD pada dokumen.

Untuk detail lebih lanjut tentang integrasi MCP dengan Cursor, lihat dokumentasi MCP Cursor resmi.

Log

Di panel bawah Cursor, klik "Output" dan pilih "Cursor MCP" dari menu dropdown untuk melihat log server. Ini dapat membantu mendiagnosis masalah koneksi atau masalah lain dengan konfigurasi server MCP Anda.

Windsurf Editor

Ikuti langkah-langkah berikut untuk menggunakan server MCP Couchbase dengan Windsurf Editor.

  1. Instal Windsurf Editor di mesin Anda.

  2. Di Windsurf Editor, navigasikan ke Command Palette > Windsurf MCP Configuration Panel atau Windsurf - Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers. Untuk detail lebih lanjut tentang konfigurasi, lihat dokumentasi resmi.

  3. Klik Add Server lalu Add custom server. Pada konfigurasi yang terbuka di editor, tambahkan konfigurasi Server MCP Couchbase dari atas.

  4. Simpan konfigurasi.

  5. Anda akan melihat couchbase sebagai server yang ditambahkan dalam daftar MCP Servers di bawah Advanced Settings. Muat ulang untuk melihat apakah server telah diaktifkan.

  6. Anda kini dapat menggunakan server MCP Couchbase di Windsurf Editor untuk mengkueri klaster Couchbase Anda menggunakan bahasa alami dan melakukan operasi CRUD pada dokumen.

Untuk detail lebih lanjut tentang integrasi MCP dengan Windsurf Editor, lihat dokumentasi MCP Windsurf resmi.

VS Code

Ikuti langkah-langkah berikut untuk menggunakan server MCP Couchbase dengan VS Code.

  1. Instal VS Code

  2. Berikut adalah beberapa cara untuk mengonfigurasi server MCP.

    • Untuk konfigurasi server Workspace

      • Buat file baru di workspace sebagai .vscode/mcp.json.
      • Tambahkan konfigurasi dan simpan file.
    • Untuk konfigurasi server Global:

      • Jalankan MCP: Open User Configuration di Command Palette (Ctrl+Shift+P atau Cmd+Shift+P)
      • Tambahkan konfigurasi dan simpan file.
    • Catatan: VS Code menggunakan servers sebagai properti JSON tingkat atas dalam file mcp.json untuk mendefinisikan server MCP (Model Context Protocol), sedangkan Cursor menggunakan mcpServers untuk konfigurasi yang setara. Periksa konfigurasi klien VS Code untuk perubahan atau detail lebih lanjut. Contoh konfigurasi VS Code disediakan di bawah.

        {
          "servers": {
            "couchbase": {
              "command": "uvx",
              "args": ["couchbase-mcp-server"],
              "env": {
                "CB_CONNECTION_STRING": "couchbases://connection-string",
                "CB_USERNAME": "username",
                "CB_PASSWORD": "password"
              }
            }
          }
        }
      
  3. Setelah Anda menyimpan file, server akan dimulai dan daftar tindakan kecil muncul dengan Running|Stop|n Tools|More...

  4. Klik opsi dari daftar opsi untuk Start/Stop/mengelola server.

  5. Anda kini dapat menggunakan server MCP Couchbase di VS Code untuk mengkueri klaster Couchbase Anda menggunakan bahasa alami dan melakukan operasi CRUD pada dokumen.

Log: Di Command Palette (Ctrl+Shift+P atau Cmd+Shift+P),

  • jalankan perintah MCP: List Servers dan pilih server couchbase
  • pilih "Show Output" untuk melihat lognya di tab Output.
IDE JetBrains

Ikuti langkah-langkah berikut untuk menggunakan server MCP Couchbase dengan IDE JetBrains

  1. Instal salah satu IDE JetBrains
  2. Instal salah satu plugin JetBrains - AI Assistant atau Junie
  3. Navigasikan ke Settings > Tools > AI Assistant atau Junie > MCP Server
  4. Klik "+" untuk menambahkan konfigurasi MCP Couchbase dan klik Save.
  5. Anda akan melihat server MCP Couchbase ditambahkan ke daftar server. Setelah Anda mengklik Apply, server MCP Couchbase dimulai dan saat kursor diarahkan ke status, semua alat yang tersedia akan ditampilkan.
  6. Anda kini dapat menggunakan server MCP Couchbase di IDE JetBrains untuk mengkueri klaster Couchbase Anda menggunakan bahasa alami dan melakukan operasi CRUD pada dokumen.

Log: File log dapat dijelajahi di Help > Show Log in Finder (Explorer) > mcp > couchbase

Mode Transport Streamable HTTP

Server MCP dapat dijalankan dalam mode transport Streamable HTTP yang memungkinkan beberapa klien terhubung ke instance server yang sama melalui HTTP. Periksa apakah klien MCP Anda mendukung transport streamable http sebelum mencoba terhubung ke server MCP dalam mode ini.

Catatan: Otorisasi OAuth 2.1 didukung pada transport ini. Lihat Otorisasi OAuth 2.1. Tanpa OAuth yang dikonfigurasi, titik akhir HTTP tidak diautentikasi.

Penggunaan

Secara default, server MCP akan berjalan pada port 8000 tetapi ini dapat dikonfigurasi menggunakan variabel lingkungan --port atau CB_MCP_PORT.

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

Server akan tersedia di http://localhost:8000/mcp. Ini dapat digunakan di klien MCP yang mendukung mode transport streamable http seperti Cursor.

Konfigurasi Klien MCP

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

Mode Transport SSE

Ada opsi untuk menjalankan server MCP dalam mode transport Server-Sent Events (SSE).

Catatan: Mode SSE telah tidak digunakan lagi oleh MCP. Kami mendukung Streamable HTTP.

SSE: Penggunaan

Secara default, server MCP akan berjalan pada port 8000 tetapi ini dapat dikonfigurasi menggunakan variabel lingkungan --port atau CB_MCP_PORT.

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

Server akan tersedia di http://localhost:8000/sse. Ini dapat digunakan di klien MCP yang mendukung mode transport SSE seperti Cursor.

SSE: Konfigurasi Klien MCP

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

Otorisasi OAuth 2.1

Saat dijalankan dengan --transport=http, server MCP dapat bertindak sebagai server sumber daya OAuth 2.1: server memvalidasi bearer JWT yang masuk terhadap JWKS penyedia identitas Anda. Server ini tidak bergantung pada penyedia (penyedia OAuth 2.1 / OIDC apa pun yang menerbitkan JWKS — Auth0, Okta, Keycloak, AWS Cognito, Microsoft Entra, dll.) dan tidak menerbitkan token atau mengelola pengguna. Pengaturan OAuth diabaikan pada stdio.

OAuth dikonfigurasi dengan variabel CB_MCP_OAUTH_* yang tercantum di Konfigurasi Tambahan:

  • OAuth aktif hanya jika ketiganya CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER, dan CB_MCP_OAUTH_JWT_AUDIENCE ditetapkan; menetapkan hanya sebagian akan menyebabkan kegagalan saat startup.
  • Menetapkan CB_MCP_OAUTH_MCP_BASE_URL juga menerbitkan Metadata Sumber Daya Terlindungi RFC 9728 sehingga klien yang mendukung PRM dapat menemukan server otorisasi.
  • Akses dibatasi oleh dua cakupan yang dibaca dari klaim scope/scp token: couchbase-mcp:read (alat baca, termasuk SQL++) dan couchbase-mcp:write (alat tulis: mutasi KV, manajemen cakupan/koleksi, dan manajemen indeks). Akses penuh memerlukan keduanya. Jika IdP Anda tidak dapat mengeluarkan label kanonis tersebut, timpa dengan CB_MCP_OAUTH_SCOPE_READ_LABEL / CB_MCP_OAUTH_SCOPE_WRITE_LABEL.
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>'

Untuk detail lengkap, lihat dokumentasi.

Gambar Docker

Server MCP juga dapat dibangun dan dijalankan sebagai kontainer Docker. Gambar yang telah dibuat sebelumnya dapat ditemukan di DockerHub atau diambil melalui docker pull docker.io/couchbase/mcp-server:latest.

Atau, kami adalah bagian dari Katalog MCP Docker.

Membangun Gambar

docker build -t mcp/couchbase-src .
Membangun dengan Argumen Jika Anda ingin membangun dengan argumen build untuk hash commit dan waktu build, Anda dapat membangun menggunakan:
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 .

Atau, gunakan skrip build yang disediakan:

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

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

Skrip ini secara otomatis:

  • Menerima parameter nama gambar opsional (default ke mcp/couchbase-src)
  • Menghasilkan hash commit git dan stempel waktu build
  • Membuat beberapa tag yang berguna (latest, <short-commit>)
  • Menampilkan informasi build dan hasil
  • Menggunakan argumen yang sama dengan build CI/CD

Verifikasi label gambar:

# 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

Menjalankan

Server MCP dapat dijalankan dengan variabel lingkungan yang digunakan untuk mengonfigurasi pengaturan Couchbase. Variabel lingkungan sama seperti yang dijelaskan di bagian Konfigurasi Tambahan.

Kontainer Docker Mandiri

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

Variabel lingkungan CB_MCP_PORT dan CB_MCP_HOST hanya berlaku dalam kasus mode transport HTTP seperti http dan sse.

Docker: Konfigurasi Klien MCP

Gambar Docker dapat digunakan dalam mode transport stdio dengan konfigurasi berikut.

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

Catatan

  • Nilai couchbase_connection_string bergantung pada apakah server Couchbase berjalan di mesin host yang sama, di kontainer Docker lain, atau di host jarak jauh. Jika server Couchbase Anda berjalan di mesin host Anda, string koneksi Anda kemungkinan akan berbentuk couchbase://host.docker.internal. Untuk detailnya, lihat dokumentasi docker.
  • Anda dapat menentukan jaringan kontainer menggunakan opsi --network=<your_network>. Jaringan yang Anda pilih bergantung pada lingkungan Anda; defaultnya adalah bridge. Untuk detailnya, lihat driver jaringan di docker.

Risiko Terkait dengan LLM

  • Penggunaan model bahasa besar dan teknologi serupa melibatkan risiko, termasuk potensi keluaran yang tidak akurat atau berbahaya.
  • Couchbase tidak meninjau atau mengevaluasi kualitas atau keakuratan keluaran tersebut, dan keluaran tersebut mungkin tidak mencerminkan pandangan Couchbase.
  • Anda sepenuhnya bertanggung jawab untuk menentukan apakah akan menggunakan model bahasa besar dan teknologi terkait, serta untuk mematuhi semua ketentuan lisensi, ketentuan penggunaan, dan kebijakan organisasi Anda yang mengatur penggunaan tersebut.

Pengumpulan Data Penggunaan

Produk ini secara otomatis mengumpulkan data penggunaan dan kinerja (seperti nama produk dan versi) serta informasi browser (seperti alamat IP) (secara kolektif, "Data Penggunaan"). Couchbase menggunakan Data Penggunaan, bersama dengan data lain yang mungkin Anda berikan kepada Couchbase (seperti nama pengguna atau alamat email Anda), untuk mengembangkan dan meningkatkan produk kami serta menginformasikan program penjualan dan pemasaran kami. Kami tidak mengakses atau mengumpulkan data apa pun yang Anda simpan di produk Couchbase. Kami menggunakan Data Penggunaan untuk memahami pola penggunaan agregat dan membuat produk kami lebih berguna bagi Anda. Untuk informasi lebih lanjut tentang bagaimana Couchbase mengumpulkan, melindungi, dan memproses informasi, silakan merujuk ke Kebijakan Privasi Couchbase yang dapat dilihat di https://www.couchbase.com/privacy-policy.

Tips Pemecahan Masalah

  • Pastikan jalur ke repositori server MCP Anda sudah benar pada konfigurasi jika dijalankan dari sumber.
  • Verifikasi bahwa string koneksi Couchbase, nama pengguna database, kata sandi, atau jalur ke sertifikat sudah benar.
  • Jika menggunakan Couchbase Capella, pastikan cluster dapat diakses dari mesin tempat server MCP berjalan.
  • Periksa bahwa pengguna database memiliki izin yang sesuai untuk mengakses setidaknya satu bucket.
  • Konfirmasikan bahwa manajer paket uv sudah terpasang dengan benar dan dapat diakses. Anda mungkin perlu memberikan jalur absolut ke uv/uvx pada kolom command di konfigurasi.
  • Periksa log untuk mengetahui adanya kesalahan atau peringatan yang dapat mengindikasikan masalah pada server MCP. Lokasi log bergantung pada klien MCP Anda.
  • Jika Anda mengalami masalah saat menjalankan server MCP dari sumber setelah memperbarui repositori server MCP lokal, coba jalankan uv sync untuk memperbarui dependensi.

Pengujian integrasi

Kami menyediakan pengujian integrasi MCP tingkat tinggi untuk memverifikasi bahwa server mengekspos alat-alat yang diharapkan dan bahwa alat-alat tersebut dapat dipanggil terhadap cluster Couchbase demo.

  1. Ekspor kredensial cluster demo:
    • CB_CONNECTION_STRING
    • CB_USERNAME
    • CB_PASSWORD
    • Opsional: CB_MCP_TEST_BUCKET (bucket untuk diuji selama pengujian)
  2. Jalankan pengujian:
uv run pytest tests/ -v

👩‍💻 Berkontribusi

Kami menyambut kontribusi dari komunitas! Baik Anda ingin memperbaiki bug, menambahkan fitur, atau meningkatkan dokumentasi, bantuan Anda sangat dihargai.

Jika Anda memerlukan bantuan, menemukan bug, atau ingin memberikan kontribusi perbaikan, tempat terbaik untuk melakukannya adalah di sini — dengan membuka issue GitHub.

Untuk Pengembang

Jika Anda tertarik untuk berkontribusi kode atau menyiapkan lingkungan pengembangan:

📖 Lihat CONTRIBUTING.md untuk petunjuk lengkap pengaturan pengembang, termasuk:

  • Pengaturan lingkungan pengembangan dengan uv
  • Linting dan pemformatan kode dengan Ruff
  • Pemasangan pre-commit hooks
  • Ringkasan struktur proyek
  • Alur kerja dan praktik pengembangan

Mulai Cepat untuk Kontributor

# 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

📢 Kebijakan Dukungan

Kami sangat menghargai minat Anda pada proyek ini! Proyek ini dipelihara oleh komunitas Couchbase, yang berarti tidak didukung secara resmi oleh tim dukungan kami. Namun, para insinyur kami secara aktif memantau dan memelihara repositori ini dan akan berusaha menyelesaikan masalah dengan upaya terbaik.

Portal dukungan kami tidak dapat membantu dengan permintaan yang terkait dengan proyek ini, jadi kami mohon agar semua pertanyaan tetap berada di dalam GitHub.

Kolaborasi Anda membantu kita semua maju bersama — terima kasih!