Couchbase
resmiBerinteraksi 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_clusterdanget_schema_for_collection. - Kelola dokumen — Baca, upsert, atau hapus dokumen berdasarkan ID dengan
get_document_by_iddanupsert_document_by_id. - Periksa kesehatan cluster — Verifikasi konektivitas dan status layanan dengan
test_cluster_connectiondanget_cluster_health_and_services. - Optimalkan indeks — Daftarkan indeks dan dapatkan rekomendasi melalui
list_indexesdanget_index_advisor_recommendations. - Analisis performa kueri — Temukan kueri yang lambat atau tidak selektif dengan
get_longest_running_queriesdanget_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.
Untuk dokumentasi lengkap, kunjungi mcp-server.couchbase.com.
Fitur/Alat
Alat pengaturan & kesehatan kluster
| Nama Alat | Deskripsi |
|---|---|
get_server_configuration_status | Dapatkan 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_connection | Periksa kredensial kluster dengan terhubung ke kluster |
get_cluster_health_and_services | Dapatkan status kesehatan kluster dan daftar semua layanan yang berjalan |
Alat penemuan model data & skema
| Nama Alat | Deskripsi |
|---|---|
get_buckets_in_cluster | Dapatkan daftar semua bucket di kluster |
get_scopes_in_bucket | Dapatkan daftar semua scope di bucket yang ditentukan |
get_collections_in_scope | Dapatkan daftar semua koleksi di scope dan bucket yang ditentukan. Perhatikan bahwa alat ini memerlukan kluster untuk memiliki layanan Query. |
get_scopes_and_collections_in_bucket | Dapatkan daftar semua scope dan koleksi di bucket yang ditentukan |
get_schema_for_collection | Dapatkan struktur untuk sebuah koleksi |
create_scope | Buat scope baru di bucket (Couchbase Server 7.6+ dan Capella). Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
create_collection | Buat koleksi baru di scope yang sudah ada (Couchbase Server 7.6+ dan Capella). Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
delete_scope | Hapus scope dan semua koleksinya dari bucket — permanen. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
delete_collection | Hapus koleksi dan semua dokumennya dari scope — permanen. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
Alat operasi KV dokumen
| Nama Alat | Deskripsi |
|---|---|
get_document_by_id | Dapatkan dokumen berdasarkan ID dari scope dan koleksi yang ditentukan |
lookup_subdocument | Cari bagian-bagian dokumen (bidang tertentu, pemeriksaan keberadaan, atau jumlah array/objek) berdasarkan jalur tanpa mengambil seluruh dokumen |
upsert_document_by_id | Upsert dokumen berdasarkan ID ke scope dan koleksi yang ditentukan. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
insert_document_by_id | Sisipkan dokumen baru berdasarkan ID (gagal jika dokumen sudah ada). Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
replace_document_by_id | Ganti dokumen yang ada berdasarkan ID (gagal jika dokumen tidak ada). Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
delete_document_by_id | Hapus dokumen berdasarkan ID dari scope dan koleksi yang ditentukan. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
mutate_subdocument | Ubah 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 Alat | Deskripsi |
|---|---|
list_indexes | Daftarkan 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_recommendations | Dapatkan rekomendasi indeks dari Couchbase Index Advisor untuk kueri SQL++ tertentu untuk mengoptimalkan performa kueri |
create_index | Buat 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_index | Picu pembangunan semua indeks yang ditunda pada koleksi. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
drop_index | Hapus indeks GSI (skalar atau vektor) dari koleksi. Dinonaktifkan secara default saat CB_MCP_READ_ONLY_MODE=true. |
run_sql_plus_plus_query | Jalankan 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_query | Buat dan evaluasi rencana EXPLAIN untuk kueri SQL++. Mengembalikan metadata kueri, rencana yang diekstrak, dan temuan evaluasi rencana. |
Alat analisis performa kueri
| Nama Alat | Deskripsi |
|---|---|
get_longest_running_queries | Dapatkan kueri yang berjalan paling lama berdasarkan waktu layanan rata-rata |
get_most_frequent_queries | Dapatkan kueri yang paling sering dijalankan |
get_queries_with_largest_response_sizes | Dapatkan kueri dengan ukuran respons terbesar |
get_queries_with_large_result_count | Dapatkan kueri dengan jumlah hasil terbesar |
get_queries_using_primary_index | Dapatkan kueri yang menggunakan indeks primer (potensi masalah performa) |
get_queries_not_using_covering_index | Dapatkan kueri yang tidak menggunakan covering index |
get_queries_not_selective | Dapatkan 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
mcpServersyang 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
mcpServersyang sudah ada.
Konfigurasi Tambahan untuk Server MCP
Server dapat dikonfigurasi menggunakan variabel lingkungan atau argumen baris perintah:
| Variabel Lingkungan | Argumen CLI | Deskripsi | Bawaan |
|---|---|---|---|
CB_CONNECTION_STRING | --connection-string | String koneksi ke cluster Couchbase | Diperlukan |
CB_USERNAME | --username | Nama pengguna dengan akses ke bucket yang diperlukan untuk autentikasi dasar | Diperlukan (atau Sertifikat Klien dan Kunci diperlukan untuk mTLS) |
CB_PASSWORD | --password | Kata sandi untuk autentikasi dasar | Diperlukan (atau Sertifikat Klien dan Kunci diperlukan untuk mTLS) |
CB_CLIENT_CERT_PATH | --client-cert-path | Jalur ke file sertifikat klien untuk autentikasi mTLS | Diperlukan jika menggunakan mTLS (atau Nama Pengguna dan Kata Sandi diperlukan) |
CB_CLIENT_KEY_PATH | --client-key-path | Jalur ke file kunci klien untuk autentikasi mTLS | Diperlukan jika menggunakan mTLS (atau Nama Pengguna dan Kata Sandi diperlukan) |
CB_CA_CERT_PATH | --ca-cert-path | Jalur 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-mode | Mencegah 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 | --transport | Mode transport: stdio, http, sse | stdio |
CB_MCP_HOST | --host | Host untuk mode transport HTTP/SSE | 127.0.0.1 |
CB_MCP_PORT | --port | Port untuk mode transport HTTP/SSE | 8000 |
CB_MCP_DISABLED_TOOLS | --disabled-tools | Alat untuk dinonaktifkan (lihat Menonaktifkan Alat) | Tidak ada |
CB_MCP_CONFIRMATION_REQUIRED_TOOLS | --confirmation-required-tools | Alat yang memerlukan konfirmasi eksplisit pengguna sebelum eksekusi melalui elisitasi MCP (lihat Alat yang Memerlukan Elisitasi/Konfirmasi) | Tidak ada |
CB_MCP_LOG_LEVEL | --log-level | Tingkat pencatatan untuk server MCP: off, debug, info, warning, error (lihat Pencatatan) | info |
CB_MCP_LOG_SINKS | --log-sinks | Tujuan log yang dipisahkan koma: stderr, file, atau keduanya (lihat Pencatatan) | stderr |
CB_MCP_LOG_FILE | --log-file | Jalur 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-mb | Ukuran 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 startup | 1 (1 MB) |
CB_MCP_LOG_MAX_BYTES | --log-max-bytes | Tidak 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 diatur | Tidak diatur |
CB_MCP_LOG_ERROR_ROTATION_MAX_SIZE_MB | --log-error-rotation-max-size-mb | Ukuran rotasi dalam MB untuk file log ERROR; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk ERROR | Mewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_WARNING_ROTATION_MAX_SIZE_MB | --log-warning-rotation-max-size-mb | Ukuran rotasi dalam MB untuk file log WARNING; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk WARNING | Mewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_INFO_ROTATION_MAX_SIZE_MB | --log-info-rotation-max-size-mb | Ukuran rotasi dalam MB untuk file log INFO; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk INFO | Mewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_DEBUG_ROTATION_MAX_SIZE_MB | --log-debug-rotation-max-size-mb | Ukuran rotasi dalam MB untuk file log DEBUG; menimpa CB_MCP_LOG_ROTATION_MAX_SIZE_MB untuk DEBUG | Mewarisi CB_MCP_LOG_ROTATION_MAX_SIZE_MB |
CB_MCP_LOG_RETENTION_BACKUP_COUNT | --log-retention-backup-count | File 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-count | Cadangan rotasi yang disimpan untuk file log ERROR; menimpa jumlah global untuk ERROR | Mewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_WARNING_RETENTION_BACKUP_COUNT | --log-warning-retention-backup-count | Cadangan rotasi yang disimpan untuk file log WARNING; menimpa jumlah global untuk WARNING | Mewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_INFO_RETENTION_BACKUP_COUNT | --log-info-retention-backup-count | Cadangan rotasi yang disimpan untuk file log INFO; menimpa jumlah global untuk INFO | Mewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_LOG_DEBUG_RETENTION_BACKUP_COUNT | --log-debug-retention-backup-count | Cadangan rotasi yang disimpan untuk file log DEBUG; menimpa jumlah global untuk DEBUG | Mewarisi CB_MCP_LOG_RETENTION_BACKUP_COUNT |
CB_MCP_OAUTH_JWT_JWKS_URI | --oauth-jwks-uri | Endpoint 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-issuer | Klaim iss JWT yang diharapkan. Diperlukan untuk mengaktifkan OAuth | Tidak ada |
CB_MCP_OAUTH_JWT_AUDIENCE | --oauth-audience | Klaim aud JWT yang diharapkan. Diperlukan untuk mengaktifkan OAuth | Tidak ada |
CB_MCP_OAUTH_JWT_ALGORITHM | --oauth-algorithm | Algoritma penandatanganan JWT: salah satu dari RS256/384/512, ES256/384/512, PS256/384/512 | RS256 |
CB_MCP_OAUTH_MCP_BASE_URL | --oauth-mcp-base-url | URL dasar publik dari server ini. Saat diatur, menerbitkan Metadata Sumber Daya yang Dilindungi RFC 9728 sehingga klien yang sadar PRM dapat menemukan IdP | Tidak ada |
CB_MCP_OAUTH_SCOPE_READ_LABEL | --oauth-scope-read-label | Timpa 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 kanonik | couchbase-mcp:read |
CB_MCP_OAUTH_SCOPE_WRITE_LABEL | --oauth-scope-write-label | Timpa label lingkup OAuth yang diperlakukan sebagai akses 'tulis'; semantik yang sama dengan label baca | couchbase-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_iddandelete_document_by_id, modifikasi data masih dapat terjadi melalui alatrun_sql_plus_plus_querymenggunakan pernyataan DML SQL++ (INSERT, UPDATE, DELETE, MERGE) kecuali:
CB_MCP_READ_ONLY_MODEdiatur ketrue(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,debugmenambahkan detail internal yang verbose, danoffmenonaktifkan semua pencatatan.CB_MCP_LOG_SINKS— ke mana log pergi:stderr(bawaan), file rotasi per tingkat (file), atau keduanya. Denganfile, satu file ditulis per tingkat (misalnyamcp_server.info.logdanmcp_server.error.log) di jalur yang ditetapkan olehCB_MCP_LOG_FILE.- Ukuran rotasi —
CB_MCP_LOG_ROTATION_MAX_SIZE_MBadalah ukuran global (dalam MB) saat setiap file per tingkat berotasi. Timpa tingkat individu denganCB_MCP_LOG_<LEVEL>_ROTATION_MAX_SIZE_MB(ERROR/WARNING/INFO/DEBUG), juga dalam MB, yang mewarisi global saat tidak diatur. Ukuran0(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 saatCB_MCP_LOG_ROTATION_MAX_SIZE_MBjuga diatur, dan mencetak peringatan deprecation saat startup. - Retensi —
CB_MCP_LOG_RETENTION_BACKUP_COUNTmenetapkan berapa banyak cadangan rotasi yang disimpan per tingkat (tidak termasuk file aktif); bawaan1mempertahankan perilaku sebelumnya. Timpa tingkat individu denganCB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT(ERROR/WARNING/INFO/DEBUG), yang mewarisi nilai global saat tidak diatur. Atur jumlah ke0untuk hanya menyimpan file aktif untuk tingkat tersebut — masih dibatasi oleh ukuran rotasi (direset saat rollover daripada dicadangkan). - Snapshot konfigurasi server — saat sink
fileaktif, rekaman satu kali (OS, Python, versi dependensi, transport, konfigurasi logging yang diselesaikan, dan konfigurasi server yang disunting) ditulis sebagai JSON ke filemcp_server_config.log.jsonkhusus (diturunkan dari basisCB_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
-
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.jsonBuka file konfigurasi dan tambahkan konfigurasi ke bagianmcpServers.
- Di Mac, file konfigurasi terletak di
-
Mulai ulang Claude Desktop untuk menerapkan perubahan.
-
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:
-
Instal Cursor di mesin Anda.
-
Di Cursor, buka Cursor > Cursor Settings > Tools & Integrations > MCP Tools. Selain itu, periksa dokumentasi tentang pengaturan konfigurasi server MCP dari Cursor.
-
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.
-
Simpan konfigurasi.
-
Anda akan melihat couchbase sebagai server yang ditambahkan dalam daftar server MCP. Muat ulang untuk melihat apakah server telah diaktifkan.
-
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.
-
Instal Windsurf Editor di mesin Anda.
-
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.
-
Klik Add Server lalu Add custom server. Pada konfigurasi yang terbuka di editor, tambahkan konfigurasi Server MCP Couchbase dari atas.
-
Simpan konfigurasi.
-
Anda akan melihat couchbase sebagai server yang ditambahkan dalam daftar MCP Servers di bawah Advanced Settings. Muat ulang untuk melihat apakah server telah diaktifkan.
-
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.
-
Instal VS Code
-
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+PatauCmd+Shift+P) - Tambahkan konfigurasi dan simpan file.
- Jalankan MCP: Open User Configuration di Command Palette (
-
Catatan: VS Code menggunakan
serverssebagai properti JSON tingkat atas dalam file mcp.json untuk mendefinisikan server MCP (Model Context Protocol), sedangkan Cursor menggunakanmcpServersuntuk 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" } } } }
-
-
Setelah Anda menyimpan file, server akan dimulai dan daftar tindakan kecil muncul dengan
Running|Stop|n Tools|More... -
Klik opsi dari daftar opsi untuk
Start/Stop/mengelola server. -
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
- Instal salah satu IDE JetBrains
- Instal salah satu plugin JetBrains - AI Assistant atau Junie
- Navigasikan ke Settings > Tools > AI Assistant atau Junie > MCP Server
- Klik "+" untuk menambahkan konfigurasi MCP Couchbase dan klik Save.
- 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.
- 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, danCB_MCP_OAUTH_JWT_AUDIENCEditetapkan; menetapkan hanya sebagian akan menyebabkan kegagalan saat startup. - Menetapkan
CB_MCP_OAUTH_MCP_BASE_URLjuga 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/scptoken:couchbase-mcp:read(alat baca, termasuk SQL++) dancouchbase-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 denganCB_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_stringbergantung 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 berbentukcouchbase://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 adalahbridge. 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
uvsudah terpasang dengan benar dan dapat diakses. Anda mungkin perlu memberikan jalur absolut keuv/uvxpada kolomcommanddi 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 syncuntuk 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.
- Ekspor kredensial cluster demo:
CB_CONNECTION_STRINGCB_USERNAMECB_PASSWORD- Opsional:
CB_MCP_TEST_BUCKET(bucket untuk diuji selama pengujian)
- 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!