Couchbase

Server MCP Couchbase

Server MCP Couchbase adalah server Model Context Protocol (MCP) yang di-hosting sendiri yang menghubungkan agen AI dan asisten bertenaga LLM — Claude, Cursor, Windsurf, VS Code Copilot, dan klien MCP lainnya — ke data di klaster Couchbase, baik yang di-hosting di Capella maupun yang dikelola sendiri. MCP adalah standar terbuka untuk memungkinkan asisten AI memanggil alat dan mengakses sumber data eksternal; server ini mengimplementasikan standar tersebut untuk Couchbase, sehingga agen AI dapat memeriksa klaster Anda, menjalankan kueri SQL++, membaca dan menulis dokumen, serta menganalisis performa kueri menggunakan bahasa alami alih-alih kode yang ditulis manual.

Server ini menyediakan alat di berbagai kategori termasuk Kesehatan Klaster, Skema Data, Key-Value, Kueri, dan Performa — dengan kontrol keamanan melalui mode baca-saja (aktif secara default) dan penonaktifan alat secara terperinci, sehingga Anda dapat membiarkan agen AI menjelajahi dan mengkueri data Anda tanpa risiko penulisan yang tidak disengaja. Server ini mendukung transport STDIO dan Streamable HTTP.

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

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

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

Daftar Isi

• Mengapa Server MCP Couchbase
• Contoh Prompt
• Fitur/Alat
• Prasyarat
• Konfigurasi
• Server Operational Insights
• Mode Transport Streamable HTTP
• Mode Transport SSE
• Otorisasi OAuth 2.1
• Citra Docker
• Pengumpulan Data Penggunaan
• Tips Pemecahan Masalah
• Pengujian Integrasi
• FAQ
• Kontribusi
• Kebijakan Dukungan

Mengapa Server MCP Couchbase

• Aman secara default — operasi penulisan (upsert/insert/delete dokumen dan kueri SQL++ yang memodifikasi data) diblokir kecuali Anda secara eksplisit mengatur CB_MCP_READ_ONLY_MODE=false, dan alat individual dapat dinonaktifkan atau dibatasi di belakang konfirmasi pengguna.
• Berfungsi dengan klaster Capella dan yang dikelola sendiri — konfigurasi yang sama terhubung ke Couchbase Capella (dikelola penuh) atau klaster Couchbase Server yang di-hosting sendiri.
• Sadar RBAC — penonaktifan alat adalah lapisan kenyamanan untuk memandu perilaku LLM; kontrol akses berbasis peran pengguna Couchbase yang mendasarinya tetap menjadi batas keamanan yang otoritatif.
• Transport produksi — jalankan melalui STDIO untuk klien desktop lokal, atau Streamable HTTP dengan OAuth 2.1 opsional (JWT/JWKS, agnostik penyedia — Auth0, Okta, Keycloak, Entra, Cognito, dll.) untuk deployment bersama/jarak jauh.
• Klien MCP apa pun — diuji dengan Claude Desktop, Cursor, Windsurf, VS Code, dan JetBrains AI Assistant/Junie; berfungsi dengan klien apa pun yang mengimplementasikan spesifikasi MCP.

Contoh Prompt

Setelah server terhubung, Anda dapat berbicara dengan klaster Couchbase Anda dalam bahasa alami melalui asisten AI Anda. Misalnya:

• "Bucket, scope, dan koleksi apa yang saya miliki di klaster ini, dan apa skema dari koleksi orders?"
• "Jalankan kueri SQL++ untuk menemukan 10 dokumen terbaru di koleksi users where status = 'active'."
• "Apa 5 kueri paling lambat di klaster ini dalam satu jam terakhir, dan apakah ada yang kekurangan covering index?"
• "Periksa apakah klaster ini sehat dan beri tahu saya layanan mana yang berjalan."
• "Sisipkan dokumen baru ke koleksi products dengan kolom berikut: ..." (memerlukan CB_MCP_READ_ONLY_MODE=false)

Fitur/Alat

Distribusi ini mengirimkan dua server: server operasional (default — tabel tepat di bawah) berbicara ke klaster Couchbase biasa melalui SDK couchbase, dan server Operational Insights (tabelnya sendiri di bawah) berbicara ke klaster Operational Insights melalui SDK couchbase-operational-insights.

Alat penyiapan & kesehatan klaster

Alat penemuan model data & skema

Alat operasi dokumen KV

Alat kueri dan pengindeksan

Alat pencarian teks lengkap (FTS)

Memerlukan Couchbase Server 7.6+ dan layanan Search. Pencarian vektor tidak didukung oleh alat-alat ini (lihat alat pencarian vektor terpisah).

Alat analisis performa kueri

Alat Operational Insights

Didaftarkan oleh server operational-insights terpisah (lihat Server Operational Insights di bawah), bukan server operational default.

Alat Server Async Request API membentuk alur mulai → polling → buang-atau-batalkan untuk kueri yang berjalan lama: run_query_async mengembalikan query_handle, get_async_query_results dipolling hingga melaporkan kesiapan (dan mengembalikan baris), lalu baik discard_async_query_results membebaskan hasil atau, untuk kueri yang masih berjalan, cancel_async_query menghentikannya.

Catatan: get_collections_in_scope, get_schema_for_collection, create_index dan list_indexes ada, dengan perilaku berbeda, di kedua server. (get_server_configuration_status juga muncul di keduanya, tetapi sengaja satu alat yang dibagikan — implementasi sama, bentuk hasil sama — sehingga tidak perlu disambiguasi.) Setiap server adalah proses terpisah, jadi ini hanya menjadi perhatian jika satu klien MCP mendaftarkan operational dan operational-insights secara bersamaan — dalam kasus itu, lakukan disambiguasi di lapisan konfigurasi klien (misalnya dengan memberi dua entri server nama yang berbeda di konfigurasi klien itu sendiri).

Prasyarat

• Python 3.10 atau lebih tinggi.
• Cluster 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 dataset sampel atau mengimpor dataset Anda sendiri.
• uv terinstal untuk menjalankan server.
• Klien MCP seperti Claude Desktop terinstal untuk menghubungkan server ke Claude. Instruksi diberikan untuk Claude Desktop dan Cursor. Klien MCP lain juga dapat digunakan.

Konfigurasi

Server MCP dapat dijalankan baik dari paket PyPI yang sudah dibuat atau 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 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 berupa 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 ada.

Konfigurasi Tambahan untuk Server MCP

Server dapat dikonfigurasi menggunakan variabel lingkungan atau argumen baris perintah:

Konfigurasi Mode Hanya-Baca

CB_MCP_READ_ONLY_MODE adalah sakelar tunggal yang mengontrol operasi tulis:

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

Ini adalah default 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 jalur Sertifikat Klien & kunci dan nama pengguna dan kata sandi keduanya 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 (misalnya, disabled_tools.txt):

# Write operations
upsert_document_by_id
delete_document_by_id

# Index advisor
get_index_advisor_recommendations

Baris yang diawali 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 (default), 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.

Elicitation/Konfirmasi untuk Pemanggilan Alat

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

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 elicitation, pengguna akan diminta untuk mengonfirmasi.
• Jika klien tidak mendukung elicitation, alat akan dieksekusi tanpa konfirmasi untuk kompatibilitas mundur.

Anda juga dapat memeriksa versi server menggunakan:

uvx couchbase-mcp-server --version

Pencatatan Log

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

• CB_MCP_LOG_LEVEL — seberapa banyak yang dicatat: info (default) mencatat peristiwa siklus hidup dan pemanggilan alat, debug menambahkan detail internal yang verbose, dan off menonaktifkan semua pencatatan log.
• CB_MCP_LOG_SINKS — ke mana log pergi: stderr (default), file bergilir 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 rotasi — CB_MCP_LOG_ROTATION_MAX_SIZE_MB adalah ukuran global (dalam MB) di mana setiap file per tingkat berputar. Timpa tingkat individual 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 default (1 MB) dengan peringatan saat startup. CB_MCP_LOG_MAX_BYTES (byte) tidak digunakan lagi tetapi masih dihormati untuk kompatibilitas mundur; ini diabaikan saat CB_MCP_LOG_ROTATION_MAX_SIZE_MB juga diatur, dan mencetak peringatan depresiasi saat startup.
• Retensi — CB_MCP_LOG_RETENTION_BACKUP_COUNT menetapkan berapa banyak cadangan yang diputar yang disimpan per tingkat (tidak termasuk file langsung); default 1 mempertahankan perilaku sebelumnya. Timpa tingkat individual dengan CB_MCP_LOG_<LEVEL>_RETENTION_BACKUP_COUNT (ERROR/WARNING/INFO/DEBUG), yang mewarisi nilai global saat tidak diatur. Tetapkan jumlah ke 0 untuk hanya menyimpan file langsung untuk tingkat itu — masih dibatasi oleh ukuran rotasi (diatur ulang saat bergulir daripada dicadangkan).
• Snapshot konfigurasi server — saat sink file aktif, catatan satu kali (OS, Python, versi dependensi, transport, konfigurasi log 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). Ini ditimpa setiap kali dimulai, sehingga dukungan selalu memiliki konfigurasi saat ini dan tidak pernah keluar dari log yang berputar.

# 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

Server Wawasan Operasional

Selain server operational default (yang dijelaskan oleh setiap bagian di atas), distribusi ini menyertakan server kedua untuk cluster Wawasan Operasional, menggunakan couchbase-operational-insights SDK yang terpisah. Ini adalah produk yang berbeda dari cluster Couchbase biasa dan berjalan sebagai proses independen di portnya sendiri.

Jalankan dengan meneruskan operational-insights sebagai subperintah CLI (atau menambahkan sebagai perintah kontainer):

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

--connection-string adalah URL HTTP(S), bukan string koneksi couchbase:// — misalnya http://localhost:8095 untuk server Wawasan Operasional lokal, atau https://<host>:18095 untuk Capella. Ini adalah kesalahan konfigurasi paling umum saat mengarahkan server ini ke cluster.

Setiap flag lainnya (--read-only-mode, --transport, --host, --port, --disabled-tools, --confirmation-required-tools, --log-*, --oauth-*) identik dengan server operasional — lihat Konfigurasi Tambahan untuk MCP Server — kecuali default untuk port (8001, bukan 8000) dan file log (mcp_server_operational_insights.log, bukan mcp_server.log), karena dua server tidak dapat berbagi keduanya. OAuth menggunakan label cakupan yang sama (couchbase-mcp:read / couchbase-mcp:write) dengan server operasional, sehingga konfigurasi IdP yang ada berfungsi untuk keduanya tanpa perubahan.

Contoh konfigurasi klien MCP:

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

Lihat Alat Operational Insights di atas untuk daftar alat, dan catatan di sana tentang tiga nama alat yang dibagikan dengan server operasional.

Kedua server berbagi satu daftar MCP Registry, io.github.couchbase/mcp-server-couchbase, yang diterbitkan dari server.json. Daftar tersebut memiliki entri paket terpisah untuk setiap server (PyPI dan Docker). Setiap entri meneruskan subperintahnya (operational atau operational-insights) dan hanya mendeklarasikan argumen dan variabel lingkungan server tersebut.

Mode Transport HTTP Streamable

MCP Server 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 http streamable sebelum mencoba terhubung ke MCP server dalam mode ini.

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

Penggunaan

Secara default, MCP server 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 http streamable seperti Cursor.

Konfigurasi Klien MCP

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

Mode Transport SSE

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

Catatan: Mode SSE telah ditinggalkan oleh MCP. Kami memiliki dukungan untuk Streamable HTTP.

SSE: Penggunaan

Secara default, MCP server 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, MCP server dapat bertindak sebagai server sumber daya OAuth 2.1: ia memvalidasi JWT bearer yang masuk terhadap JWKS penyedia identitas Anda. Ini agnostik terhadap 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 ketika ketiga CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER, dan CB_MCP_OAUTH_JWT_AUDIENCE disetel; menyetel hanya sebagian akan gagal saat startup.
• Menyetel 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 kanonik 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

MCP server juga dapat dibangun dan dijalankan sebagai kontainer Docker. Gambar yang sudah dibuat sebelumnya dapat ditemukan di DockerHub atau ditarik 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 .

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

Menjalankan

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

Kontainer Docker Independen

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 mematuhi 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 MCP server Anda benar dalam konfigurasi jika dijalankan dari sumber.
• Verifikasi bahwa string koneksi Couchbase, nama pengguna database, kata sandi, atau jalur ke sertifikat Anda sudah benar.
• Jika menggunakan Couchbase Capella, pastikan cluster dapat diakses dari mesin tempat MCP server berjalan.
• Periksa bahwa pengguna database memiliki izin yang tepat untuk mengakses setidaknya satu bucket.
• Konfirmasikan bahwa manajer paket uv terinstal dengan benar dan dapat diakses. Anda mungkin perlu memberikan jalur absolut ke uv/uvx di bidang command dalam konfigurasi.
• Periksa log untuk kesalahan atau peringatan yang mungkin menunjukkan masalah dengan MCP server. Lokasi log bergantung pada klien MCP Anda.
• Jika Anda mengalami masalah menjalankan MCP server dari sumber setelah memperbarui repositori MCP server lokal Anda, coba jalankan uv sync untuk memperbarui dependensi.

Pengujian integrasi

Kami menyediakan pengujian integrasi MCP tingkat tinggi untuk memverifikasi bahwa server mengekspos alat yang diharapkan dan bahwa 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)
   • Opsional, untuk pengujian server Operational Insights sendiri: CB_OI_CONNECTION_STRING / CB_OI_USERNAME / CB_OI_PASSWORD. Pengujian tersebut dilewati secara otomatis (tidak gagal) saat tidak disetel.
2. Jalankan pengujian:

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

FAQ

Apa itu Couchbase MCP Server? Ini adalah implementasi yang dihosting sendiri dari Model Context Protocol yang memungkinkan asisten AI dan agen (Claude, Cursor, Windsurf, VS Code Copilot, JetBrains AI Assistant/Junie, dan klien MCP lainnya) untuk membuat kueri dan, secara opsional, memodifikasi data di cluster Couchbase menggunakan bahasa alami.

Bagaimana cara menghubungkan Claude Desktop ke Couchbase? Instal server dengan uvx couchbase-mcp-server (atau jalankan dari sumber atau Docker), lalu tambahkan konfigurasinya ke claude_desktop_config.json Claude Desktop seperti yang ditunjukkan di Konfigurasi. Mulai ulang Claude Desktop dan ia akan mengambil alat baru.

Bisakah saya menggunakan ini dengan Couchbase Capella? Ya. Konfigurasi CB_CONNECTION_STRING/CB_USERNAME/CB_PASSWORD (atau sertifikat mTLS) yang sama berfungsi untuk cluster Couchbase Capella dan Couchbase Server yang dikelola sendiri.

Apakah aman membiarkan agen AI menulis ke database saya? Secara default, CB_MCP_READ_ONLY_MODE adalah true, sehingga semua operasi tulis — upsert/insert/replace/delete dokumen dan pernyataan SQL++ yang memodifikasi data — dinonaktifkan dan alat tulis bahkan tidak dimuat. Anda juga dapat menonaktifkan alat individual (lihat Menonaktifkan Alat) atau memerlukan konfirmasi pengguna yang eksplisit sebelum alat tertentu dijalankan (lihat Elicitation/Confirmation). Kontrol tingkat alat memandu perilaku LLM; izin RBAC pengguna Couchbase Anda tetap menjadi batas keamanan yang sebenarnya.

Bisakah saya menjalankan kueri bahasa alami terhadap data saya tanpa menulis SQL++ sendiri? Ya — ajukan pertanyaan kepada asisten AI Anda dalam bahasa Inggris sederhana (misalnya "tunjukkan 10 pesanan terbaru di atas $100") dan ia dapat menerjemahkannya menjadi kueri SQL++ menggunakan alat run_sql_plus_plus_query. Anda juga dapat meminta asisten untuk explain_sql_plus_plus_query kueri atau meminta penasihat indeks untuk rekomendasi. Apa perbedaan antara transport STDIO, Streamable HTTP, dan SSE? STDIO digunakan untuk satu klien MCP lokal (misalnya Claude Desktop) yang meluncurkan server sebagai subproses. Streamable HTTP memungkinkan beberapa klien berbagi satu instance server yang berjalan melalui HTTP, dan mendukung OAuth 2.1. SSE adalah transport HTTP yang lebih lama, kini tidak digunakan lagi oleh spesifikasi MCP dan digantikan oleh Streamable HTTP — lihat Streamable HTTP Transport Mode.

Apakah ini didukung secara resmi oleh Couchbase? Proyek ini dikelola oleh komunitas Couchbase — lihat Support Policy. Dukungan enterprise tersedia secara terpisah melalui Couchbase AI Data Plane.

Berkontribusi

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

Jika Anda membutuhkan bantuan, menemukan bug, atau ingin menyumbangkan 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 pengaturan pengembang yang lengkap, termasuk:

• Pengaturan lingkungan pengembangan dengan uv
• Linting dan pemformatan kode dengan Ruff
• Instalasi 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 dikelola 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 GitHub.

Kolaborasi Anda membantu kita semua maju bersama — terima kasih!