Couchbase MCP Server

Server MCP Couchbase

Server MCP Couchbase adalah Server MCP yang dihosting sendiri yang memungkinkan agen AI terhubung dan berinteraksi dengan data di klaster Couchbase, baik yang dihosting di Capella maupun yang dikelola sendiri. Server ini menyediakan alat di berbagai kategori termasuk Kesehatan Klaster, Skema Data, Key-Value, Kueri, dan Performa — dengan kontrol keamanan melalui mode hanya-baca dan penonaktifan alat secara terperinci. Server ini mendukung transportasi STDIO dan HTTP Streamable.

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 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 klaster

Alat penemuan model data & skema

Alat operasi KV dokumen

Alat kueri dan pengindeksan

Alat analisis performa kueri

Prasyarat

• Python 3.10 atau lebih tinggi.
• Klaster Couchbase yang berjalan. Cara termudah untuk memulai adalah menggunakan Capella tingkat gratis, yang merupakan versi server Couchbase yang dikelola sepenuhnya. Anda dapat mengikuti petunjuk untuk mengimpor salah satu set data sampel atau mengimpor data Anda sendiri.
• uv terinstal untuk menjalankan server.
• Klien MCP seperti Claude Desktop terinstal untuk menghubungkan server ke Claude. Petunjuk disediakan untuk Claude Desktop dan Cursor. Klien MCP lainnya juga dapat digunakan.

Konfigurasi

Server MCP dapat dijalankan baik dari paket PyPI yang sudah dibangun sebelumnya atau dari sumber menggunakan uv.

Menjalankan dari PyPI

Kami menerbitkan paket PyPI yang sudah dibangun sebelumnya untuk server MCP.

Konfigurasi Server menggunakan Paket yang Sudah Dibangun 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.

Kloning 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 sudah 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 dan Query) dinonaktifkan. Alat tulis KV (upsert, insert, replace, delete) tidak dimuat dan tidak akan tersedia untuk LLM, dan kueri SQL++ yang memodifikasi data atau struktur diblokir.
• Saat false: Alat tulis KV 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 serta 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 (direkomendasikan 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 otoritatif.

Misalnya, meskipun 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.

Elisitasi/Konfirmasi untuk Panggilan Alat

Anda dapat memerlukan konfirmasi pengguna eksplisit untuk alat tertentu sebelum eksekusi (ketika 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

Ketika alat yang terdaftar dipanggil:

• Jika klien mendukung elisitasi, pengguna diminta untuk mengonfirmasi.
• Jika klien tidak mendukung elisitasi, alat akan 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 default. Pencatatan 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.
• CB_MCP_LOG_SINKS — ke mana log pergi: stderr (default), file berputar per-level (file), atau keduanya. Dengan file, satu file ditulis per level (misalnya mcp_server.info.log dan mcp_server.error.log) di jalur yang ditetapkan oleh CB_MCP_LOG_FILE.

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

Untuk detail lebih lanjut, lihat dokumentasi.

Konfigurasi Spesifik Klien

Mode Transport HTTP Streamable

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

Catatan: Otorisasi OAuth 2.1 didukung pada transport ini. Lihat Otorisasi OAuth 2.1. Tanpa OAuth 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 http streamable 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 ditinggalkan oleh MCP. Kami memiliki dukungan untuk HTTP Streamable.

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 berjalan dengan --transport=http, server MCP dapat bertindak sebagai server sumber daya OAuth 2.1: server memvalidasi JWT pembawa masuk terhadap JWKS penyedia identitas Anda. Ini agnostik 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 hanya aktif ketika ketiga CB_MCP_OAUTH_JWT_JWKS_URI, CB_MCP_OAUTH_JWT_ISSUER, dan CB_MCP_OAUTH_JWT_AUDIENCE diatur; hanya mengatur beberapa di antaranya akan gagal saat startup.
• Mengatur CB_MCP_OAUTH_MCP_BASE_URL juga menerbitkan Metadata Sumber Daya Terlindungi RFC 9728 sehingga klien yang sadar 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 mutasi KV). Akses penuh memerlukan keduanya.

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 sudah dibangun dapat ditemukan di DockerHub atau ditarik melalui docker pull docker.io/couchbase/mcp-server:latest.

Atau, kami adalah bagian dari Docker MCP Catalog.

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

Server MCP dapat dijalankan dengan variabel lingkungan yang digunakan untuk mengonfigurasi pengaturan Couchbase. Variabel lingkungannya 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 mode transport HTTP seperti http dan sse.

Docker: Konfigurasi Klien MCP

Image 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, string koneksi Anda kemungkinan 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 LLM

• Penggunaan model bahasa besar dan teknologi serupa mengandung 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 bertanggung jawab penuh untuk menentukan apakah akan menggunakan model bahasa besar dan teknologi terkait, serta untuk mematuhi ketentuan lisensi, ketentuan penggunaan, dan kebijakan organisasi Anda yang mengatur penggunaannya.

Tips Pemecahan Masalah

• Pastikan path ke repositori server MCP Anda sudah benar dalam konfigurasi jika menjalankan dari sumber.
• Verifikasi bahwa string koneksi Couchbase, nama pengguna database, kata sandi, atau path ke sertifikat sudah benar.
• Jika menggunakan Couchbase Capella, pastikan kluster dapat diakses dari mesin tempat server MCP berjalan.
• Periksa apakah 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 path absolut ke uv/uvx di bidang command dalam konfigurasi.
• Periksa log untuk setiap kesalahan atau peringatan yang mungkin mengindikasikan masalah dengan server MCP. Lokasi log bergantung pada klien MCP Anda.
• Jika Anda mengamati masalah saat menjalankan server MCP dari sumber setelah memperbarui repositori server MCP 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 alat tersebut dapat dipanggil terhadap kluster demo Couchbase.

1. Ekspor kredensial kluster demo:
   • CB_CONNECTION_STRING
   • CB_USERNAME
   • CB_PASSWORD
   • Opsional: CB_MCP_TEST_BUCKET (bucket untuk diperiksa 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 berkontribusi perbaikan, tempat terbaik untuk melakukannya adalah di sini — dengan membuka isu GitHub.

Untuk Pengembang

Jika Anda tertarik untuk berkontribusi kode atau menyiapkan lingkungan pengembangan:

📖 Lihat CONTRIBUTING.md untuk instruksi pengaturan pengembang yang komprehensif, termasuk:

• Pengaturan lingkungan pengembangan dengan uv
• Linting dan pemformatan kode dengan Ruff
• Instalasi hook pre-commit
• Gambaran umum 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 repo ini dan akan berusaha menyelesaikan masalah dengan upaya terbaik.

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

Kolaborasi Anda membantu kita semua maju bersama — terima kasih!